Merge pull request #10 from ThomasWaldmann/doc-misc

docs: install docs, faq improvements, other minor changes

docs/faq.rst

@@ -7,10 +7,13 @@ Frequently asked questions
 Which platforms are supported?
     Currently Linux, FreeBSD and MacOS X are supported.
 
+    You can try your luck on other POSIX-like systems, like Cygwin,
+    other BSDs, etc. but they are not officially supported.
 
 Can I backup VM disk images?
     Yes, the :ref:`deduplication <deduplication_def>` technique used by |project_name|
     makes sure only the modified parts of the file are stored.
+    Also, we have optional simple sparse file support for extract.
 
 Can I backup from multiple servers into a single repository?
     Yes, but in order for the deduplication used by Borg to work, it
@@ -62,7 +65,13 @@ How can I specify the encryption passphrase programmatically?
 When backing up to remote servers, is data encrypted before leaving the local machine, or do I have to trust that the remote server isn't malicious?
     Yes, everything is encrypted before leaving the local machine.
 
-If a backup stops mid-way, does the already-backed-up data stay there? I.e. does Borg resume backups?
+If a backup stops mid-way, does the already-backed-up data stay there? I.e. does |project_name| resume backups?
     Yes, during a backup a special checkpoint archive named ``<archive-name>.checkpoint`` is saved every 5 minutes
     containing all the data backed-up until that point. This means that at most 5 minutes worth of data needs to be
     retransmitted if a backup needs to be restarted.
+
+If it crashes with a UnicodeError, what can I do?
+    Check if your encoding is set correctly. For most POSIX-like systems, try::
+
+    export LANG=en_US.UTF-8  # or similar, important is correct charset
+

docs/index.rst

@@ -2,10 +2,16 @@
 
 Welcome to Borg
 ================
-|project_name| is a deduplicating backup program written in Python.
+|project_name| is a deduplicating and compressing backup program.
+Optionally, it also supports authenticated encryption.
+
 The main goal of |project_name| is to provide an efficient and secure way
 to backup data. The data deduplication technique used makes |project_name|
-suitable for daily backups since only the changes are stored.
+suitable for daily backups since only the changes are stored. The authenticated
+encryption makes it suitable for backups to not fully trusted targets.
+
+|project_name| is written in Python (with a little bit of Cython and C for
+the speed critical parts).
 
 
 Easy to use
@@ -52,9 +58,11 @@ User's Guide
 Getting help
 ============
 
-If you've found a bug or have a concrete feature request, you can add your bug
-report or feature request directly to the project's `issue tracker`_. For more
-general questions or discussions, a post to the mailing list is preferred.
+If you've found a bug or have a concrete feature request, please create a new
+ticket on the project's `issue tracker`_ (after checking whether someone else
+already has reported the same thing).
+
+For more general questions or discussions, IRC or mailing list are preferred.
 
 IRC
 ---

docs/installation.rst

@@ -4,62 +4,79 @@
 Installation
 ============
 
-|project_name| requires Python_ 3.2 or above to work. Even though Python 3 is
-not the default Python version on most Linux distributions, it is usually
-available as an optional install.
+|project_name| requires:
 
-Other dependencies:
-
-* `msgpack-python`_ >= 0.1.10
+* Python_ >= 3.2
 * OpenSSL_ >= 1.0.0
 * libacl_
+* some python dependencies, see install_requires in setup.py
+
+General notes
+-------------
+Even though Python 3 is not the default Python version on many systems, it is
+usually available as an optional install.
 
-The OpenSSL version bundled with Mac OS X and FreeBSD is most likey too old.
-Newer versions are available from homebrew_ on OS X and from FreeBSD ports.
+Virtualenv_ can be used to build and install |project_name| without affecting
+the system Python or requiring root access.
 
 The llfuse_ python package is also required if you wish to mount an
-archive as a FUSE filesystem.
+archive as a FUSE filesystem. Only FUSE >= 2.8.0 can support llfuse.
 
-Virtualenv_ can be used to build and install |project_name|
-without affecting the system Python or requiring root access.
+You only need Cython to compile the .pyx files to the respective .c files
+when using |project_name| code from git. For |project_name| releases, the .c
+files will be bundled.
 
