Update prune docs and a few other things in usage.rst.

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/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
 ~~~~~~~~~~~