docs: usage: improved formatting, cosmetic changes

1 files changed, 63 insertions, 43 deletions

diff --git a/docs/usage.rst b/docs/usage.rst
index c4e2fa80f..8595ca7f8 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -41,26 +41,32 @@ Environment Variables
 
 |project_name| uses some environment variables for automation:
 
-::
-
-    Specifying a passphrase:
-        BORG_PASSPHRASE : When set, use the value to answer the passphrase question for encrypted repositories.
-
-    Some "yes" sayers (if set, they automatically confirm that you really want to do X even if there is that warning):
-        BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK : For "Warning: Attempting to access a previously unknown unencrypted repository"
-        BORG_RELOCATED_REPO_ACCESS_IS_OK : For "Warning: The repository at location ... was previously located at ..."
-        BORG_CHECK_I_KNOW_WHAT_I_AM_DOING : For "Warning: 'check --repair' is an experimental feature that might result in data loss."
-
-    Directories:
-        BORG_KEYS_DIR : Default to '~/.borg/keys'. This directory contains keys for encrypted repositories.
-        BORG_CACHE_DIR : Default to '~/.cache/borg'. This directory contains the local cache and might need a lot
-                         of space for dealing with big repositories).
-
-    Building:
-        BORG_OPENSSL_PREFIX : Adds given OpenSSL header file directory to the default locations (setup.py).
-
-    General:
-        TMPDIR : where temporary files are stored (might need a lot of temporary space for some operations)
+Specifying a passphrase:
+    BORG_PASSPHRASE
+        When set, use the value to answer the passphrase question for encrypted repositories.
+
+Some "yes" sayers (if set, they automatically confirm that you really want to do X even if there is that warning):
+    BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK
+        For "Warning: Attempting to access a previously unknown unencrypted repository"
+    BORG_RELOCATED_REPO_ACCESS_IS_OK
+        For "Warning: The repository at location ... was previously located at ..."
+    BORG_CHECK_I_KNOW_WHAT_I_AM_DOING
+        For "Warning: 'check --repair' is an experimental feature that might result in data loss."
+
+Directories:
+    BORG_KEYS_DIR
+        Default to '~/.borg/keys'. This directory contains keys for encrypted repositories.
+    BORG_CACHE_DIR
+        Default to '~/.cache/borg'. This directory contains the local cache and might need a lot
+        of space for dealing with big repositories).
+
+Building:
+    BORG_OPENSSL_PREFIX
+        Adds given OpenSSL header file directory to the default locations (setup.py).
+
+General:
+    TMPDIR
+        where temporary files are stored (might need a lot of temporary space for some operations)
 
 
 Please note:
@@ -75,29 +81,43 @@ Resource Usage
 
 |project_name| might use a lot of resources depending on the size of the data set it is dealing with.
 
-CPU: it won't go beyond 100% of 1 core as the code is currently single-threaded.
-     Especially higher zlib and lzma compression levels use significant amounts of CPU cycles.
-
-Memory (RAM): the chunks index and the files index are read into memory for performance reasons.
-              compression, esp. lzma compression with high levels might need substantial amounts
-              of memory.
-
-Temporary files: reading data and metadata from a FUSE mounted repository will consume about the same space as the
-                 deduplicated chunks used to represent them in the repository.
-
-Cache files: chunks index and files index (plus a compressed collection of single-archive chunk indexes).
-
-Chunks index: proportional to the amount of data chunks in your repo. lots of small chunks in your repo implies a big
-              chunks index. you may need to tweak the chunker params (see create options) if you have a lot of data and
-              you want to keep the chunks index at some reasonable size.
-
-Files index: proportional to the amount of files in your last backup. can be switched off (see create options), but
-             next backup will be much slower if you do.
-
-Network: if your repository is remote, all deduplicated (and optionally compressed/encrypted) data of course has to go
-         over the connection (ssh: repo url). if you use a locally mounted network filesystem, additionally some copy
-         operations used for transaction support also go over the connection. if you backup multiple sources to one
-         target repository, additional traffic happens for cache resynchronization.
+CPU:
+    It won't go beyond 100% of 1 core as the code is currently single-threaded.
+    Especially higher zlib and lzma compression levels use significant amounts
+    of CPU cycles.
+
+Memory (RAM):
+    The chunks index and the files index are read into memory for performance
+    reasons.
+    Compression, esp. lzma compression with high levels might need substantial
+    amounts of memory.
+
+Temporary files:
+    Reading data and metadata from a FUSE mounted repository will consume about
+    the same space as the deduplicated chunks used to represent them in the
+    repository.
+
+Cache files:
+    Contains the chunks index and files index (plus a compressed collection of
+    single-archive chunk indexes).
+
+Chunks index:
+    Proportional to the amount of data chunks in your repo. Lots of small chunks
+    in your repo imply a big chunks index. You may need to tweak the chunker
+    params (see create options) if you have a lot of data and you want to keep
+    the chunks index at some reasonable size.
+
+Files index:
+    Proportional to the amount of files in your last backup. Can be switched
+    off (see create options), but next backup will be much slower if you do.
+
+Network:
+    If your repository is remote, all deduplicated (and optionally compressed/
+    encrypted) data of course has to go over the connection (ssh: repo url).
+    If you use a locally mounted network filesystem, additionally some copy
+    operations used for transaction support also go over the connection. If
+    you backup multiple sources to one target repository, additional traffic
+    happens for cache resynchronization.
 
 In case you are interested in more details, please read the internals documentation.