# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1460999788 -7200
# Node ID 21e8e4fcc2ad42ea61bd2be0e6b56525dbc4b6eb
# Parent  b131dbbb2da22e4e97aed6a0a62666bbb6d39f24
Added some documentation.

diff -r b131dbbb2da2 -r 21e8e4fcc2ad README.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.txt	Mon Apr 18 19:16:28 2016 +0200
@@ -0,0 +1,66 @@
+Introduction
+============
+
+The fburl software provides an extension for Lightning/Iceowl (the calendar
+extension for Mozilla Thunderbird/Icedove) that can obtain free/busy URL
+details from LDAP directories registered as address books. Thus, when the
+free/busy dialogue is opened, availability information for event participants
+may be shown if their contact details are supplied by an LDAP directory, if
+those details include an FBURL property, and if that property refers to a
+valid iCalendar VFREEBUSY component residing on an accessible Web server.
+
+More information about FBURL can be found in the following document:
+
+http://tools.ietf.org/html/rfc2739
+
+Other Sources of Free/Busy Information
+======================================
+
+Although not currently supported by this software, FBURL information could be
+obtained from vCard objects:
+
+https://tools.ietf.org/html/rfc6350#section-6.9
+
+In Thunderbird, this would involve opening an address book and obtaining a
+card object (from a non-LDAP source) that can provide the FBURL property.
+Unfortunately, the built-in address books do not seem to support the FBURL
+property. Moreover, when vCard information is imported, properties such as
+FBURL that are not part of the traditional set of vCard properties are
+discarded.
+
+Although not directly related to FBURL and over-the-Web free/busy resource
+retrieval, such information may also be exchanged using iMIP and normal e-mail
+communications:
+
+https://tools.ietf.org/html/rfc6047
+
+Thunderbird supports iMIP for VEVENT and VTODO components but not for
+VFREEBUSY components. Support for VFREEBUSY would require received components
+to be recorded in a suitable repository so that they may then be consulted by
+a specific free/busy provider when scheduling events. The sending of VFREEBUSY
+components would involve access to the user's schedule and the construction of
+iCalendar output from such information. Control over free/busy sharing would
+need to be exercised, probably requiring configuration settings to indicate
+whether such information is sent along with other iMIP payloads and with whom
+such information may be shared.
+
+With iMIP, the effective "FBURL" of a contact would in fact be the e-mail
+address of that contact or, more accurately, the address expressed using the
+mailto URI scheme. Thus, wider support for FBURL in vCard-handling and in
+Thunderbird address books would let users indicate that they can expect
+free/busy information via iMIP from certain contacts and, in their own vCard
+details, that they will publish their own availability details via iMIP.
+
+Contact, Copyright and Licence Information
+==========================================
+
+See the following Web pages for more information about this work:
+
+http://hgweb.boddie.org.uk/fburl
+
+The author can be contacted at the following e-mail address:
+
+paul@boddie.org.uk
+
+Copyright and licence information can be found in the docs directory - see
+docs/COPYING.txt for more information.