--- /dev/null
+Addressbooks are commonly kept on a CardDAV server, where the individual
+contacts are represented as single vCard (`.vcf`) files. Supporting those files
+as a source format could facilitate integration between ikiwiki and address
+books, and allow linking wiki entries to people. With the plugin presented here
+and the [[calypso|http://keithp.com/blogs/calypso/]] server, that is easily
+possible.
+
+The idea was first presented on [[forum/debconf13 ikiwiki bof|DebConf13]] by
+[[chrysn]].
+
+Software involved
+=================
+
+* CardDAV server
+
+ ikiwiki generates its pages from the local file system. Using the
+ [[calypso|http://keithp.com/blogs/calypso/]] CardDAV/CalDAV server makes that
+ trivial, as it stores its contacts as plain files already (and under git
+ version control!).
+
+ The files can be pulled into ikiwiki in the form of an underlay.
+
+* Rendering VCF files
+
+ A python plugin called `vcf` has been published in chrysn's plugin repository
+ at `git://prometheus.amsuess.com/ikiwiki-plugins`. It supports contact images
+ (as `data:` URLs) as well as all the attributes Evolution generates, creates
+ external hyperlinks for those attributes that can be dereferenced (including
+ telephone numbers), and renders vCard categories into ikiwiki tags.
+
+ Python was chosen as a programming language due to the availability of the
+ [[`vobject`|http://vobject.skyhouseconsulting.com/]] python module and the
+ author's personal preference.
+
+* Linking to contacts
+
+ File names of vCard files are usually not usable
+ (`4FD53349-51280409-28AD50CB.vcf`). To make links like "`I've talked to
+ \[[John Doe]] about this`" possible, the [[todo/alias directive]] has to be
+ implemented in the same repository. (Work in progress.)
+
+Issues / Further development
+============================
+
+* The rendered output is currently a plain definition list, and could need some
+ theming and/or grouping.
+
+ The current implementation does not use templating, and instead generates
+ HTML directly in Python (with the help of the
+ [[MarkupSafe|https://pypi.python.org/pypi/MarkupSafe]] module). Due to the
+ [[limitations of the foreign language API|plugins/write/external]], ikiwiki's
+ regular templating can't be used anyway.
+
+* Addresses are rendered by `python-vcard` builtin address renderer (plus a
+ hack to get unicode out of it), and are not always most beautiful; moreover,
+ this kind of rendering is not themable.
+
+* The `paramlist` words in the vcards are plain dumped out after the respective
+ fields. That's unsuitable for theming, and would need localization.
+
+* In general, the plugin is not internationalized.
+
+* All VCF pages currently receive a 'Contact' tag. That needs configurability
+ and/or localization. In the same vein, prefix configuration for the category
+ taggings would be useful too.
+
+* The alias plugin is not ready yet.
+
+* vCards can not be edited. To be precise: vCards can be edited, but they show
+ vCard sources which are not suitable for user editing. Moreover, the changes
+ would be committed into the wiki main from the underlay, and not travel back.
+
+ Two approaches would make editing feasible, a relatively easy one and a
+ hard-but-wow-if-it-works one:
+
+ * Use a dedicated vCard editing online tool like CardDavMate, which accepts
+ URLs for editing (unlike CardDavMate). Ideally we would even hijack the
+ edit button on vCard pages to take the user to a proper editor.
+
+ * Have a simple edit mask for vCard objects. (It'd be ok if it was incomplete
+ with respect to fields, the vCard format is designed to make that
+ possible). That's related to the
+ [[forum/an alternative approach to structured data|structured data]] issue.
+
+ In such a setup, the vCard list would not go to an underlay, but rather to
+ a git checkout in a subdirectory or a submodule, from which the change
+ could then be pushed back to Calypso. (AFAIK, different git roots are not
+ supported in ikiwiki yet.)
+
+* Would such a renderer be useful for vCalendar too? (vCard and vCalendar only
+ differ in what they can represent, not in how they do it.)
+
+Status
+======
+
+The setup is currently usable, but just barely so. Once the basic issues are
+solved (aliases, parameters for tags, enhanced appearence), I will suggest this
+plugin for inclusion in ikiwiki.
+
+-- [[chrysn]]