From 85bbcc718f79f9eae252efbc99526cb74d3606f2 Mon Sep 17 00:00:00 2001
From: Markus Unterwaditzer <markus@unterwaditzer.net>
Date: Wed, 4 Jun 2014 21:39:06 +0200
Subject: [PATCH] Add vdir spec to vdirsyncer docs

---
 docs/index.rst                   |  1 +
 docs/vdir.rst                    | 63 ++++++++++++++++++++++++++++++++
 vdirsyncer/storage/filesystem.py |  5 +--
 3 files changed, 66 insertions(+), 3 deletions(-)
 create mode 100644 docs/vdir.rst

diff --git a/docs/index.rst b/docs/index.rst
index f3e0621..e99067f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -21,4 +21,5 @@ Table of Contents
    server_support
    troubleshooting
    changelog
+   vdir
    license
diff --git a/docs/vdir.rst b/docs/vdir.rst
new file mode 100644
index 0000000..c552d50
--- /dev/null
+++ b/docs/vdir.rst
@@ -0,0 +1,63 @@
+=======================
+The vdir Storage Format
+=======================
+
+This document describes a standard for storing calendars and contacts on a
+filesystem, with the main goal of being easy to implement.
+
+Basic Structure
+===============
+
+The main folder (root) contains an arbitrary number of subfolders
+(collections), which contain only files (items). Synonyms for "collection" may
+be "addressbook" or "calendar".
+
+An item is:
+
+- A vCard_ file, in which case the file extension *must* be `.vcf`, *or*
+- An iCalendar_ file, in which case the file extension *must* be `.ics`.
+
+An item *should* contain a ``UID`` property as described by the vCard and
+iCalendar standards.
+
+The filename *must* consist of the ``ident``, followed by the file extension.
+The ``ident`` is either the ``UID``, if the item has one, else a string with
+similar properties as the ``UID``:
+
+   Type name: UID
+
+   Type purpose: To specify a value that represents a globally unique
+   identifier corresponding to the individual or resource associated
+   with the vCard.
+
+   -- The vCard_ RFC
+
+One reason this format was chosen is due to its compatibility with the CardDAV_
+and CalDAV_ standards.
+
+.. _vCard: https://tools.ietf.org/html/rfc6350
+.. _iCalendar: https://tools.ietf.org/html/rfc5545
+.. _CardDAV: http://tools.ietf.org/html/rfc6352
+.. _CalDAV: http://tools.ietf.org/search/rfc4791
+
+Writing to vdirs
+================
+
+Creating and modifying items *should* happen atomically_.
+
+Writing to a temporary file on the same physical device, and then moving it to
+the appropriate location is usually a very effective solution. For this
+purpose, files with the extension ``.tmp`` may be created inside collections.
+
+When changing an item, the original filename *must* be used.
+
+.. _atomically: https://en.wikipedia.org/wiki/Atomicity_%28programming%29
+
+Reading from vdirs
+==================
+
+- Any file ending with the ``.tmp`` or no file extension *must not* be treated
+  as an item.
+
+- The ``ident`` part of the filename *should not* be parsed to improve the
+  speed of item lookup.
diff --git a/vdirsyncer/storage/filesystem.py b/vdirsyncer/storage/filesystem.py
index a14065f..055f74a 100644
--- a/vdirsyncer/storage/filesystem.py
+++ b/vdirsyncer/storage/filesystem.py
@@ -22,9 +22,8 @@ class FilesystemStorage(Storage):
 
     '''
     Saves each item in its own file, given a directory. Can be used with `khal
-    <http://lostpackets.de/khal/>`_. See `vdir
-    <https://github.com/untitaker/vdir>`_ for a more formal description of the
-    format. Usable as ``filesystem`` in the config file.
+    <http://lostpackets.de/khal/>`_. See :doc:`vdir` for a more formal
+    description of the format. Usable as ``filesystem`` in the config file.
 
     :param path: Absolute path to a vdir or collection, depending on the
         collection parameter (see :py:class:`vdirsyncer.storage.base.Storage`).