Merge pull request #568 from ypid/docs-fixes

Docs fixes.

README.rst

@@ -165,7 +165,7 @@ for the complete license.
 
 .. |doc| image:: https://readthedocs.org/projects/borgbackup/badge/?version=stable
         :alt: Documentation
-        :target: http://borgbackup.readthedocs.org/en/stable/
+        :target: https://borgbackup.readthedocs.org/en/stable/
 
 .. |build| image:: https://travis-ci.org/borgbackup/borg.svg
         :alt: Build Status

borg/archiver.py

@@ -470,7 +470,7 @@ class Archiver:
         manifest, key = Manifest.load(repository)
         archives = manifest.list_archive_infos(sort_by='ts', reverse=True)  # just a ArchiveInfo list
         if args.hourly + args.daily + args.weekly + args.monthly + args.yearly == 0 and args.within is None:
-            self.print_error('At least one of the "within", "keep-hourly", "keep-daily", "keep-weekly", '
+            self.print_error('At least one of the "keep-within", "keep-hourly", "keep-daily", "keep-weekly", '
                              '"keep-monthly" or "keep-yearly" settings must be specified')
             return self.exit_code
         if args.prefix:

borg/testsuite/archiver.py

@@ -769,7 +769,7 @@ class ArchiverTestCase(ArchiverTestCaseBase):
         output = self.cmd('create', '-v', '--list', self.repository_location + '::test1', 'input')
         self.assert_in("U input/file1", output)
         # this is expected, although surprising, for why, see:
-        # http://borgbackup.readthedocs.org/en/latest/faq.html#i-am-seeing-a-added-status-for-a-unchanged-file
+        # https://borgbackup.readthedocs.org/en/latest/faq.html#i-am-seeing-a-added-status-for-a-unchanged-file
         self.assert_in("A input/file2", output)
 
     def test_create_topical(self):

docs/deployment.rst

@@ -73,8 +73,10 @@ The options which are added to the key will perform the following:
 3. Run ``borg serve`` restricted at the client base path
 4. Restrict ssh and do not allow stuff which imposes a security risk
 
-Due to the cd command we use, the server automatically changes the current working
-directory so the client will not need to append the hostname to the remote URI.
+Due to the ``cd`` command we use, the server automatically changes the current
+working directory. Then client doesn't need to have knowledge of the absolute
+or relative remote repository path and can directly access the repositories at
+``<user>@<host>:<repo>``.
 
 .. note:: The setup above ignores all client given commandline parameters
           which are normally appended to the `borg serve` command.
@@ -161,4 +163,4 @@ See also
 --------
 
 * `SSH Daemon manpage <http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man8/sshd.8>`_
-* `Ansible <http://docs.ansible.com>`_
+* `Ansible <https://docs.ansible.com>`_

docs/faq.rst

@@ -67,14 +67,14 @@ adjust the level or algorithm).
 
 |project_name| offers a lot of different compression algorithms and
 levels. Which of them is the best for you pretty much depends on your
-use case, your data, your hardware - so you need to do an informed
+use case, your data, your hardware -- so you need to do an informed
 decision about whether you want to use compression, which algorithm
 and which level you want to use. This is why compression defaults to
 none.
 
 How can I specify the encryption passphrase programmatically?
 -------------------------------------------------------------
-      
+
 The encryption passphrase can be specified programmatically using the
 `BORG_PASSPHRASE` environment variable. This is convenient when setting up
 automated encrypted backups. Another option is to use
@@ -89,11 +89,11 @@ key file based encryption with a blank passphrase. See
           ``export`` in a shell script file should be safe, however, as
           the environment of a process is `accessible only to that
           user
-          <http://security.stackexchange.com/questions/14000/environment-variable-accessibility-in-linux/14009#14009>`_.
+          <https://security.stackexchange.com/questions/14000/environment-variable-accessibility-in-linux/14009#14009>`_.
 
 When backing up to remote encrypted repos, is encryption done locally?
 ----------------------------------------------------------------------
