Better help texts and Sphinx reproduction of usage

- Group options
- Nicer list of options in Sphinx
- Deduplicate 'Common options'
  (including --help)

The latter is done by explicitly declaring --help in the common_parser,
which is then inherited by the sub-parsers; no change in observable
behaviour.

22 files changed, 403 insertions, 701 deletions

diff --git a/docs/usage/break-lock.rst.inc b/docs/usage/break-lock.rst.inc
index f0dd5636f..15afaa0b9 100644
--- a/docs/usage/break-lock.rst.inc
+++ b/docs/usage/break-lock.rst.inc
@@ -4,32 +4,15 @@ borg break-lock
 ---------------
 ::
 
-    usage: borg break-lock [-h] [--critical] [--error] [--warning] [--info]
-                           [--debug] [--lock-wait N] [--show-version] [--show-rc]
-                           [--no-files-cache] [--umask M] [--remote-path PATH]
-                           REPOSITORY
-    
-    Break the repository lock (e.g. in case it was left by a dead borg.
-    
-    positional arguments:
-      REPOSITORY            repository for which to break the locks
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg break-lock <options> REPOSITORY
+
+positional arguments
+    REPOSITORY
+        repository for which to break the locks
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/change-passphrase.rst.inc b/docs/usage/change-passphrase.rst.inc
index bbf32ddc9..16ca9608c 100644
--- a/docs/usage/change-passphrase.rst.inc
+++ b/docs/usage/change-passphrase.rst.inc
@@ -4,33 +4,15 @@ borg change-passphrase
 ----------------------
 ::
 
-    usage: borg change-passphrase [-h] [--critical] [--error] [--warning] [--info]
-                                  [--debug] [--lock-wait N] [--show-version]
-                                  [--show-rc] [--no-files-cache] [--umask M]
-                                  [--remote-path PATH]
-                                  [REPOSITORY]
-    
-    Change repository key file passphrase
-    
-    positional arguments:
-      REPOSITORY
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg change-passphrase <options> REPOSITORY
+
+positional arguments
+    REPOSITORY
+
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc
index 52355ab66..4dd5b05fb 100644
--- a/docs/usage/check.rst.inc
+++ b/docs/usage/check.rst.inc
@@ -4,42 +4,29 @@ borg check
 ----------
 ::
 
-    usage: borg check [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                      [--lock-wait N] [--show-version] [--show-rc]
-                      [--no-files-cache] [--umask M] [--remote-path PATH]
-                      [--repository-only] [--archives-only] [--repair]
-                      [--save-space] [--last N] [-P PREFIX]
-                      [REPOSITORY_OR_ARCHIVE]
-    
-    Check repository consistency
-    
-    positional arguments:
-      REPOSITORY_OR_ARCHIVE
-                            repository or archive to check consistency of
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      --repository-only     only perform repository checks
-      --archives-only       only perform archives checks
-      --repair              attempt to repair any inconsistencies found
-      --save-space          work slower, but using less space
-      --last N              only check last N archives (Default: all)
-      -P PREFIX, --prefix PREFIX
-                            only consider archive names starting with this prefix
-    
+    borg check <options> REPOSITORY_OR_ARCHIVE
+
+positional arguments
+    REPOSITORY_OR_ARCHIVE
+        repository or archive to check consistency of
+
+optional arguments
+    ``--repository-only``
+        | only perform repository checks
+    ``--archives-only``
+        | only perform archives checks
+    ``--repair``
+        | attempt to repair any inconsistencies found
+    ``--save-space``
+        | work slower, but using less space
+    ``--last N``
+        | only check last N archives (Default: all)
+    ``-P``, ``--prefix``
+        | only consider archive names starting with this prefix
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/comment.rst.inc b/docs/usage/comment.rst.inc
index b15edf378..56709a537 100644
--- a/docs/usage/comment.rst.inc
+++ b/docs/usage/comment.rst.inc
@@ -4,34 +4,20 @@ borg comment
 ------------
 ::
 
-    usage: borg comment [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                        [--lock-wait N] [--show-version] [--show-rc]
-                        [--no-files-cache] [--umask M] [--remote-path PATH]
-                        ARCHIVE COMMENT
-    
-    Set the archive comment
-    
-    positional arguments:
-      ARCHIVE               archive to modify
-      COMMENT               the new archive comment
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg comment <options> ARCHIVE COMMENT
+
+positional arguments
+    ARCHIVE
+        archive to modify
+    COMMENT
+        the new archive comment
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
 This command sets the archive comment.
+
+This results in a different archive ID.
diff --git a/docs/usage/common-options.rst.inc b/docs/usage/common-options.rst.inc
new file mode 100644
index 000000000..0a3c3c3ed
--- /dev/null
+++ b/docs/usage/common-options.rst.inc
@@ -0,0 +1,24 @@
+    ``-h``, ``--help``
+        | show this help message and exit
+    ``--critical``
+        | work on log level CRITICAL
+    ``--error``
+        | work on log level ERROR
+    ``--warning``
+        | work on log level WARNING (default)
+    ``--info``, ``-v``, ``--verbose``
+        | work on log level INFO
+    ``--debug``
+        | enable debug output, work on log level DEBUG
+    ``--lock-wait N``
+        | wait for the lock, but max. N seconds (default: 1).
+    ``--show-version``
+        | show/log the borg version
+    ``--show-rc``
+        | show/log the return code (rc)
+    ``--no-files-cache``
+        | do not load/update the file metadata cache used to detect unchanged files
+    ``--umask M``
+        | set umask to M (local and remote, default: 0077)
+    ``--remote-path PATH``
+        | set remote path to executable (default: "borg")
\ No newline at end of file
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc
index 974770a99..383e18056 100644
--- a/docs/usage/create.rst.inc
+++ b/docs/usage/create.rst.inc
@@ -4,80 +4,69 @@ borg create
 -----------
 ::
 
-    usage: borg create [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                       [--lock-wait N] [--show-version] [--show-rc]
-                       [--no-files-cache] [--umask M] [--remote-path PATH]
-                       [--comment COMMENT] [-s] [-p] [--list]
-                       [--filter STATUSCHARS] [-e PATTERN]
-                       [--exclude-from EXCLUDEFILE] [--exclude-caches]
-                       [--exclude-if-present FILENAME] [--keep-tag-files]
-                       [-c SECONDS] [-x] [--numeric-owner]
-                       [--timestamp yyyy-mm-ddThh:mm:ss]
-                       [--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE]
-                       [--ignore-inode] [-C COMPRESSION] [--read-special] [-n]
-                       ARCHIVE PATH [PATH ...]
-    
-    Create new archive
-    
-    positional arguments:
-      ARCHIVE               name of archive to create (must be also a valid
-                            directory name)
-      PATH                  paths to archive
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      --comment COMMENT     add a comment text to the archive
-      -s, --stats           print statistics for the created archive
-      -p, --progress        show progress display while creating the archive,
-                            showing Original, Compressed and Deduplicated sizes,
-                            followed by the Number of files seen and the path
-                            being processed, default: False
-      --list                output verbose list of items (files, dirs, ...)
-      --filter STATUSCHARS  only display items with the given status characters
-      -e PATTERN, --exclude PATTERN
-                            exclude paths matching PATTERN
-      --exclude-from EXCLUDEFILE
-                            read exclude patterns from EXCLUDEFILE, one per line
-      --exclude-caches      exclude directories that contain a CACHEDIR.TAG file
-                            (http://www.brynosaurus.com/cachedir/spec.html)
-      --exclude-if-present FILENAME
-                            exclude directories that contain the specified file
-      --keep-tag-files      keep tag files of excluded caches/directories
-      -c SECONDS, --checkpoint-interval SECONDS
-                            write checkpoint every SECONDS seconds (Default: 300)
-      -x, --one-file-system
-                            stay in same file system, do not cross mount points
-      --numeric-owner       only store numeric user and group identifiers
-      --timestamp yyyy-mm-ddThh:mm:ss
-                            manually specify the archive creation date/time (UTC).
-                            alternatively, give a reference file/directory.
-      --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE
-                            specify the chunker parameters. default: 19,23,21,4095
-      --ignore-inode        ignore inode data in the file metadata cache used to
-                            detect unchanged files.
-      -C COMPRESSION, --compression COMPRESSION
-                            select compression algorithm (and level): none == no
-                            compression (default), lz4 == lz4, zlib == zlib
-                            (default level 6), zlib,0 .. zlib,9 == zlib (with
-                            level 0..9), lzma == lzma (default level 6), lzma,0 ..
-                            lzma,9 == lzma (with level 0..9).
-      --read-special        open and read special files as if they were regular
-                            files
-      -n, --dry-run         do not create a backup archive
-    
+    borg create <options> ARCHIVE PATH
+
+positional arguments
+    ARCHIVE
+        name of archive to create (must be also a valid directory name)
+    PATH
+        paths to archive
+
+optional arguments
+    ``-n``, ``--dry-run``
+        | do not create a backup archive
+    ``-s``, ``--stats``
+        | print statistics for the created archive
+    ``-p``, ``--progress``
+        | show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False
+    ``--list``
+        | output verbose list of items (files, dirs, ...)
+    ``--filter STATUSCHARS``
+        | only display items with the given status characters
+
+`Common options`_
+    |
+
+Exclusion options
+    ``-e PATTERN``, ``--exclude PATTERN``
+        | exclude paths matching PATTERN
+    ``--exclude-from EXCLUDEFILE``
+        | read exclude patterns from EXCLUDEFILE, one per line
+    ``--exclude-caches``
+        | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+    ``--exclude-if-present FILENAME``
+        | exclude directories that contain the specified file
+    ``--keep-tag-files``
+        | keep tag files of excluded caches/directories
+
+Filesystem options
+    ``-x``, ``--one-file-system``
+        | stay in same file system, do not cross mount points
+    ``--numeric-owner``
+        | only store numeric user and group identifiers
+    ``--ignore-inode``
+        | ignore inode data in the file metadata cache used to detect unchanged files.
+    ``--read-special``
+        | open and read special files as if they were regular files
+
+Archive options
+    ``--comment COMMENT``
+        | add a comment text to the archive
+    ``--timestamp yyyy-mm-ddThh:mm:ss``
+        | manually specify the archive creation date/time (UTC). alternatively, give a reference file/directory.
+    ``-c SECONDS``, ``--checkpoint-interval SECONDS``
+        | write checkpoint every SECONDS seconds (Default: 300)
+    ``--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
+        | specify the chunker parameters. default: 19,23,21,4095
+    ``-C COMPRESSION``, ``--compression COMPRESSION``
+        | select compression algorithm (and level):
+        | none == no compression (default),
+        | lz4 == lz4,
+        | zlib == zlib (default level 6),
+        | zlib,0 .. zlib,9 == zlib (with level 0..9),
+        | lzma == lzma (default level 6),
+        | lzma,0 .. lzma,9 == lzma (with level 0..9).
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/debug-delete-obj.rst.inc b/docs/usage/debug-delete-obj.rst.inc
index fa4c677c3..8e9f6e667 100644
--- a/docs/usage/debug-delete-obj.rst.inc
+++ b/docs/usage/debug-delete-obj.rst.inc
@@ -4,34 +4,17 @@ borg debug-delete-obj
 ---------------------
 ::
 
-    usage: borg debug-delete-obj [-h] [--critical] [--error] [--warning] [--info]
-                                 [--debug] [--lock-wait N] [--show-version]
-                                 [--show-rc] [--no-files-cache] [--umask M]
-                                 [--remote-path PATH]
-                                 [REPOSITORY] IDs [IDs ...]
-    
-    delete the objects with the given IDs from the repo
-    
-    positional arguments:
-      REPOSITORY            repository to use
-      IDs                   hex object ID(s) to delete from the repo
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg debug-delete-obj <options> REPOSITORY IDs
+
+positional arguments
+    REPOSITORY
+        repository to use
+    IDs
+        hex object ID(s) to delete from the repo
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/debug-dump-archive-items.rst.inc b/docs/usage/debug-dump-archive-items.rst.inc
index 10bb16f6f..ec35c80a1 100644
--- a/docs/usage/debug-dump-archive-items.rst.inc
+++ b/docs/usage/debug-dump-archive-items.rst.inc
@@ -4,34 +4,15 @@ borg debug-dump-archive-items
 -----------------------------
 ::
 
-    usage: borg debug-dump-archive-items [-h] [--critical] [--error] [--warning]
-                                         [--info] [--debug] [--lock-wait N]
-                                         [--show-version] [--show-rc]
-                                         [--no-files-cache] [--umask M]
-                                         [--remote-path PATH]
-                                         ARCHIVE
-    
-    dump (decrypted, decompressed) archive items metadata (not: data)
-    
-    positional arguments:
-      ARCHIVE               archive to dump
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg debug-dump-archive-items <options> ARCHIVE
+
+positional arguments
+    ARCHIVE
+        archive to dump
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/debug-get-obj.rst.inc b/docs/usage/debug-get-obj.rst.inc
index aa2e94744..986b2c4f5 100644
--- a/docs/usage/debug-get-obj.rst.inc
+++ b/docs/usage/debug-get-obj.rst.inc
@@ -4,35 +4,19 @@ borg debug-get-obj
 ------------------
 ::
 
-    usage: borg debug-get-obj [-h] [--critical] [--error] [--warning] [--info]
-                              [--debug] [--lock-wait N] [--show-version]
-                              [--show-rc] [--no-files-cache] [--umask M]
-                              [--remote-path PATH]
-                              [REPOSITORY] ID PATH
-    
-    get object contents from the repository and write it into file
-    
-    positional arguments:
-      REPOSITORY            repository to use
-      ID                    hex object ID to get from the repo
-      PATH                  file to write object data into
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg debug-get-obj <options> REPOSITORY ID PATH
+
+positional arguments
+    REPOSITORY
+        repository to use
+    ID
+        hex object ID to get from the repo
+    PATH
+        file to write object data into
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/debug-put-obj.rst.inc b/docs/usage/debug-put-obj.rst.inc
index 3d38cfe42..8a4c3987d 100644
--- a/docs/usage/debug-put-obj.rst.inc
+++ b/docs/usage/debug-put-obj.rst.inc
@@ -4,34 +4,17 @@ borg debug-put-obj
 ------------------
 ::
 
-    usage: borg debug-put-obj [-h] [--critical] [--error] [--warning] [--info]
-                              [--debug] [--lock-wait N] [--show-version]
-                              [--show-rc] [--no-files-cache] [--umask M]
-                              [--remote-path PATH]
-                              [REPOSITORY] PATH [PATH ...]
-    
-    put file(s) contents into the repository
-    
-    positional arguments:
-      REPOSITORY            repository to use
-      PATH                  file(s) to read and create object(s) from
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-    
+    borg debug-put-obj <options> REPOSITORY PATH
+
+positional arguments
+    REPOSITORY
+        repository to use
+    PATH
+        file(s) to read and create object(s) from
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc
index 2a47ebf98..e07069d3d 100644
--- a/docs/usage/delete.rst.inc
+++ b/docs/usage/delete.rst.inc
@@ -4,37 +4,25 @@ borg delete
 -----------
 ::
 
-    usage: borg delete [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                       [--lock-wait N] [--show-version] [--show-rc]
-                       [--no-files-cache] [--umask M] [--remote-path PATH] [-p]
-                       [-s] [-c] [--save-space]
-                       [TARGET]
-    
-    Delete an existing repository or archive
-    
-    positional arguments:
-      TARGET                archive or repository to delete
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      -p, --progress        show progress display while deleting a single archive
-      -s, --stats           print statistics for the deleted archive
-      -c, --cache-only      delete only the local cache for the given repository
-      --save-space          work slower, but using less space
-    
+    borg delete <options> TARGET
+
+positional arguments
+    TARGET
+        archive or repository to delete
+
+optional arguments
+    ``-p``, ``--progress``
+        | show progress display while deleting a single archive
+    ``-s``, ``--stats``
+        | print statistics for the deleted archive
+    ``-c``, ``--cache-only``
+        | delete only the local cache for the given repository
+    ``--save-space``
+        | work slower, but using less space
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc
index b093b1a27..a24be1446 100644
--- a/docs/usage/diff.rst.inc
+++ b/docs/usage/diff.rst.inc
@@ -4,45 +4,31 @@ borg diff
 ---------
 ::
 
-    usage: borg diff [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                     [--lock-wait N] [--show-version] [--show-rc]
-                     [--no-files-cache] [--umask M] [--remote-path PATH]
-                     [-e PATTERN] [--exclude-from EXCLUDEFILE] [--numeric-owner]
-                     [--same-chunker-params] [--sort]
-                     ARCHIVE1 ARCHIVE2 [PATH [PATH ...]]
-    
-    Diff contents of two archives
-    
-    positional arguments:
-      ARCHIVE1              archive
-      ARCHIVE2              archive to compare with ARCHIVE1 (no repository
-                            location)
-      PATH                  paths to compare; patterns are supported
-    
-    optional arguments:
-      -h, --help            show this help message and exit
-      --critical            work on log level CRITICAL
-      --error               work on log level ERROR
-      --warning             work on log level WARNING (default)
-      --info, -v, --verbose
-                            work on log level INFO
-      --debug               work on log level DEBUG
-      --lock-wait N         wait for the lock, but max. N seconds (default: 1).
-      --show-version        show/log the borg version
-      --show-rc             show/log the return code (rc)
-      --no-files-cache      do not load/update the file metadata cache used to
-                            detect unchanged files
-      --umask M             set umask to M (local and remote, default: 0077)
-      --remote-path PATH    set remote path to executable (default: "borg")
-      -e PATTERN, --exclude PATTERN
-                            exclude paths matching PATTERN
-      --exclude-from EXCLUDEFILE
-                            read exclude patterns from EXCLUDEFILE, one per line
-      --numeric-owner       only consider numeric user and group identifiers
-      --same-chunker-params
-                            Override check of chunker parameters.
-      --sort                Sort the output lines by file path.
-    
+    borg diff <options> ARCHIVE1 ARCHIVE2 PATH
+
+positional arguments
+    ARCHIVE1
+        archive
+    ARCHIVE2
+        archive to compare with ARCHIVE1 (no repository location)
+    PATH
+        paths to compare; patterns are supported
+
+optional arguments
+    ``-e PATTERN``, ``--exclude PATTERN``
+        | exclude paths matching PATTERN
+    ``--exclude-from EXCLUDEFILE``
+        | read exclude patterns from EXCLUDEFILE, one per line
+    ``--numeric-owner``
+        | only consider numeric user and group identifiers
+    ``--same-chunker-params``
+        | Override check of chunker parameters.
+    ``--sort``
+        | Sort the output lines by file path.
+
+`Common options`_
+    |
+
 Description
 ~~~~~~~~~~~
 
diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc
index 36892a03d..f18458c30 100644
--- a/docs/usage/extract.rst.inc
+++ b/docs/usage/extract.rst.inc
@@ -4,50 +4,35 @@ borg extract
 ------------
 ::
 
-    usage: borg extract [-h] [--critical] [--error] [--warning] [--info] [--debug]
-                        [--lock-wait N] [--show-version] [--show-rc]
-                        [--no-files-cache] [--umask M] [--remote-path PATH]
-                        [--list] [-n] [-e PATTERN] [--exclude-from EXCLUDEFILE]
-                        [--numeric-owner] [--strip-components NUMBER] [--stdout]
-                        [--sparse]
-                        ARCHIVE [PATH [PATH ...]]
-    
-    Extract archive contents
-    
-    positional arguments:
-      ARCHIVE               archive to extract