Fix various code blocks in the docs (#4708)

Fix various code blocks in the docs

- rst markup: put codeblock markup on separate line to make it better visible / separate it from normal text colons.

- borg help texts in archiver.py: put codeblock markup instead of colon - that way it looks like a single colon when using the cli help and also works as code block markup.

docs/deployment/central-backup-server.rst

@@ -91,16 +91,22 @@ Client
 
 The client needs to initialize the `pictures` repository like this:
 
+::
+
  borg init backup@backup01.srv.local:pictures
 
 Or with the full path (should actually never be used, as only for demonstrational purposes).
 The server should automatically change the current working directory to the `<client fqdn>` folder.
 
+::
+
   borg init backup@backup01.srv.local:/home/backup/repos/johndoe.clnt.local/pictures
 
 When `johndoe.clnt.local` tries to access a not restricted path the following error is raised.
 John Doe tries to backup into the Web 01 path:
 
+::
+
   borg init backup@backup01.srv.local:/home/backup/repos/web01.srv.local/pictures
 
 ::

docs/deployment/hosting-repositories.rst

@@ -42,13 +42,13 @@ SSH access to safe operations only.
 	with no control characters and that it consists of three parts separated
 	by a single space. Ensure that no newlines are contained within the key.
 
-The `restrict` keyword enables all restrictions, i.e. disables port, agent
+The ``restrict`` keyword enables all restrictions, i.e. disables port, agent
 and X11 forwarding, as well as disabling PTY allocation and execution of ~/.ssh/rc.
 If any future restriction capabilities are added to authorized_keys
 files they will be included in this set.
 
-The `command` keyword forces execution of the specified command line
-upon login. This must be ``borg serve``. The `--restrict-to-repository`
+The ``command`` keyword forces execution of the specified command line
+upon login. This must be ``borg serve``. The ``--restrict-to-repository``
 option permits access to exactly **one** repository. It can be given
 multiple times to permit access to more than one repository.
 

docs/development.rst

@@ -200,11 +200,15 @@ Running more checks using coala
 
 First install coala and some checkers ("bears"):
 
+::
+
   pip install -r requirements.d/coala.txt
 
 You can now run coala from the toplevel directory; it will read its settings
 from ``.coafile`` there:
 
+::
+
   coala
 
 Some bears have additional requirements and they usually tell you about
@@ -333,13 +337,17 @@ Checklist:
   do a fresh start based on that.
 - run tox and/or binary builds on all supported platforms via vagrant,
   check for test failures
-- create sdist, sign it, upload release to (test) PyPi::
+- create sdist, sign it, upload release to (test) PyPi:
+
+  ::
 
     scripts/sdist-sign X.Y.Z
     scripts/upload-pypi X.Y.Z test
     scripts/upload-pypi X.Y.Z
 - put binaries into dist/borg-OSNAME and sign them:
 
+  ::
+
     scripts/sign-binaries 201912312359
 - close the release milestone on GitHub
 - announce on:

docs/faq.rst

@@ -673,7 +673,9 @@ There is no built-in way to limit *download*
 (i.e. :ref:`borg_extract`) bandwidth, but limiting download bandwidth
 can be accomplished with pipeviewer_:
 
-Create a wrapper script:  /usr/local/bin/pv-wrapper  ::
+Create a wrapper script:  /usr/local/bin/pv-wrapper
+
+::
 
     #!/bin/sh
         ## -q, --quiet              do not output any transfer information at all
@@ -681,11 +683,15 @@ Create a wrapper script:  /usr/local/bin/pv-wrapper  ::
     RATE=307200
     pv -q -L $RATE  | "$@"
 
-Add BORG_RSH environment variable to use pipeviewer wrapper script with ssh. ::
+Add BORG_RSH environment variable to use pipeviewer wrapper script with ssh.
+
+::
 
     export BORG_RSH='/usr/local/bin/pv-wrapper ssh'
 
-Now Borg will be bandwidth limited. Nice thing about pv is that you can change rate-limit on the fly: ::
+Now Borg will be bandwidth limited. Nice thing about pv is that you can change rate-limit on the fly:
+
+::
 
     pv -R $(pidof pv) -L 102400
 

docs/installation.rst

@@ -321,7 +321,9 @@ Using git
 ~~~~~~~~~
 
 This uses latest, unreleased development code from git.
-While we try not to break master, there are no guarantees on anything. ::
+While we try not to break master, there are no guarantees on anything.
+
+::
 
     # get borg from github
     git clone https://github.com/borgbackup/borg.git
@@ -342,7 +344,9 @@ While we try not to break master, there are no guarantees on anything. ::
     fakeroot -u tox
 
 By default the system installation of python will be used.
-If you need to use a different version of Python you can install this using ``pyenv``: ::
+If you need to use a different version of Python you can install this using ``pyenv``:
+
+::
 
     ...
     # create a virtual environment

docs/quickstart.rst

@@ -224,7 +224,7 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac
     # actually free repo disk space by compacting segments
 
     info "Compacting repository"
-    
+
     borg compact
 
     compact_exit=$?
@@ -240,7 +240,7 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac
     else
         info "Backup, Prune, and/or Compact finished with errors"
     fi
-    
+
     exit ${global_exit}
 
 Pitfalls with shell variables and environment variables
@@ -327,7 +327,7 @@ compression) using N=1 to high compression (and lower speed) using N=22.
 
 zstd is a modern compression algorithm and might be preferable over zlib and
 lzma, except if you need compatibility to older borg versions (< 1.1.4) that
