ran build_usage

25 files changed, 292 insertions, 426 deletions

diff --git a/docs/usage/benchmark_crud.rst.inc b/docs/usage/benchmark_crud.rst.inc
index b692cae12..c0274dbe7 100644
--- a/docs/usage/benchmark_crud.rst.inc
+++ b/docs/usage/benchmark_crud.rst.inc
@@ -8,11 +8,11 @@ borg benchmark crud
 
     borg [common options] benchmark crud [options] REPO PATH
 
-positional arguments
-    REPO
-        repo to use for benchmark (must exist)
-    PATH
-        path were to create benchmark input data
+REPO
+    repo to use for benchmark (must exist)
+PATH
+    path were to create benchmark input data
+
 
 :ref:`common_options`
     |
diff --git a/docs/usage/break-lock.rst.inc b/docs/usage/break-lock.rst.inc
index fe5dcc84c..341fa8a03 100644
--- a/docs/usage/break-lock.rst.inc
+++ b/docs/usage/break-lock.rst.inc
@@ -8,9 +8,9 @@ borg break-lock
 
     borg [common options] break-lock [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
-        repository for which to break the locks
+REPOSITORY
+    repository for which to break the locks
+
 
 :ref:`common_options`
     |
diff --git a/docs/usage/change-passphrase.rst.inc b/docs/usage/change-passphrase.rst.inc
index 29384d472..c9cbee362 100644
--- a/docs/usage/change-passphrase.rst.inc
+++ b/docs/usage/change-passphrase.rst.inc
@@ -8,8 +8,8 @@ borg change-passphrase
 
     borg [common options] change-passphrase [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
+REPOSITORY
+
 
 
 :ref:`common_options`
diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc
index 047da6b28..ad31b6a2c 100644
--- a/docs/usage/check.rst.inc
+++ b/docs/usage/check.rst.inc
@@ -8,36 +8,28 @@ borg check
 
     borg [common options] check [options] REPOSITORY_OR_ARCHIVE
 
-positional arguments
-    REPOSITORY_OR_ARCHIVE
-        repository or archive to check consistency of
+REPOSITORY_OR_ARCHIVE
+    repository or archive to check consistency of
+
 
 optional arguments
-    ``--repository-only``
-        | only perform repository checks
-    ``--archives-only``
-        | only perform archives checks
-    ``--verify-data``
-        | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
-    ``--repair``
-        | attempt to repair any inconsistencies found
-    ``--save-space``
-        | work slower, but using less space
+    --repository-only    only perform repository checks
+    --archives-only    only perform archives checks
+    --verify-data     perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
+    --repair          attempt to repair any inconsistencies found
+    --save-space      work slower, but using less space
+
 
 :ref:`common_options`
     |
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-    ``--sort-by``
-        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-    ``--first N``
-        | consider first N archives after other filters were applied
-    ``--last N``
-        | consider last N archives after other filters were applied
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    --sort-by               Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    --first N               consider first N archives after other filters were applied
+    --last N                consider last N archives after other filters were applied
+
 
 Description
 ~~~~~~~~~~~
diff --git a/docs/usage/common-options.rst.inc b/docs/usage/common-options.rst.inc
index 6bc18ebac..a0d0bd0e2 100644
--- a/docs/usage/common-options.rst.inc
+++ b/docs/usage/common-options.rst.inc
@@ -1,36 +1,18 @@
-``-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
-``--debug-topic TOPIC``
-    | enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
-``-p``, ``--progress``
-    | show progress information
-``--log-json``
-    | Output one JSON object per log line instead of formatted text.
-``--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``
-    | use PATH as borg executable on the remote (default: "borg")
-``--remote-ratelimit rate``
-    | set remote network upload rate limit in kiByte/s (default: 0=unlimited)
-``--consider-part-files``
-    | treat part files like normal files (e.g. to list/extract them)
-``--debug-profile FILE``
-    | Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".
\ No newline at end of file
+-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
+--debug-topic TOPIC    enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
+-p, --progress     show progress information
+--log-json         Output one JSON object per log line instead of formatted text.
+--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    use PATH as borg executable on the remote (default: "borg")
+--remote-ratelimit rate    set remote network upload rate limit in kiByte/s (default: 0=unlimited)
+--consider-part-files    treat part files like normal files (e.g. to list/extract them)
+--debug-profile FILE    Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc
index 2a76c0dd8..0480befb2 100644
--- a/docs/usage/create.rst.inc
+++ b/docs/usage/create.rst.inc
@@ -8,70 +8,50 @@ borg create
 
     borg [common options] create [options] ARCHIVE PATH
 
-positional arguments
-    ARCHIVE
-        name of archive to create (must be also a valid directory name)
-    PATH
-        paths to archive
+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
-    ``--list``
-        | output verbose list of items (files, dirs, ...)
-    ``--filter STATUSCHARS``
-        | only display items with the given status characters
-    ``--json``
-        | output stats as JSON (implies --stats)
-    ``--no-cache-sync``
-        | experimental: do not synchronize the cache. Implies --no-files-cache.
+    -n, --dry-run    do not create a backup archive
+    -s, --stats     print statistics for the created archive
+    --list          output verbose list of items (files, dirs, ...)
+    --filter STATUSCHARS    only display items with the given status characters
+    --json          output stats as JSON (implies --stats)
+    --no-cache-sync    experimental: do not synchronize the cache. Implies --no-files-cache.
+
 
 :ref:`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 NAME``
-        | exclude directories that are tagged by containing a filesystem object with the given NAME
-    ``--keep-exclude-tags``, ``--keep-tag-files``
-        | if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
+    -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 NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
+    --keep-exclude-tags, --keep-tag-files    if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
+    --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+
 
 Filesystem options
-    ``-x``, ``--one-file-system``
-        | stay in the same file system and do not store mount points of other file systems
-    ``--numeric-owner``
-        | only store numeric user and group identifiers
-    ``--noatime``
-        | do not store atime into archive
-    ``--noctime``
-        | do not store ctime into archive
-    ``--ignore-inode``
-        | ignore inode data in the file metadata cache used to detect unchanged files.
-    ``--read-special``
-        | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
+    -x, --one-file-system     stay in the same file system and do not store mount points of other file systems
+    --numeric-owner           only store numeric user and group identifiers
+    --noatime                 do not store atime into archive
+    --noctime                 do not store ctime into archive
+    --ignore-inode            ignore inode data in the file metadata cache used to detect unchanged files.
+    --read-special            open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
+
 
 Archive options
-    ``--comment COMMENT``
-        | add a comment text to the archive
-    ``--timestamp TIMESTAMP``
-        | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
-    ``-c SECONDS``, ``--checkpoint-interval SECONDS``
-        | write checkpoint every SECONDS seconds (Default: 1800)
-    ``--chunker-params PARAMS``
-        | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
-    ``-C COMPRESSION``, ``--compression COMPRESSION``
-        | select compression algorithm, see the output of the "borg help compression" command for details.
+    --comment COMMENT                             add a comment text to the archive
+    --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
+    -c SECONDS, --checkpoint-interval SECONDS     write checkpoint every SECONDS seconds (Default: 1800)
+    --chunker-params PARAMS                       specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
+    -C COMPRESSION, --compression COMPRESSION     select compression algorithm, see the output of the "borg help compression" command for details.
+
 
 Description
 ~~~~~~~~~~~
diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc
index 18e9d539d..294900fed 100644
--- a/docs/usage/delete.rst.inc
+++ b/docs/usage/delete.rst.inc
@@ -8,34 +8,27 @@ borg delete
 
     borg [common options] delete [options] TARGET
 
-positional arguments
-    TARGET
-        archive or repository to delete
+TARGET
+    archive or repository to delete
+
 
 optional arguments
-    ``-s``, ``--stats``
-        | print statistics for the deleted archive
-    ``-c``, ``--cache-only``
-        | delete only the local cache for the given repository
-    ``--force``
-        | force deletion of corrupted archives, use --force --force in case --force does not work.
-    ``--save-space``
-        | work slower, but using less space
+    -s, --stats     print statistics for the deleted archive
+    -c, --cache-only    delete only the local cache for the given repository
+    --force         force deletion of corrupted archives, use --force --force in case --force does not work.
+    --save-space    work slower, but using less space
+
 
 :ref:`common_options`
     |
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-    ``--sort-by``
-        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-    ``--first N``
-        | consider first N archives after other filters were applied
-    ``--last N``
-        | consider last N archives after other filters were applied
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    --sort-by               Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    --first N               consider first N archives after other filters were applied
+    --last N                consider last N archives after other filters were applied
+
 
 Description
 ~~~~~~~~~~~
diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc
index 0de6e9090..1c3d7fb1a 100644
--- a/docs/usage/diff.rst.inc
+++ b/docs/usage/diff.rst.inc
@@ -8,40 +8,32 @@ borg diff
 
     borg [common options] diff [options] REPO_ARCHIVE1 ARCHIVE2 PATH
 
-positional arguments
-    REPO_ARCHIVE1
-        repository location and ARCHIVE1 name
-    ARCHIVE2
-        ARCHIVE2 name (no repository location allowed)
-    PATH
-        paths of items inside the archives to compare; patterns are supported
+REPO_ARCHIVE1
+    repository location and ARCHIVE1 name
+ARCHIVE2
+    ARCHIVE2 name (no repository location allowed)
+PATH
+    paths of items inside the archives to compare; patterns are supported
+
 
 optional arguments
-    ``--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.
+    --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.
+
 
 :ref:`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 NAME``
-        | exclude directories that are tagged by containing a filesystem object with the given NAME
-    ``--keep-exclude-tags``, ``--keep-tag-files``
-        | if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
+    -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 NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
+    --keep-exclude-tags, --keep-tag-files    if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
+    --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+
 
 Description
 ~~~~~~~~~~~
diff --git a/docs/usage/export-tar.rst.inc b/docs/usage/export-tar.rst.inc
index 327a0874c..d28bf999f 100644
--- a/docs/usage/export-tar.rst.inc
+++ b/docs/usage/export-tar.rst.inc
@@ -8,29 +8,23 @@ borg export-tar
 
     borg [common options] export-tar [options] ARCHIVE FILE PATH
 
-positional arguments
-    ARCHIVE
-        archive to export
-    FILE
-        output tar file. "-" to write to stdout instead.
-    PATH
-        paths to extract; patterns are supported
+ARCHIVE
+    archive to export
+FILE
+    output tar file. "-" to write to stdout instead.
+PATH
+    paths to extract; patterns are supported
+
 
 optional arguments
-    ``--tar-filter``
-        | filter program to pipe data through
-    ``--list``
-        | output verbose list of items (files, dirs, ...)
-    ``-e PATTERN``, ``--exclude PATTERN``
-        | exclude paths matching PATTERN
-    ``--exclude-from EXCLUDEFILE``
-        | read exclude patterns from EXCLUDEFILE, one per line
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
-    ``--strip-components NUMBER``
-        | Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
+    --tar-filter                      filter program to pipe data through
+    --list                            output verbose list of items (files, dirs, ...)
+    -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
+    --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+    --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+    --strip-components NUMBER         Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
+
 
 :ref:`common_options`
     |
diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc
index e9913d65f..e23eecd02 100644
--- a/docs/usage/extract.rst.inc
+++ b/docs/usage/extract.rst.inc
@@ -8,33 +8,24 @@ borg extract
 
     borg [common options] extract [options] ARCHIVE PATH
 
-positional arguments
-    ARCHIVE
-        archive to extract
-    PATH
-        paths to extract; patterns are supported
+ARCHIVE
+    archive to extract
+PATH
+    paths to extract; patterns are supported
+
 
 optional arguments
-    ``--list``
-        | output verbose list of items (files, dirs, ...)
-    ``-n``, ``--dry-run``
-        | do not actually change any files
-    ``-e PATTERN``, ``--exclude PATTERN``
-        | exclude paths matching PATTERN
-    ``--exclude-from EXCLUDEFILE``
-        | read exclude patterns from EXCLUDEFILE, one per line
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
-    ``--numeric-owner``
-        | only obey numeric user and group identifiers
-    ``--strip-components NUMBER``
-        | Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
-    ``--stdout``
-        | write all extracted data to stdout
-    ``--sparse``
-        | create holes in output sparse file from all-zero chunks
+    --list            output verbose list of items (files, dirs, ...)
+    -n, --dry-run     do not actually change any files
+    -e PATTERN, --exclude PATTERN    exclude paths matching PATTERN
+    --exclude-from EXCLUDEFILE    read exclude patterns from EXCLUDEFILE, one per line
+    --pattern PATTERN    experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE    experimental: read include/exclude patterns from PATTERNFILE, one per line
+    --numeric-owner    only obey numeric user and group identifiers
+    --strip-components NUMBER    Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
+    --stdout          write all extracted data to stdout
+    --sparse          create holes in output sparse file from all-zero chunks
+
 
 :ref:`common_options`
     |
diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc
index 879dee144..d23664d6b 100644
--- a/docs/usage/info.rst.inc
+++ b/docs/usage/info.rst.inc
@@ -8,28 +8,24 @@ borg info
 
     borg [common options] info [options] REPOSITORY_OR_ARCHIVE
 
-positional arguments
-    REPOSITORY_OR_ARCHIVE
-        archive or repository to display information about
+REPOSITORY_OR_ARCHIVE
+    archive or repository to display information about
+
 
 optional arguments
-    ``--json``
-        | format output as JSON
+    --json     format output as JSON
+
 
 :ref:`common_options`
     |
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-    ``--sort-by``
-        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-    ``--first N``
-        | consider first N archives after other filters were applied
-    ``--last N``
-        | consider last N archives after other filters were applied
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    --sort-by               Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    --first N               consider first N archives after other filters were applied
+    --last N                consider last N archives after other filters were applied
+
 
 Description
 ~~~~~~~~~~~
diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc
index 88fe11c7e..a959ead2f 100644
--- a/docs/usage/init.rst.inc
+++ b/docs/usage/init.rst.inc
@@ -8,17 +8,15 @@ borg init
 
     borg [common options] init [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
-        repository to create
+REPOSITORY
+    repository to create
+
 
 optional arguments
-    ``-e``, ``--encryption``
-        | select encryption key mode **(required)**
-    ``--append-only``
-        | create an append-only mode repository
-    ``--storage-quota``
-        | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
+    -e, --encryption     select encryption key mode **(required)**
+    --append-only        create an append-only mode repository
+    --storage-quota      Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
+
 
 :ref:`common_options`
     |
diff --git a/docs/usage/key_change-passphrase.rst.inc b/docs/usage/key_change-passphrase.rst.inc
index 91323a043..b40ab8065 100644
--- a/docs/usage/key_change-passphrase.rst.inc
+++ b/docs/usage/key_change-passphrase.rst.inc
@@ -8,8 +8,8 @@ borg key change-passphrase
 
     borg [common options] key change-passphrase [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
+REPOSITORY
+
 
 
 :ref:`common_options`
diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc
index a0d7cf133..271d0eeb7 100644
--- a/docs/usage/key_export.rst.inc
+++ b/docs/usage/key_export.rst.inc
@@ -8,17 +8,16 @@ borg key export
 
     borg [common options] key export [options] REPOSITORY PATH
 
-positional arguments
-    REPOSITORY
+REPOSITORY
+
+PATH
+    where to store the backup
 
-    PATH
-        where to store the backup
 
 optional arguments
-    ``--paper``
-        | Create an export suitable for printing and later type-in
-    ``--qr-html``
-        | Create an html file suitable for printing and later type-in or qr scan
+    --paper       Create an export suitable for printing and later type-in
+    --qr-html     Create an html file suitable for printing and later type-in or qr scan
+
 
 :ref:`common_options`
     |
diff --git a/docs/usage/key_import.rst.inc b/docs/usage/key_import.rst.inc
index c6b9b5ea4..e08ef912e 100644
--- a/docs/usage/key_import.rst.inc
+++ b/docs/usage/key_import.rst.inc
@@ -8,15 +8,15 @@ borg key import
 
     borg [common options] key import [options] REPOSITORY PATH
 
-positional arguments
-    REPOSITORY
+REPOSITORY
+
+PATH
+    path to the backup
 
-    PATH
-        path to the backup
 
 optional arguments
-    ``--paper``
-        | interactively import from a backup done with ``--paper``
+    --paper     interactively import from a backup done with ``--paper``
+
 
 :ref:`common_options`
     |
diff --git a/docs/usage/key_migrate-to-repokey.rst.inc b/docs/usage/key_migrate-to-repokey.rst.inc
index 9acf215d6..948d7b8c1 100644
--- a/docs/usage/key_migrate-to-repokey.rst.inc
+++ b/docs/usage/key_migrate-to-repokey.rst.inc
@@ -8,8 +8,8 @@ borg key migrate-to-repokey
 
     borg [common options] key migrate-to-repokey [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
+REPOSITORY
+
 
 
 :ref:`common_options`
diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc
index a1fedea9f..cb8e6d579 100644
--- a/docs/usage/list.rst.inc
+++ b/docs/usage/list.rst.inc
@@ -8,53 +8,40 @@ borg list
 
     borg [common options] list [options] REPOSITORY_OR_ARCHIVE PATH
 
-positional arguments
-    REPOSITORY_OR_ARCHIVE
-        repository/archive to list contents of
-    PATH
-        paths to list; patterns are supported
+REPOSITORY_OR_ARCHIVE
+    repository/archive to list contents of
+PATH
+    paths to list; patterns are supported
+
 
 optional arguments
-    ``--short``
-        | only print file/directory names, nothing else
-    ``--format``, ``--list-format``
-        | specify format for file listing
-        |                                 (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
-    ``--json``
-        | Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
-    ``--json-lines``
-        | Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
+    --short     only print file/directory names, nothing else
+    --format, --list-format    specify format for file listing
+                                    (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
+    --json      Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
+    --json-lines    Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
+
 
 :ref:`common_options`
     |
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-    ``--sort-by``
-        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-    ``--first N``
-        | consider first N archives after other filters were applied
-    ``--last N``
-        | consider last N archives after other filters were applied
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only