Restructure supported.rst into tutorial subpages (#631)

* Restructure supported.rst into tutorial subpages

Fix #623

* Fix section headings and whitespace

* fix link

* Stylefix

README.rst

@@ -11,7 +11,7 @@ folder or file. The local data can then be accessed via a variety of programs_,
 none of which have to know or worry about syncing to a server.
 
 .. _storages: https://vdirsyncer.pimutils.org/en/latest/config.html#storages
-.. _programs: https://vdirsyncer.pimutils.org/en/stable/supported.html
+.. _programs: https://vdirsyncer.pimutils.org/en/latest/tutorials/
 
 It aims to be for CalDAV and CardDAV what `OfflineIMAP
 <http://offlineimap.org/>`_ is for IMAP.

docs/contributing.rst

@@ -58,7 +58,7 @@ Suggesting features
 If you're suggesting a feature, keep in mind that vdirsyncer tries not to be a
 full calendar or contacts client, but rather just the piece of software that
 synchronizes all the data. :doc:`Take a look at the documentation for software
-working with vdirsyncer <supported>`.
+working with vdirsyncer <tutorials/index>`.
 
 Submitting patches, pull requests
 =================================

docs/index.rst

@@ -8,7 +8,7 @@ vdirsyncer
 Vdirsyncer synchronizes your calendars and addressbooks between two
 :ref:`storages <storages>`. The most popular purpose is to synchronize a
 CalDAV/CardDAV server with a local folder or file. The local data can then be
-accessed via a variety of :doc:`programs <supported>`, none of which have to
+accessed via a variety of :doc:`programs <tutorials/index>`, none of which have to
 know or worry about syncing to a server.
 
 It aims to be for CalDAV and CardDAV what `OfflineIMAP
@@ -25,7 +25,6 @@ It aims to be for CalDAV and CardDAV what `OfflineIMAP
    keyring
    partial-sync
    config
-   supported
    tutorials/index
    problems
 

docs/supported.rst

@@ -1,280 +0,0 @@
-==================
-Supported Software
-==================
-
-Client applications
-===================
-
-The following software has been reported to work well with vdirsyncer, however,
-none of it is regularly tested.
-
-Calendars
----------
-
-- khal_, a CLI calendar application supporting :doc:`vdir <vdir>`. You can use
-  :storage:`filesystem` with it.
-
-- Many graphical calendar apps such as dayplanner_, Orage_ or rainlendar_ save
-  a calendar in a single ``.ics`` file. You can use :storage:`singlefile` with
-  those.
-
-.. _khal: http://lostpackets.de/khal/
-.. _dayplanner: http://www.day-planner.org/
-.. _Orage: http://www.kolumbus.fi/~w408237/orage/
-.. _rainlendar: http://www.rainlendar.net/
-
-Task/Todo managers
-------------------
-
-The iCalendar format also supports saving tasks in form of ``VTODO``-entries,
-with the same file extension as normal events: ``.ics``. All CalDAV servers
-support synchronizing tasks, vdirsyncer does too.
-
-- todoman_, a CLI task manager supporting :doc:`vdir <vdir>`. Its interface is
-  similar to the ones of Taskwarrior or the todo.txt CLI app. You can use
-  :storage:`filesystem` with it.
-
-.. _todoman: https://hugo.barrera.io/journal/2015/03/30/introducing-todoman/
-
-
-Contacts
---------
-
-- khard_, a commandline addressbook supporting :doc:`vdir <vdir>`.  You can use
-  :storage:`filesystem` with it.
-
-- contactquery.c_, a small program explicitly written for querying vdirs from
-  mutt.
-
-- mates_, a commandline addressbook supporting :doc:`vdir <vdir>`.
-
-- vdirel_, access :doc:`vdir <vdir>` contacts from Emacs.
-
-- Claws-Mail's addressbook can be fed by a ``.vcf`` file. See :ref:`here
-  <claws-mail-tutorial>` for a tutorial.
-
-.. _khard: https://github.com/scheibler/khard/
-.. _contactquery.c: https://github.com/t-8ch/snippets/blob/master/contactquery.c
-.. _mates: https://github.com/pimutils/mates.rs
-.. _vdirel: https://github.com/DamienCassou/vdirel
-
-.. _supported-servers:
-
-Supported servers
-=================
-
-CalDAV and CardDAV servers not listed here may work anyway.
-
-Radicale
---------
-
-Radicale_ is a very lightweight server, however, it intentionally doesn't
-implement the CalDAV and CardDAV standards completely, which might lead to
-issues even with very well-written clients. Apart from its non-conformity with
-standards, there are multiple other problems with its code quality and the way
-it is maintained. Consider using e.g. Xandikos_ instead.
-
-That said, vdirsyncer is continuously tested against the git version and the
-latest PyPI release of Radicale.
-
-- Vdirsyncer can't create collections on Radicale.
-- Radicale doesn't `support time ranges in the calendar-query of CalDAV
-  <https://github.com/Kozea/Radicale/issues/146>`_, so setting ``start_date``
-  and ``end_date`` for :storage:`caldav` will have no or unpredicted
-  consequences.
-
-- `Versions of Radicale older than 0.9b1 choke on RFC-conform queries for all
-  items of a collection <https://github.com/Kozea/Radicale/issues/143>`_.
-
-  You have to set ``item_types = ["VTODO", "VEVENT"]`` in
-  :storage:`caldav` for vdirsyncer to work with those versions.
-
-.. _Radicale: http://radicale.org/
-
-
-.. _owncloud_setup:
-
-ownCloud
---------
-
-Vdirsyncer is continuously tested against the latest version of ownCloud_::
-
-    [storage cal]
-    type = "caldav"
-    url = "https://example.com/remote.php/dav/"
-    username = ...
-    password = ...
-
-    [storage card]
-    type = "carddav"
-    url = "https://example.com/remote.php/dav/"
-    username = ...
-    password = ...
-
-- *Versions older than 7.0.0:* ownCloud uses SabreDAV, which had problems
-  detecting collisions and race-conditions. The problems were reported and are
-  fixed in SabreDAV's repo, and the corresponding fix is also in ownCloud since
-  7.0.0. See :gh:`16` for more information.
-
-.. _ownCloud: https://owncloud.org/
-
-nextCloud
----------
-
-Vdirsyncer is continuously tested against the latest version of nextCloud_::
-
-    [storage cal]
-    type = "caldav"
-    url = "https://nextcloud.example.com/"
-    username = ...
-    password = ...
-
-    [storage card]
-    type = "carddav"
-    url = "https://nextcloud.example.com/"
-
-- WebCAL-subscriptions can't be discovered by vdirsyncer. See `this relevant
-  issue <https://github.com/nextcloud/calendar/issues/63>`_.
-
-.. _nextCloud: https://nextcloud.com/
-
-
-FastMail
---------
-
-Vdirsyncer is irregularly tested against FastMail_. There are no known issues
-with it. `FastMail's support pages
-<https://www.fastmail.com/help/technical/servernamesandports.html>`_ provide
-the settings to use::
-
-    [storage cal]
-    type = "caldav"
-    url = "https://caldav.messagingengine.com/"
-    username = ...
-    password = ...
-
-    [storage card]
-    type = "carddav"
-    url = "https://carddav.messagingengine.com/"
-    username = ...
-    password = ...
-
-.. _FastMail: https://www.fastmail.com/
-
-.. _icloud_setup:
-
-iCloud
-------
-
-Vdirsyncer is regularly tested against iCloud_.
-
-::
-
-    [storage cal]
-    type = "caldav"
-    url = "https://caldav.icloud.com/"
-    username = ...
-    password = ...
-
-    [storage card]
-    type = "carddav"
-    url = "https://contacts.icloud.com/"
-    username = ...
-    password = ...
-
-Problems:
-
-- Vdirsyncer can't do two-factor auth with iCloud (there doesn't seem to be a
-  way to do two-factor auth over the DAV APIs) You'll need to use `app-specific
-  passwords <https://support.apple.com/en-us/HT204397>`_ instead.
-- iCloud has a few special requirements when creating collections. In principle
-  vdirsyncer can do it, but it is recommended to create them from an Apple
-  client (or the iCloud web interface).
-
-  - iCloud requires a minimum length of collection names.
-  - Calendars created by vdirsyncer cannot be used as tasklists.
-
-.. _iCloud: https://www.icloud.com/
-
-.. _davmail_setup:
-
-DavMail (Exchange, Outlook)
----------------------------
-
-DavMail_ is a proxy program that allows you to use Card- and CalDAV clients
-with Outlook. That allows you to use vdirsyncer with Outlook.
-
-In practice your success with DavMail may wildly vary. Depending on your
-Exchange server you might get confronted with weird errors of all sorts
-(including data-loss).
-
-**Make absolutely sure you use the latest DavMail**::
-
-    [storage outlook]
-    type = "caldav"
-    url = "http://localhost:1080/users/user@example.com/calendar/"
-    username = "user@example.com"
-    password = ...
-
-- Older versions of DavMail handle URLs case-insensitively. See :gh:`144`.
-- DavMail is handling malformed data on the Exchange server very poorly. In
-  such cases the `Calendar Checking Tool for Outlook
-  <https://www.microsoft.com/en-us/download/details.aspx?id=28786>`_ might
-  help.
-- In some cases, you may see errors about duplicate events. It may look
-  something like this::
-
-      error: my_calendar/calendar: Storage "my_calendar_remote/calendar" contains multiple items with the same UID or even content. Vdirsyncer will now abort the synchronization of this collection, because the fix for this is not clear; It could be the result of a badly behaving server. You can try running:
-      error:
-      error:     vdirsyncer repair my_calendar_remote/calendar
-      error:
-      error: But make sure to have a backup of your data in some form. The offending hrefs are:
-      [...]
-
-  In order to fix this, you can try the Remove-DuplicateAppointments.ps1_
-  PowerShell script that Microsoft has come up with in order to remove duplicates.
-
-.. _DavMail: http://davmail.sourceforge.net/
-.. _Remove-DuplicateAppointments.ps1: https://blogs.msdn.microsoft.com/emeamsgdev/2015/02/12/powershell-remove-duplicate-calendar-appointments/
-
-Baikal
-------
-
-Vdirsyncer is continuously tested against the latest version of Baikal_.
-
-- Baikal up to ``0.2.7`` also uses an old version of SabreDAV, with the same
-  issue as ownCloud, see :gh:`160`. This issue is fixed in later versions.
-
-.. _Baikal: http://baikal-server.com/
-
-Google
-------
-
-Using vdirsyncer with Google Calendar is possible as of 0.10, but it is not
-tested frequently. You can use :storage:`google_contacts` and
-:storage:`google_calendar`.
-
-For more information see :gh:`202` and :gh:`8`.
-
-Xandikos
---------
-
-Xandikos_ is a lightweight, yet complete CalDAV and CardDAV server, backed by
-git. Vdirsyncer is continuously tested against its latest version.
-
-After running ``./bin/xandikos --defaults -d $HOME/dav``, you should be able to
-point vdirsyncer against the root of Xandikos like this::
-
-    [storage cal]
-    type = "caldav"
-    url = "https://xandikos.example.com/"
-    username = ...
-    password = ...
-
-    [storage card]
-    type = "carddav"
-    url = "https://xandikos.example.com/"
-    username = ...
-    password = ...
-
-.. _Xandikos: https://github.com/jelmer/xandikos