-did not yet offer zstd.
+did not yet offer zstd.::
 
     $ borg create --compression zstd,N /path/to/repo::arch ~
 
@@ -338,12 +338,16 @@ If you have a fast repo storage and you want minimum CPU usage, no compression::
     $ borg create --compression none /path/to/repo::arch ~
 
 If you have a less fast repo storage and you want a bit more compression (N=0..9,
-0 means no compression, 9 means high compression): ::
+0 means no compression, 9 means high compression):
+
+::
 
     $ borg create --compression zlib,N /path/to/repo::arch ~
 
 If you have a very slow repo storage and you want high compression (N=0..9, 0 means
-low compression, 9 means high compression): ::
+low compression, 9 means high compression):
+
+::
 
     $ borg create --compression lzma,N /path/to/repo::arch ~
 

docs/usage/notes.rst

@@ -142,14 +142,18 @@ original volumes continue changing the data stored there.
 You also add the output of ``lvdisplay`` to your backup, so you can see the LV
 sizes in case you ever need to recreate and restore them.
 
-After the backup has completed, you remove the snapshots again. ::
+After the backup has completed, you remove the snapshots again.
+
+::
 
     $ # create snapshots here
     $ lvdisplay > lvdisplay.txt
     $ borg create --read-special /path/to/repo::arch lvdisplay.txt /dev/vg0/*-snapshot
     $ # remove snapshots here
 
-Now, let's see how to restore some LVs from such a backup. ::
+Now, let's see how to restore some LVs from such a backup.
+
+::
 
     $ borg extract /path/to/repo::arch lvdisplay.txt
     $ # create empty LVs with correct sizes here (look into lvdisplay.txt).
@@ -204,7 +208,9 @@ append-only is useful for scenarios where a backup client machine backups
 remotely to a backup server using ``borg serve``, since a hacked client machine
 cannot delete backups on the server permanently.
 
-To activate append-only mode, set ``append_only`` to 1 in the repository config::
+To activate append-only mode, set ``append_only`` to 1 in the repository config:
+
+::
 
     borg config /path/to/repo append_only 1
 
@@ -216,7 +222,9 @@ where each line is a transaction and a UTC timestamp.
 
 In addition, ``borg serve`` can act as if a repository is in append-only mode with
 its option ``--append-only``. This can be very useful for fine-tuning access control
-in ``.ssh/authorized_keys`` ::
+in ``.ssh/authorized_keys``:
+
+::
 
     command="borg serve --append-only ..." ssh-rsa <key used for not-always-trustable backup clients>
     command="borg serve ..." ssh-rsa <key used for backup management>
@@ -229,7 +237,9 @@ Example
 +++++++
 
 Suppose an attacker remotely deleted all backups, but your repository was in append-only
-mode. A transaction log in this situation might look like this: ::
+mode. A transaction log in this situation might look like this:
+
+::
 
     transaction 1, UTC time 2016-03-31T15:53:27.383532
     transaction 5, UTC time 2016-03-31T15:53:52.588922

src/borg/archiver.py

@@ -2633,9 +2633,9 @@ class Archiver:
 
         Make sure you have free space there, you'll need about 1GB each (+ overhead).
 
-        If your repository is encrypted and borg needs a passphrase to unlock the key, use:
+        If your repository is encrypted and borg needs a passphrase to unlock the key, use::
 
-        BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
+            BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
 
         Measurements are done with different input file sizes and counts.
         The file contents are very artificial (either all zero or all random),
@@ -4152,7 +4152,7 @@ class Archiver:
         Upgrade should be able to resume if interrupted, although it
         will still iterate over all segments. If you want to start
         from scratch, use `borg delete` over the copied repository to
-        make sure the cache files are also removed:
+        make sure the cache files are also removed::
 
             borg delete borg