-     
+
 Yes, file and directory metadata and data is locally encrypted, before
 leaving the local machine. We do not mean the transport layer encryption
 by that, but the data/metadata itself. Transport layer encryption (e.g.

docs/global.rst.inc

@@ -8,17 +8,17 @@
 .. _issue tracker: https://github.com/borgbackup/borg/issues
 .. _deduplication: https://en.wikipedia.org/wiki/Data_deduplication
 .. _AES: https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
-.. _HMAC-SHA256: http://en.wikipedia.org/wiki/HMAC
+.. _HMAC-SHA256: https://en.wikipedia.org/wiki/HMAC
 .. _SHA256: https://en.wikipedia.org/wiki/SHA-256
 .. _PBKDF2: https://en.wikipedia.org/wiki/PBKDF2
 .. _ACL: https://en.wikipedia.org/wiki/Access_control_list
-.. _libacl: http://savannah.nongnu.org/projects/acl/
-.. _libattr: http://savannah.nongnu.org/projects/attr/
+.. _libacl: https://savannah.nongnu.org/projects/acl/
+.. _libattr: https://savannah.nongnu.org/projects/attr/
 .. _liblz4: https://github.com/Cyan4973/lz4
 .. _OpenSSL: https://www.openssl.org/
-.. _`Python 3`: http://www.python.org/
+.. _`Python 3`: https://www.python.org/
 .. _Buzhash: https://en.wikipedia.org/wiki/Buzhash
-.. _msgpack: http://msgpack.org/
+.. _msgpack: https://msgpack.org/
 .. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/
 .. _llfuse: https://pypi.python.org/pypi/llfuse/
 .. _homebrew: http://brew.sh/

docs/internals.rst

@@ -207,7 +207,7 @@ The |project_name| chunker uses a rolling hash computed by the Buzhash_ algorith
 It triggers (chunks) when the last HASH_MASK_BITS bits of the hash are zero,
 producing chunks of 2^HASH_MASK_BITS Bytes on average.
 
-create --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE
+``borg create --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
 can be used to tune the chunker parameters, the default is:
 
 - CHUNK_MIN_EXP = 10 (minimum chunk size = 2^10 B = 1 kiB)
@@ -220,7 +220,7 @@ for the archive, and stored encrypted in the keyfile. This is to prevent chunk
 size based fingerprinting attacks on your encrypted repo contents (to guess
 what files you have based on a specific set of chunk sizes).
 
-For some more general usage hints see also `--chunker-params`.
+For some more general usage hints see also ``--chunker-params``.
 
 
 Indexes / Caches
@@ -311,28 +311,27 @@ more chunks than estimated above, because 1 file is at least 1 chunk).
 
 If a remote repository is used the repo index will be allocated on the remote side.
 
-E.g. backing up a total count of 1Mi files with a total size of 1TiB.
+E.g. backing up a total count of 1 Mi (IEC binary prefix e.g. 2^20) files with a total size of 1TiB.
 
-a) with create --chunker-params 10,23,16,4095 (default):
+a) with create ``--chunker-params 10,23,16,4095`` (default):
 
   mem_usage  =  2.8GiB
 
-b) with create --chunker-params 10,23,20,4095 (custom):
+b) with create ``--chunker-params 10,23,20,4095`` (custom):
 
   mem_usage  =  0.4GiB
 
-Note: there is also the --no-files-cache option to switch off the files cache.
-You'll save some memory, but it will need to read / chunk all the files then as
-it can not skip unmodified files then.
-
+.. note:: There is also the ``--no-files-cache`` option to switch off the files cache.
+   You'll save some memory, but it will need to read / chunk all the files as
+   it can not skip unmodified files then.
 
 Encryption
 ----------
 
-AES_ is used in CTR mode (so no need for padding). A 64bit initialization
+AES_-256 is used in CTR mode (so no need for padding). A 64bit initialization
 vector is used, a `HMAC-SHA256`_ is computed on the encrypted chunk with a
 random 64bit nonce and both are stored in the chunk.
-The header of each chunk is : ``TYPE(1)`` + ``HMAC(32)`` + ``NONCE(8)`` + ``CIPHERTEXT``.
+The header of each chunk is: ``TYPE(1)`` + ``HMAC(32)`` + ``NONCE(8)`` + ``CIPHERTEXT``.
 Encryption and HMAC use two different keys.
 
 In AES CTR mode you can think of the IV as the start value for the counter.

docs/quickstart.rst

@@ -17,7 +17,7 @@ a good amount of free space on the filesystem that has your backup repository
 
 If you run out of disk space, it can be hard or impossible to free space,
 because |project_name| needs free space to operate - even to delete backup
-archives. There is a `--save-space` option for some commands, but even with
+archives. There is a ``--save-space`` option for some commands, but even with
 that |project_name| will need free space to operate.
 
 You can use some monitoring process or just include the free space information

docs/usage.rst

@@ -18,9 +18,9 @@ The log level of the builtin logging configuration defaults to WARNING.
 This is because we want |project_name| to be mostly silent and only output
 warnings (plus errors and critical messages).
 