-Common compilation pre-requisites
----------------------------------
+Platform notes
+--------------
+FreeBSD: You may need to get a recent enough OpenSSL version from FreeBSD ports.
 
-The following Debian packages are generally necessary to compile
-|project_name|, either through pip, the tarball or git::
+Mac OS X: You may need to get a recent enough OpenSSL version from homebrew_.
 
-  $ sudo apt-get install python3 python3-dev python3-msgpack python3-sphinx libssl-dev libacl1-dev
+Mac OS X: A recent enough FUSE implementation might be unavailable.
 
-Installing from PyPI using pip
-------------------------------
 
-To install |project_name| system-wide::
+Debian / Ubuntu installation (from git)
+---------------------------------------
+Note: this uses latest, unreleased development code from git.
+While we try not to break master, there are no guarantees on anything.
 
-  $ sudo pip3 install borgbackup
+Some of the steps detailled below might be useful also for non-git installs.
 
-To install it in a user-specific account::
+.. parsed-literal::
 
-  $ pip3 install --user borgbackup
+    # Python 3.x (>= 3.2) + Headers, Py Package Installer
+    apt-get install python3 python3-dev python3-pip
 
-Then add ``$HOME/.library/bin`` to your ``$PATH``.
+    # we need OpenSSL + Headers for Crypto
+    apt-get install libssl-dev openssl
 
-Installing from source tarballs
--------------------------------
-.. parsed-literal::
+    # ACL support Headers + Library
+    apt-get install libacl1-dev libacl1
 
-    $ curl -O :targz_url:`Borg`
-    $ tar -xvzf |package_filename|
-    $ cd |package_dirname|
-    $ sudo python3 setup.py install
+    # if you do not have gcc / make / etc. yet
+    apt-get install build-essential
 
-Installing from git
--------------------
-.. parsed-literal::
+    # optional: lowlevel FUSE py binding - to mount backup archives
+    apt-get install python3-llfuse fuse
+
+    # optional: for unit testing
+    apt-get install fakeroot
+
+    # install virtualenv tool, create and activate a virtual env
+    apt-get install python-virtualenv
+    virtualenv --python=python3 borg-env
+    source borg-env/bin/activate   # always do this before using!
+
+    # install some dependencies into virtual env
+    pip install cython  # to compile .pyx -> .c
+    pip install tox   # optional, for running unit tests
+    pip install sphinx  # optional, to build the docs
+
+    # get |project_name| from github, install it
+    git clone |git_url|
+    cd borg
+    pip install -e .  # in-place editable mode
 
-    $ git clone |git_url|
-    $ cd borg
-    $ sudo python3 setup.py install
+    # optional: run all the tests, on all supported Python versions
+    fakeroot -u tox
 
-Please note that when installing from git, Cython_ is required to generate some files that
-are normally bundled with the release tarball.

docs/quickstart.rst

@@ -68,18 +68,17 @@ A step by step example
 Automating backups
 ------------------
 
-The following example script backs up ``/home`` and
-``/var/www`` to a remote server. The script also uses the
-:ref:`borg_prune` subcommand to maintain a certain number
-of old archives::
+The following example script backs up ``/home`` and ``/var/www`` to a remote
+server. The script also uses the :ref:`borg_prune` subcommand to maintain a
+certain number of old archives::
 
     #!/bin/sh
     REPOSITORY=username@remoteserver.com:backup
 
     # Backup all of /home and /var/www except a few
     # excluded directories
-    borg create --stats                            \
-        $REPOSITORY::hostname-`date +%Y-%m-%d`      \
+    borg create --stats                             \
+        $REPOSITORY::`hostname`-`date +%Y-%m-%d`    \
         /home                                       \
         /var/www                                    \
         --exclude /home/*/.cache                    \
@@ -103,7 +102,7 @@ When repository encryption is enabled all data is encrypted using 256-bit AES_
 encryption and the integrity and authenticity is verified using `HMAC-SHA256`_.
 
 All data is encrypted before being written to the repository. This means that
-an attacker that manages to compromise the host containing an encrypted
+an attacker who manages to compromise the host containing an encrypted
 archive will not be able to access any of the data.
 
 |project_name| supports two different methods to derive the AES and HMAC keys.