docs/tutorial.rst

@@ -90,7 +90,7 @@ However, if new collections are created on the server, it will not
 automatically start synchronizing those [2]_. You need to run ``vdirsyncer
 discover`` again to re-fetch this list instead.
 
-.. [1] You'll want to :doc:`use a helper program for this <supported>`.
+.. [1] You'll want to :doc:`use a helper program for this <tutorials/index>`.
 
 .. [2] Because collections are added rarely, and checking for this case before
    every synchronization isn't worth the overhead.

docs/tutorials/baikal.rst

@@ -0,0 +1,10 @@
+======
+Baikal
+======
+
+Vdirsyncer is continuously tested against the latest version of Baikal_.
+
+- Baikal up to ``0.2.7`` also uses an old version of SabreDAV, with the same
+  issue as ownCloud, see :gh:`160`. This issue is fixed in later versions.
+
+.. _Baikal: http://baikal-server.com/

docs/tutorials/davmail.rst

@@ -0,0 +1,41 @@
+.. _davmail_setup:
+
+===========================
+DavMail (Exchange, Outlook)
+===========================
+
+DavMail_ is a proxy program that allows you to use Card- and CalDAV clients
+with Outlook. That allows you to use vdirsyncer with Outlook.
+
+In practice your success with DavMail may wildly vary. Depending on your
+Exchange server you might get confronted with weird errors of all sorts
+(including data-loss).
+
+**Make absolutely sure you use the latest DavMail**::
+
+    [storage outlook]
+    type = "caldav"
+    url = "http://localhost:1080/users/user@example.com/calendar/"
+    username = "user@example.com"
+    password = ...
+
+- Older versions of DavMail handle URLs case-insensitively. See :gh:`144`.
+- DavMail is handling malformed data on the Exchange server very poorly. In
+  such cases the `Calendar Checking Tool for Outlook
+  <https://www.microsoft.com/en-us/download/details.aspx?id=28786>`_ might
+  help.
+- In some cases, you may see errors about duplicate events. It may look
+  something like this::
+
+      error: my_calendar/calendar: Storage "my_calendar_remote/calendar" contains multiple items with the same UID or even content. Vdirsyncer will now abort the synchronization of this collection, because the fix for this is not clear; It could be the result of a badly behaving server. You can try running:
+      error:
+      error:     vdirsyncer repair my_calendar_remote/calendar
+      error:
+      error: But make sure to have a backup of your data in some form. The offending hrefs are:
+      [...]
+
+  In order to fix this, you can try the Remove-DuplicateAppointments.ps1_
+  PowerShell script that Microsoft has come up with in order to remove duplicates.
+
+.. _DavMail: http://davmail.sourceforge.net/
+.. _Remove-DuplicateAppointments.ps1: https://blogs.msdn.microsoft.com/emeamsgdev/2015/02/12/powershell-remove-duplicate-calendar-appointments/