-Use --verbose or --info to set INFO (you will get informative output then
+Use ``--verbose`` or ``--info`` to set INFO (you will get informative output then
 additionally to warnings, errors, critical messages).
-Use --debug to set DEBUG to get output made for debugging.
+Use ``--debug`` to set DEBUG to get output made for debugging.
 
 All log messages created with at least the set level will be output.
 
@@ -29,9 +29,9 @@ Log levels: DEBUG < INFO < WARNING < ERROR < CRITICAL
 While you can set misc. log levels, do not expect that every command will
 give different output on different log levels - it's just a possibility.
 
-..warning:: While some options (like --stats or --list) will emit more
+.. warning:: While some options (like ``--stats`` or ``--list``) will emit more
 informational messages, you have to use INFO (or lower) log level to make
-them show up in log output. Use `-v` or a logging configuration.
+them show up in log output. Use ``-v`` or a logging configuration.
 
 Return codes
 ~~~~~~~~~~~~
@@ -75,7 +75,7 @@ Some "yes" sayers (if set, they automatically confirm that you really want to do
     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."
+        For "Warning: '``check --repair``' is an experimental feature that might result in data loss."
     BORG_DELETE_I_KNOW_WHAT_I_AM_DOING
         For "You requested to completely DELETE the repository *including* all archives it contains:  "
 
@@ -334,11 +334,11 @@ Be careful, prune is potentially dangerous command, it will remove backup
 archives.
 
 The default of prune is to apply to **all archives in the repository** unless
-you restrict its operation to a subset of the archives using `--prefix`.
-When using --prefix, be careful to choose a good prefix - e.g. do not use a
+you restrict its operation to a subset of the archives using ``--prefix``.
+When using ``--prefix``, be careful to choose a good prefix - e.g. do not use a
 prefix "foo" if you do not also want to match "foobar".
 
-It is strongly recommended to always run `prune --dry-run ...` first so you
+It is strongly recommended to always run ``prune --dry-run ...`` first so you
 will see what it would do without it actually doing anything.
 
 ::
@@ -457,17 +457,17 @@ Here are misc. notes about topics that are maybe not covered in enough detail in
 Item flags
 ~~~~~~~~~~
 
-`borg create -v --list` outputs a verbose list of all files, directories and other
+``borg create -v --list`` outputs a verbose list of all files, directories and other
 file system items it considered (no matter whether they had content changes
 or not). For each item, it prefixes a single-letter flag that indicates type
 and/or status of the item.
 
 If you are interested only in a subset of that output, you can give e.g.
-`--filter=AME` and it will only show regular files with A, M or E status (see
+``--filter=AME`` and it will only show regular files with A, M or E status (see
 below).
 
 A uppercase character represents the status of a regular file relative to the
-"files" cache (not relative to the repo - this is an issue if the files cache
+"files" cache (not relative to the repo -- this is an issue if the files cache
 is not used). Metadata is stored in any case and for 'A' and 'M' also new data
 chunks are stored. For 'U' all data chunks refer to already existing chunks.
 
@@ -501,12 +501,12 @@ resource usage (RAM and disk space) as the amount of resources needed is
 (also) determined by the total amount of chunks in the repository (see
 `Indexes / Caches memory usage` for details).
 
-`--chunker-params=10,23,16,4095 (default)` results in a fine-grained deduplication
+``--chunker-params=10,23,16,4095 (default)`` results in a fine-grained deduplication
 and creates a big amount of chunks and thus uses a lot of resources to manage them.
 This is good for relatively small data volumes and if the machine has a good
 amount of free RAM and disk space.
 
-`--chunker-params=19,23,21,4095` results in a coarse-grained deduplication and
+``--chunker-params=19,23,21,4095`` results in a coarse-grained deduplication and
 creates a much smaller amount of chunks and thus uses less resources.
 This is good for relatively big data volumes and if the machine has a relatively
 low amount of free RAM and disk space.
@@ -519,10 +519,11 @@ In the worst case (all files are big and were touched in between backups), this
 will store all content into the repository again.
 
 Usually, it is not that bad though:
+
 - usually most files are not touched, so it will just re-use the old chunks
-it already has in the repo
+  it already has in the repo
 - files smaller than the (both old and new) minimum chunksize result in only
-one chunk anyway, so the resulting chunks are same and deduplication will apply
+  one chunk anyway, so the resulting chunks are same and deduplication will apply
 
 If you switch chunker params to save resources for an existing repo that
 already has some backup archives, you will see an increasing effect over time,
@@ -556,7 +557,7 @@ You need to be careful with what you give as filename when using ``--read-specia
 e.g. if you give ``/dev/zero``, your backup will never terminate.
 
 The given files' metadata is saved as it would be saved without
-``--read-special`` (e.g. its name, its size [might be 0], its mode, etc.) - but
+``--read-special`` (e.g. its name, its size [might be 0], its mode, etc.) -- but
 additionally, also the content read from it will be saved for it.
 
 Restoring such files' content is currently only supported one at a time via