From 5539ec26e90c5aca58e84e827e7e7fa20f3e06e2 Mon Sep 17 00:00:00 2001
From: Markus Unterwaditzer <markus@unterwaditzer.net>
Date: Sat, 13 Sep 2014 20:36:32 +0200
Subject: [PATCH] Recommend system packages over pip

Including pkgsrc package by @0-wiz-0 and AUR package by @hobarrera.
---
 README.rst        | 18 +++++++-----------
 docs/tutorial.rst | 24 +++++++++++++++++++++---
 2 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/README.rst b/README.rst
index 6f4da79..dfbb94c 100644
--- a/README.rst
+++ b/README.rst
@@ -15,19 +15,15 @@ It aims to be for CalDAV and CardDAV what `OfflineIMAP
 .. image:: https://coveralls.io/repos/untitaker/vdirsyncer/badge.png?branch=master
     :target: https://coveralls.io/r/untitaker/vdirsyncer?branch=master
 
-How to use
-==========
+Installation and usage
+======================
 
-vdirsyncer requires Python >= 2.7 or Python >= 3.3.
+If you already have it installed and want to quickly configure it, copy the
+``example.cfg`` to ``~/.vdirsyncer/config`` and edit it.
 
-As all Python packages, vdirsyncer can be installed with ``pip``::
-
-    pip install --user vdirsyncer
-
-Then copy ``example.cfg`` to ``~/.vdirsyncer/config`` and edit it.
-
-Run ``vdirsyncer --help`` and check out `the documentation
-<https://vdirsyncer.readthedocs.org/>`_.
+If that method doesn't work for you or you want a deeper understanding of what
+you just did, check out `the tutorial
+<https://vdirsyncer.readthedocs.org/en/latest/tutorial.html>`_.
 
 How to run the tests
 ====================
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index 9fd0ba2..1983924 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -5,11 +5,29 @@ Tutorial
 Installation
 ============
 
-- Make sure you have Python 2.7+ or Python 3.3+ installed.
+Vdirsyncer requires Python 2.7+ or 3.3+.
 
-- ``pip install --user vdirsyncer``
+Unless you want to contribute to vdirsyncer, you should use the packages from
+your distribution:
 
-- Check if the ``vdirsyncer`` command is available.
+- `AUR package for ArchLinux <https://aur.archlinux.org/packages/vdirsyncer>`_.
+- `pkgsrc <http://pkgsrc.se/time/py-vdirsyncer>`_.
+
+If your distribution doesn't provide a package for vdirsyncer, you still can
+use Python's package manager PIP. You'll have to check that a compatible
+version of Python is installed (see above), and then run::
+
+    pip install --user vdirsyncer
+
+This will install vdirsyncer and its dependencies into your home directory,
+presumably into ``~/local/lib/pythonX.X/``, and an executable under
+``~/.local/bin/``. You then can uninstall vdirsyncer with ``pip uninstall
+vdirsyncer``, but this will leave vdirsyncer's dependencies on your system,
+whose files you'll have to remove manually from the mentioned directories. You
+could check out pipsi_, but that one is a quite new tool. You should always
+prefer the packages of your distribution over this method.
+
+.. _pipsi:: https://github.com/mitsuhiko/pipsi
 
 Configuration
 =============