docs/tutorials/fastmail.rst

@@ -0,0 +1,22 @@
+========
+FastMail
+========
+
+Vdirsyncer is irregularly tested against FastMail_. There are no known issues
+with it. `FastMail's support pages
+<https://www.fastmail.com/help/technical/servernamesandports.html>`_ provide
+the settings to use::
+
+    [storage cal]
+    type = "caldav"
+    url = "https://caldav.messagingengine.com/"
+    username = ...
+    password = ...
+
+    [storage card]
+    type = "carddav"
+    url = "https://carddav.messagingengine.com/"
+    username = ...
+    password = ...
+
+.. _FastMail: https://www.fastmail.com/

docs/tutorials/google.rst

@@ -0,0 +1,9 @@
+======
+Google
+======
+
+Using vdirsyncer with Google Calendar is possible as of 0.10, but it is not
+tested frequently. You can use :storage:`google_contacts` and
+:storage:`google_calendar`.
+
+For more information see :gh:`202` and :gh:`8`.

docs/tutorials/icloud.rst

@@ -0,0 +1,35 @@
+.. _icloud_setup:
+
+======
+iCloud
+======
+
+Vdirsyncer is regularly tested against iCloud_.
+
+::
+
+    [storage cal]
+    type = "caldav"
+    url = "https://caldav.icloud.com/"
+    username = ...
+    password = ...
+
+    [storage card]
+    type = "carddav"
+    url = "https://contacts.icloud.com/"
+    username = ...
+    password = ...
+
+Problems:
+
+- Vdirsyncer can't do two-factor auth with iCloud (there doesn't seem to be a
+  way to do two-factor auth over the DAV APIs) You'll need to use `app-specific
+  passwords <https://support.apple.com/en-us/HT204397>`_ instead.
+- iCloud has a few special requirements when creating collections. In principle
+  vdirsyncer can do it, but it is recommended to create them from an Apple
+  client (or the iCloud web interface).
+
+  - iCloud requires a minimum length of collection names.
+  - Calendars created by vdirsyncer cannot be used as tasklists.
+
+.. _iCloud: https://www.icloud.com/

