Merge pull request #32 from jdchristensen/docs2

Docs2: update lots of documentation

README.rst

@@ -1,13 +1,13 @@
 What is Attic?
 --------------
-Attic is a deduplicating backup program. The main goal of attic is to provide
+Attic is a deduplicating backup program. The main goal of Attic is to provide
 an efficient and secure way to backup data. The data deduplication
-technique used makes Attic suitable for daily backups since only actual changes
+technique used makes Attic suitable for daily backups since only changes
 are stored.
 
 Easy to use
 ~~~~~~~~~~~
-Initialze backup repository and create a backup archive::
+Initialize backup repository and create a backup archive::
 
     $ attic init /usbdrive/my-backup.attic
     $ attic create -v /usbdrive/my-backup.attic::documents ~/Documents
@@ -25,8 +25,8 @@ Optional data encryption
     and authenticity is verified using HMAC-SHA256.
 
 Off-site backups
-    attic can store data on any remote host accessible over SSH as long as
-    attic is installed.
+    Attic can store data on any remote host accessible over SSH.  This is
+    most efficient if Attic is also installed on the remote host.
 
 Backups mountable as filesystems
     Backup archives are mountable as userspace filesystems for easy backup
@@ -34,8 +34,9 @@ Backups mountable as filesystems
 
 What do I need?
 ---------------
-Attic requires Python 3.2 or above to work. Besides Python attic also requires 
+Attic requires Python 3.2 or above to work. Besides Python, Attic also requires 
 msgpack-python and sufficiently recent OpenSSL (>= 1.0.0).
+In order to mount archives as filesystems, llfuse is required.
 
 How do I install it?
 --------------------
@@ -45,8 +46,8 @@ How do I install it?
 
 Where are the docs?
 -------------------
-Go to https://pythonhosted.org/Attic/ for a prebuilt version of the docs. You
-can also build them yourself form the docs folder.
+Go to https://pythonhosted.org/Attic/ for a prebuilt version of the documentation.
+You can also build it yourself from the docs folder.
 
 Where are the tests?
 --------------------

attic/archiver.py

@@ -450,8 +450,22 @@ class Archiver:
                                type=location_validator(archive=True),
                                help='archive to display information about')
 
+        prune_epilog = '''The prune command prunes a repository by deleting archives
+        not matching any of the specified retention options. This command is normally
+        used by automated backup scripts wanting to keep a certain number of historic
+        backups. As an example, "-d 7" means to keep the latest backup on each day
+        for 7 days. Days without backups do not count towards the total. The rules
+        are applied from hourly to yearly, and backups selected by previous rules do
+        not count towards those of later rules. Dates and times are interpreted in
+        the local timezone, and weeks go from Monday to Sunday. Specifying a
+        negative number of archives to keep means that there is no limit. If a
+        prefix is set with -p, then only archives that start with the prefix are
+        considered for deletion and only those archives count towards the totals
+        specified by the rules.'''
+
         subparser = subparsers.add_parser('prune', parents=[common_parser],
-                                          description=self.do_prune.__doc__)
+                                          description=self.do_prune.__doc__,
+                                          epilog=prune_epilog)
         subparser.set_defaults(func=self.do_prune)
         subparser.add_argument('-H', '--hourly', dest='hourly', type=int, default=0,
                                help='number of hourly archives to keep')

docs/global.rst.inc

@@ -13,6 +13,7 @@
 .. _OpenSSL: https://www.openssl.org/
 .. _Python: http://www.python.org/
 .. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/
+.. _llfuse: https://pypi.python.org/pypi/llfuse/
 .. _homebrew: http://mxcl.github.io/homebrew/
 .. _issue tracker: https://github.com/jborg/attic/issues
 .. _userspace filesystems: https://en.wikipedia.org/wiki/Filesystem_in_Userspace

docs/index.rst

@@ -5,7 +5,7 @@ Welcome to Attic
 |project_name| is a deduplicating backup program written in Python.
 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 actual changes are stored.
+suitable for daily backups since only the changes are stored.
 
 
 Easy to use
@@ -44,17 +44,17 @@ 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 `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, 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.
 
 Mailing list
 ------------
 
-There is a mailing list for Attic on librelist_ you can use for feature
+There is a mailing list for Attic on librelist_ that you can use for feature
 requests and general discussions about Attic. A mailing list archive is
 available `here <http://librelist.com/browser/attic/>`_.
 
-To subscribe to the list send an email to attic@librelist.com and reply
-to the confirmation mail. Likevise To unsubscribe send an email to 
+To subscribe to the list, send an email to attic@librelist.com and reply
+to the confirmation mail. Likewise, to unsubscribe, send an email to 
 attic-unsubscribe@librelist.com and reply to the confirmation mail.

docs/installation.rst

@@ -5,7 +5,7 @@ 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
+not the default Python version on most Linux distributions, it is usually
 available as an optional install.
 
 Other dependencies:
