ran build_usage

25 files changed, 1312 insertions, 388 deletions

diff --git a/docs/usage/benchmark_crud.rst.inc b/docs/usage/benchmark_crud.rst.inc
index 6eb48ef60..91a9ff424 100644
--- a/docs/usage/benchmark_crud.rst.inc
+++ b/docs/usage/benchmark_crud.rst.inc
@@ -8,16 +8,42 @@ borg benchmark crud
 
     borg [common options] benchmark crud [options] REPO PATH
 
-REPO
-    repo to use for benchmark (must exist)
-PATH
-    path were to create benchmark input data
-
-
-.. class:: borg-common-opt-ref
-
-:ref:`common_options`
-
+.. only:: html
+
+    .. class:: borg-options-table
+
+    +-------------------------------------------------------+----------+------------------------------------------+
+    | **positional arguments**                                                                                    |
+    +-------------------------------------------------------+----------+------------------------------------------+
+    |                                                       | ``REPO`` | repo to use for benchmark (must exist)   |
+    +-------------------------------------------------------+----------+------------------------------------------+
+    |                                                       | ``PATH`` | path were to create benchmark input data |
+    +-------------------------------------------------------+----------+------------------------------------------+
+    | **optional arguments**                                                                                      |
+    +-------------------------------------------------------+----------+------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                              |
+    |                                                                                                             |
+    | :ref:`common_options`                                                                                       |
+    +-------------------------------------------------------+----------+------------------------------------------+
+
+    .. raw:: html
+
+        <script type='text/javascript'>
+        $(window).load(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. only:: latex
+
+    REPO
+        repo to use for benchmark (must exist)
+    PATH
+        path were to create benchmark input data
+
+
+    :ref:`common_options`
+        |
 
 Description
 ~~~~~~~~~~~
diff --git a/docs/usage/break-lock.rst.inc b/docs/usage/break-lock.rst.inc
index 130e573e4..4ca4aa5b6 100644
--- a/docs/usage/break-lock.rst.inc
+++ b/docs/usage/break-lock.rst.inc
@@ -8,14 +8,38 @@ borg break-lock
 
     borg [common options] break-lock [options] REPOSITORY
 
-REPOSITORY
-    repository for which to break the locks
+.. only:: html
 
+    .. class:: borg-options-table
 
-.. class:: borg-common-opt-ref
+    +-------------------------------------------------------+----------------+-----------------------------------------+
+    | **positional arguments**                                                                                         |
+    +-------------------------------------------------------+----------------+-----------------------------------------+
+    |                                                       | ``REPOSITORY`` | repository for which to break the locks |
+    +-------------------------------------------------------+----------------+-----------------------------------------+
+    | **optional arguments**                                                                                           |
+    +-------------------------------------------------------+----------------+-----------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                   |
+    |                                                                                                                  |
+    | :ref:`common_options`                                                                                            |
+    +-------------------------------------------------------+----------------+-----------------------------------------+
 
-:ref:`common_options`
+    .. raw:: html
 
+        <script type='text/javascript'>
+        $(window).load(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. only:: latex
+
+    REPOSITORY
+        repository for which to break the locks
+
+
+    :ref:`common_options`
+        |
 
 Description
 ~~~~~~~~~~~
diff --git a/docs/usage/change-passphrase.rst.inc b/docs/usage/change-passphrase.rst.inc
index 0df569a70..5b2fd281d 100644
--- a/docs/usage/change-passphrase.rst.inc
+++ b/docs/usage/change-passphrase.rst.inc
@@ -8,14 +8,38 @@ borg change-passphrase
 
     borg [common options] change-passphrase [options] REPOSITORY
 
-REPOSITORY
+.. only:: html
 
+    .. class:: borg-options-table
 
+    +-------------------------------------------------------+----------------+--+
+    | **positional arguments**                                                  |
+    +-------------------------------------------------------+----------------+--+
+    |                                                       | ``REPOSITORY`` |  |
+    +-------------------------------------------------------+----------------+--+
+    | **optional arguments**                                                    |
+    +-------------------------------------------------------+----------------+--+
+    | .. class:: borg-common-opt-ref                                            |
+    |                                                                           |
+    | :ref:`common_options`                                                     |
+    +-------------------------------------------------------+----------------+--+
 
-.. class:: borg-common-opt-ref
+    .. raw:: html
 
-:ref:`common_options`
+        <script type='text/javascript'>
+        $(window).load(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
 
+.. only:: latex
+
+    REPOSITORY
+
+
+
+    :ref:`common_options`
+        |
 
 Description
 ~~~~~~~~~~~
diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc
index ae185a583..918a3af7c 100644
--- a/docs/usage/check.rst.inc
+++ b/docs/usage/check.rst.inc
@@ -8,29 +8,75 @@ borg check
 
     borg [common options] check [options] REPOSITORY_OR_ARCHIVE
 
-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
-
-
-.. class:: borg-common-opt-ref
-
-: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
+.. only:: html
+
+    .. class:: borg-options-table
+
+    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **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                                                                                                                           |
+    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--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                                                                                                                      |
+    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                               |
+    |                                                                                                                                                                                                                                              |
+    | :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                                                                                              |
+    +-------------------------------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+    .. raw:: html
+
+        <script type='text/javascript'>
+        $(window).load(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. only:: latex
+
+    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
+
+
+    :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
 
 
 Description
diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc
index 515591576..00a3dfcc8 100644
--- a/docs/usage/create.rst.inc
+++ b/docs/usage/create.rst.inc
@@ -8,51 +8,131 @@ borg create
 
     borg [common options] create [options] ARCHIVE PATH
 
-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.
-
-
-.. class:: borg-common-opt-ref
-
-: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
-
-
-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.
-
-
-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.
+.. only:: html
+
+    .. class:: borg-options-table
+
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **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                                                                                                          |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--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``.                                                                         |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                |
+    |                                                                                                                                                                                                                                                               |
+    | :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                                                                        |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **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. |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **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.                                                  |
+    +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+
+    .. raw:: html
+
+        <script type='text/javascript'>
+        $(window).load(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. only:: latex
+
+    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``.
+
+
+    :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