docs/tutorials/index.rst

@@ -5,10 +5,59 @@ Other tutorials
 The following section contains tutorials not explicitly about any particular
 core function of vdirsyncer. They usually show how to integrate vdirsyncer with
 third-party software. Because of that, it may be that the information regarding
-that other software may only apply to specific versions of them.
+that other software only applies to specific versions of them.
+
+.. note::
+    Please :doc:`contribute </contributing>` your own tutorials too!  Pages are
+    often only stubs and are lacking full examples.
+
+Ćlient applications
+===================
 
 .. toctree::
     :maxdepth: 1
 
     claws-mail
     systemd-timer
+    todoman
+
+Further applications, with missing pages:
+
+- khal_, a CLI calendar application supporting :doc:`vdir </vdir>`. You can use
+  :storage:`filesystem` with it.
+- Many graphical calendar apps such as dayplanner_, Orage_ or rainlendar_ save
+  a calendar in a single ``.ics`` file. You can use :storage:`singlefile` with
+  those.
+- khard_, a commandline addressbook supporting :doc:`vdir </vdir>`.  You can use
+  :storage:`filesystem` with it.
+- contactquery.c_, a small program explicitly written for querying vdirs from
+  mutt.
+- mates_, a commandline addressbook supporting :doc:`vdir </vdir>`.
+- vdirel_, access :doc:`vdir </vdir>` contacts from Emacs.
+
+.. _khal: http://lostpackets.de/khal/
+.. _dayplanner: http://www.day-planner.org/
+.. _Orage: http://www.kolumbus.fi/~w408237/orage/
+.. _rainlendar: http://www.rainlendar.net/
+.. _khard: https://github.com/scheibler/khard/
+.. _contactquery.c: https://github.com/t-8ch/snippets/blob/master/contactquery.c
+.. _mates: https://github.com/pimutils/mates.rs
+.. _vdirel: https://github.com/DamienCassou/vdirel
+
+.. _supported-servers:
+
+Servers
+=======
+
+.. toctree::
+    :maxdepth: 1
+
+    baikal
+    davmail
+    fastmail
+    google
+    icloud
+    nextcloud
+    owncloud
+    radicale
+    xandikos