@@ -16,6 +16,9 @@ Other dependencies:
 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.
 
+The llfuse_ python package is also required if you wish to mount an
+archive as a FUSE filesystem.
+
 Installing from PyPI using pip
 ------------------------------
 ::
@@ -39,5 +42,11 @@ Installing from git
     $ cd attic
     $ python setup.py install
 
-Please not that when installing from git Cython_ is required to generate some files that
+Please note that when installing from git, Cython_ is required to generate some files that
 are normally bundled with the release tarball.
+
+Packages
+--------
+
+|project_name| is also part of the Debian_, Ubuntu_ and `Arch Linux`_
+distributions of GNU/Linux.

docs/quickstart.rst

@@ -113,13 +113,20 @@ Key file based encryption
 Remote repositories
 -------------------
 
-|project_name| can initialize and access repositories on remote hosts as the
-host is accessible using SSH and |project_name| is installed.
-
-The following syntax is used to address remote repositories::
+|project_name| can initialize and access repositories on remote hosts if the
+host is accessible using SSH.  This is fastest and easiest when |project_name|
+is installed on the remote host, in which case the following syntax is used::
 
   $ attic init user@hostname:repository.attic
 
 or::
 
   $ attic init ssh://user@hostname:port/repository.attic
+
+If it is not possible to install |project_name| on the remote host, 
+it is still possible to use the remote host to store a repository by
+mounting the remote filesystem, for example, using sshfs::
+
+  $ sshfs user@hostname:/path/to/folder /tmp/mymountpoint
+  $ attic init /tmp/mymountpoint/repository.attic
+  $ fusermount -u /tmp/mymountpoint

docs/usage.rst

@@ -40,21 +40,21 @@ Examples
 
 This command creates a backup archive containing all files found while
 recursively traversing all paths specified. The archive will consume almost
-no disk space for files or parts of files that has already been archived by
+no disk space for files or parts of files that have already been stored in
 other archives.
 
 Examples
 ~~~~~~~~
 ::
 
-    # Backups ~/Documents into an archive named "my-documents"
+    # Backup ~/Documents into an archive named "my-documents"
     $ attic create /data/myrepo.attic::my-documents ~/Documents
 
     # Backup ~/Documents and ~/src but exclude pyc files
     $ attic create /data/myrepo.attic::my-files   \
         ~/Documents                               \
         ~/src                                     \
-        --exclude *.pyc
+        --exclude '*.pyc'
 
     # Backup the root filesystem into an archive named "root-YYYY-MM-DD"
     NAME="root-`date +%Y-%m-%d`"
@@ -82,7 +82,7 @@ Examples
     $ attic extract /data/myrepo::my-files home/USERNAME/src
 
     # Extract the "src" directory but exclude object files
-    $ attic extract /data/myrepo::my-files home/USERNAME/src --exclude *.o
+    $ attic extract /data/myrepo::my-files home/USERNAME/src --exclude '*.o'
 
 
 .. include:: usage/verify.rst.inc
@@ -126,7 +126,7 @@ Examples
 .. include:: usage/prune.rst.inc
 
 The ``prune`` command prunes a repository by deleting archives not matching
-any of the specified retention options specified. This command is normally
+any of the specified retention options. This command is normally
 used by automated backup scripts wanting to keep a certain number of historic
 backups. 
 
@@ -134,12 +134,16 @@ Examples
 ~~~~~~~~
 ::
 
-    # Keep 7 end of day and 4 end of week archives
+    # Keep 7 end of day and 4 additional end of week archives
     $ attic prune /data/myrepo --daily=7 --weekly=4
 
     # Same as above but only apply to archive names starting with "foo"
     $ attic prune /data/myrepo --daily=7 --weekly=4 --prefix=foo
 
+    # Keep 7 end of day, 4 additional end of week archives, and an
+    # end of month archive for every month:
+    $ attic prune /data/myrepo --daily=7 --weekly=4 --monthly=-1
+
 
 .. include:: usage/info.rst.inc
 

docs/usage/prune.rst.inc

@@ -29,6 +29,18 @@ attic prune
                             number of yearly archives to keep
       -p PREFIX, --prefix PREFIX
                             only consider archive names starting with this prefix
+    
+    The prune command prunes a repository by deleting archives not matching any of
+    the specified retention options. This command is normally used by automated
+    backup scripts wanting to keep a certain number of historic backups. As an
+    example, "-d 7" means to keep the latest backup on each day for 7 days. Days
+    without backups do not count towards the total. The rules are applied from
+    hourly to yearly, and backups selected by previous rules do not count towards
+    those of later rules. Dates and times are interpreted in the local timezone,
+    and weeks go from Monday to Sunday. Specifying a negative number of archives
+    to keep means that there is no limit. If a prefix is set with -p, then only
+    archives that start with the prefix are considered for deletion and only those
+    archives count towards the totals specified by the rules.
 
 Description
 ~~~~~~~~~~~