docs/tutorials/nextcloud.rst

@@ -0,0 +1,20 @@
+=========
+nextCloud
+=========
+
+Vdirsyncer is continuously tested against the latest version of nextCloud_::
+
+    [storage cal]
+    type = "caldav"
+    url = "https://nextcloud.example.com/"
+    username = ...
+    password = ...
+
+    [storage card]
+    type = "carddav"
+    url = "https://nextcloud.example.com/"
+
+- WebCAL-subscriptions can't be discovered by vdirsyncer. See `this relevant
+  issue <https://github.com/nextcloud/calendar/issues/63>`_.
+
+.. _nextCloud: https://nextcloud.com/

docs/tutorials/owncloud.rst

@@ -0,0 +1,26 @@
+.. _owncloud_setup:
+
+========
+ownCloud
+========
+
+Vdirsyncer is continuously tested against the latest version of ownCloud_::
+
+    [storage cal]
+    type = "caldav"
+    url = "https://example.com/remote.php/dav/"
+    username = ...
+    password = ...
+
+    [storage card]
+    type = "carddav"
+    url = "https://example.com/remote.php/dav/"
+    username = ...
+    password = ...
+
+- *Versions older than 7.0.0:* ownCloud uses SabreDAV, which had problems
+  detecting collisions and race-conditions. The problems were reported and are
+  fixed in SabreDAV's repo, and the corresponding fix is also in ownCloud since
+  7.0.0. See :gh:`16` for more information.
+
+.. _ownCloud: https://owncloud.org/

docs/tutorials/radicale.rst

@@ -0,0 +1,26 @@
+========
+Radicale
+========
+
+Radicale_ is a very lightweight server, however, it intentionally doesn't
+implement the CalDAV and CardDAV standards completely, which might lead to
+issues even with very well-written clients. Apart from its non-conformity with
+standards, there are multiple other problems with its code quality and the way
+it is maintained. Consider using e.g. :doc:`xandikos` instead.
+
+That said, vdirsyncer is continuously tested against the git version and the
+latest PyPI release of Radicale.
+
+- Vdirsyncer can't create collections on Radicale.
+- Radicale doesn't `support time ranges in the calendar-query of CalDAV
+  <https://github.com/Kozea/Radicale/issues/146>`_, so setting ``start_date``
+  and ``end_date`` for :storage:`caldav` will have no or unpredicted
+  consequences.
+
+- `Versions of Radicale older than 0.9b1 choke on RFC-conform queries for all
+  items of a collection <https://github.com/Kozea/Radicale/issues/143>`_.
+
+  You have to set ``item_types = ["VTODO", "VEVENT"]`` in
+  :storage:`caldav` for vdirsyncer to work with those versions.
+
+.. _Radicale: http://radicale.org/

docs/tutorials/todoman.rst

@@ -0,0 +1,13 @@
+=======
+Todoman
+=======
+
+The iCalendar format also supports saving tasks in form of ``VTODO``-entries,
+with the same file extension as normal events: ``.ics``. Many CalDAV servers
+support synchronizing tasks, vdirsyncer does too.
+
+todoman_ is a CLI task manager supporting :doc:`vdir </vdir>`. Its interface is
+similar to the ones of Taskwarrior or the todo.txt CLI app. You can use
+:storage:`filesystem` with it.
+
+.. _todoman: https://hugo.barrera.io/journal/2015/03/30/introducing-todoman/

docs/tutorials/xandikos.rst

@@ -0,0 +1,23 @@
+========
+Xandikos
+========
+
+Xandikos_ is a lightweight, yet complete CalDAV and CardDAV server, backed by
+git. Vdirsyncer is continuously tested against its latest version.
+
+After running ``./bin/xandikos --defaults -d $HOME/dav``, you should be able to
+point vdirsyncer against the root of Xandikos like this::
+
+    [storage cal]
+    type = "caldav"
+    url = "https://xandikos.example.com/"
+    username = ...
+    password = ...
+
+    [storage card]
+    type = "carddav"
+    url = "https://xandikos.example.com/"
+    username = ...
+    password = ...
+
+.. _Xandikos: https://github.com/jelmer/xandikos