Docs grammar fixes

joined split infinitives, and relocated adverbs appropriately.

Author: systemcrash

docs/changes_0.x.rst

@@ -8,8 +8,8 @@ Version 0.30.0 (2016-01-23)
 
 Compatibility notes:
 
-- you may need to use -v (or --info) more often to actually see output emitted
-  at INFO log level (because it is suppressed at the default WARNING log level).
+- The new default logging level is WARNING. Previously, it was INFO, which was
+  more verbose. Use -v (or --info) to show once again log level INFO messages.
   See the "general" section in the usage docs.
 - for borg create, you need --list (additionally to -v) to see the long file
   list (was needed so you can have e.g. --stats alone without the long list)

docs/changes_1.x.rst

@@ -776,7 +776,7 @@ Other changes:
 - docs:
 
   - improve description of path variables
-  - document how to completely delete data, #2929
+  - document how to delete data completely, #2929
   - add FAQ about Borg config dir, #4941
   - add docs about errors not printed as JSON, #4073
   - update usage_general.rst.inc
@@ -2149,7 +2149,7 @@ New features:
 - mount: added exclusion group options and paths, #2138
 
   Reused some code to support similar options/paths as borg extract offers -
-  making good use of these to only mount a smaller subset of dirs/files can
+  making good use of these to mount only a smaller subset of dirs/files can
   speed up mounting a lot and also will consume way less memory.
 
   borg mount [options] repo_or_archive mountpoint path [paths...]
@@ -3078,7 +3078,7 @@ New features:
     which includes the SHA1 and SHA2 family as well as MD5
 - borg prune:
 
-  - to better visualize the "thinning out", we now list all archives in
+  - to visualize the "thinning out" better, we now list all archives in
     reverse time order. rephrase and reorder help text.
   - implement --keep-last N via --keep-secondly N, also --keep-minutely.
     assuming that there is not more than 1 backup archive made in 1s,
@@ -3505,8 +3505,18 @@ Security fixes:
 
   CVE-2016-10099 was assigned to this vulnerability.
 - borg check: When rebuilding the manifest (which should only be needed very rarely)
-  duplicate archive names would be handled on a "first come first serve" basis, allowing
-  an attacker to apparently replace archives.
+  duplicate archive names would be handled on a "first come first serve" basis,
+  potentially opening an attack vector to replace archives.
+
+  Example: were there 2 archives named "foo" in a repo (which can not happen
+  under normal circumstances, because borg checks if the name is already used)
+  and a "borg check" recreated a (previously lost) manifest, the first of the
+  archives it encountered would be in the manifest. The second archive is also
+  still in the repo, but not referenced in the manifest, in this case. If the
+  second archive is the "correct" one (and was previously referenced from the
+  manifest), it looks like it got replaced by the first one. In the manifest,
+  it actually got replaced. Both remain in the repo but the "correct" one is no
+  longer accessible via normal means - the manifest.
 
   CVE-2016-10100 was assigned to this vulnerability.
 
@@ -4234,20 +4244,20 @@ Compatibility notes:
   changed file and in the worst case (e.g. if your files cache was lost / is
   not used) by the size of every file (minus any compression you might use).
 
-  in case you want to immediately see a much lower resource usage (RAM / disk)
+  in case you want to see a much lower resource usage immediately (RAM / disk)
   for chunks management, it might be better to start with a new repo than
-  continuing in the existing repo (with an existing repo, you'ld have to wait
-  until all archives with small chunks got pruned to see a lower resource
+  to continue in the existing repo (with an existing repo, you have to wait
+  until all archives with small chunks get pruned to see a lower resource
   usage).
 
   if you used the old --chunker-params default value (or if you did not use
-  --chunker-params option at all) and you'ld like to continue using small
+  --chunker-params option at all) and you'd like to continue using small
   chunks (and you accept the huge resource usage that comes with that), just
-  explicitly use borg create --chunker-params=10,23,16,4095.
+  use explicitly borg create --chunker-params=10,23,16,4095.
 - archive timestamps: the 'time' timestamp now refers to archive creation
   start time (was: end time), the new 'time_end' timestamp refers to archive
-  creation end time. This might affect prune if your backups take rather long.
-  if you give a timestamp via cli this is stored into 'time', therefore it now
+  creation end time. This might affect prune if your backups take a long time.
+  if you give a timestamp via cli, this is stored into 'time'. therefore it now
   needs to mean archive creation start time.
 
 New features:
@@ -4289,8 +4299,8 @@ Bug fixes:
 
 Other changes:
 
-- it is now possible to use "pip install borgbackup[fuse]" to automatically
-  install the llfuse dependency using the correct version requirement
+- it is now possible to use "pip install borgbackup[fuse]" to
+  install the llfuse dependency automatically, using the correct version requirement
   for it. you still need to care about having installed the FUSE / build
   related OS package first, though, so that building llfuse can succeed.
 - Vagrant: drop Ubuntu Precise (12.04) - does not have Python >= 3.4

docs/deployment/automated-local.rst

@@ -168,13 +168,13 @@ after creating the backup. Rename the file to something else (e.g. ``/etc/backup
 when you want to do something with the drive after creating backups (e.g running check).
 
 Create the ``/etc/backups/backup-suspend`` file if the machine should suspend after completing
-the backup. Don't forget to physically disconnect the device before resuming,
+the backup. Don't forget to disconnect the device physically before resuming,
 otherwise you'll enter a cycle. You can also add an option to power down instead.
 
 Create an empty ``/etc/backups/backup.disks`` file, you'll register your backup drives
 there.
 
-The last part is to actually enable the udev rules and services:
+The last part is actually to enable the udev rules and services:
 
 .. code-block:: bash
 

docs/deployment/hosting-repositories.rst

@@ -5,7 +5,7 @@
 Hosting repositories
 ====================
 
-This sections shows how to securely provide repository storage for users.
+This sections shows how to provide repository storage securely for users.
 Optionally, each user can have a storage quota.
 
 Repositories are accessed through SSH. Each user of the service should

docs/deployment/image-backup.rst

@@ -77,7 +77,7 @@ Because the partitions were zeroed in place, restoration is only one command::
     borg extract --stdout repo::hostname-disk | dd of=$DISK
 
 .. note:: The "traditional" way to zero out space on a partition, especially one already
-          mounted, is to simply ``dd`` from ``/dev/zero`` to a temporary file and delete
+          mounted, is simply to ``dd`` from ``/dev/zero`` to a temporary file and delete
           it. This is ill-advised for the reasons mentioned in the ``zerofree`` man page:
 
           - it is slow

docs/deployment/pull-backup.rst

@@ -161,7 +161,7 @@ Now we can run
 
     borg extract /borgrepo::archive PATH
 
-to partially restore whatever we like. Finally, do the clean-up:
+to restore whatever we like partially. Finally, do the clean-up:
 
 ::
 
@@ -209,8 +209,8 @@ socat
 =====
 
 In this setup a SSH connection from the backup server to the client is
-established that uses SSH reverse port forwarding to transparently
-tunnel data between UNIX domain sockets on the client and server and the socat
+established that uses SSH reverse port forwarding to tunnel data
+transparently between UNIX domain sockets on the client and server and the socat
 tool to connect these with the borg client and server processes, respectively.
 
 The program socat has to be available on the backup server and on the client
@@ -277,7 +277,7 @@ forwarding can do this for us::
 
       Warning: remote port forwarding failed for listen path /run/borg/reponame.sock
 
-   When you are done, you have to manually remove the socket file, otherwise
+   When you are done, you have to remove the socket file manually, otherwise
    you may see an error like this when trying to execute borg commands::
 
       Remote: YYYY/MM/DD HH:MM:SS socat[XXX] E connect(5, AF=1 "/run/borg/reponame.sock", 13): Connection refused
@@ -417,7 +417,7 @@ Parentheses are not needed when using a dedicated bash process.
 
   *ssh://borgs@borg-server/~/repo* refers to the repository *repo* within borgs's home directory on *borg-server*.
 
-  *StrictHostKeyChecking=no* is used to automatically add host keys to *~/.ssh/known_hosts* without user intervention.
+  *StrictHostKeyChecking=no* is used to add host keys automatically to *~/.ssh/known_hosts* without user intervention.
 
 ``kill "${SSH_AGENT_PID}"``
 

docs/faq.rst

@@ -86,7 +86,7 @@ run into this by yourself by restoring an older copy of your repository.
 "attack": maybe an attacker has replaced your repo by an older copy, trying to
 trick you into AES counter reuse, trying to break your repo encryption.
 
-If you'ld decide to ignore this and accept unsafe operation for this repository,
+If you decide to ignore this and accept unsafe operation for this repository,
 you could delete the manifest-timestamp and the local cache:
 
 ::
@@ -159,7 +159,7 @@ so that checkpoints even work while a big file is being processed.
 They are named ``<filename>.borg_part_<N>`` and all operations usually ignore
 these files, but you can make them considered by giving the option
 ``--consider-part-files``. You usually only need that option if you are
-really desperate (e.g. if you have no completed backup of that file and you'ld
+really desperate (e.g. if you have no completed backup of that file and you'd
 rather get a partial file extracted than nothing). You do **not** want to give
 that option under any normal circumstances.
 
@@ -342,7 +342,7 @@ That's **45** orders of magnitude more probable than the SHA-256 collision. Brie
 if you find SHA-256 collisions scary then your priorities are wrong. This example was grabbed from
 `this SO answer <https://stackoverflow.com/a/4014407/13359375>`_, it's great honestly.
 
-Still, the real question is if Borg tries not to make this happen?
+Still, the real question is whether Borg tries not to make this happen?
 
 Well... previously it did not check anything until there was a feature added which saves the size
 of the chunks too, so the size of the chunks is compared to the size that you got with the
@@ -467,7 +467,7 @@ Setting ``BORG_PASSPHRASE``
           user
           <https://security.stackexchange.com/questions/14000/environment-variable-accessibility-in-linux/14009#14009>`_.
 
-Using ``BORG_PASSCOMMAND`` with a properly permissioned file
+Using ``BORG_PASSCOMMAND`` with a file of proper permissions
   Another option is to create a file with a password in it in your home
   directory and use permissions to keep anyone else from reading it. For
   example, first create a key::
@@ -524,7 +524,7 @@ Using ``BORG_PASSCOMMAND`` with GNOME Keyring
 
     export BORG_PASSCOMMAND="secret-tool lookup borg-repository repo-name"
 
-  .. note:: For this to automatically unlock the keychain it must be run
+  .. note:: For this to unlock the keychain automatically it must be run
     in the ``dbus`` session of an unlocked terminal; for example, running a backup
     script as a ``cron`` job might not work unless you also ``export DISPLAY=:0``
     so ``secret-tool`` can pick up your open session. `It gets even more complicated`__
@@ -573,7 +573,7 @@ C to delete all backups residing on S.
 
 These are your options to protect against that:
 
-- Do not allow to permanently delete data from the repo, see :ref:`append_only_mode`.
+- Do not allow to delete data permanently from the repo, see :ref:`append_only_mode`.
 - Use a pull-mode setup using ``ssh -R``, see :ref:`pull_backup` for more information.
 - Mount C's filesystem on another machine and then create a backup of it.
 - Do not give C filesystem-level access to S.
@@ -853,7 +853,7 @@ Then you do the backup and look at the log output:
   The metadata values used in this comparison are determined by the ``--files-cache`` option
   and could be e.g. size, ctime and inode number (see the ``borg create`` docs for more
   details and potential issues).
-  You can use the ``stat`` command on files to manually look at fs metadata to debug if
+  You can use the ``stat`` command on files to look at fs metadata manually to debug if
   there is any unexpected change triggering the ``M`` status.
   Also, the ``--debug-topic=files_cache`` option of ``borg create`` provides a lot of debug
   output helping to analyse why the files cache does not give its expected high performance.

docs/installation.rst

@@ -134,7 +134,7 @@ fail if /tmp has not enough free space or is mounted with the ``noexec``
 option. You can change the temporary directory by setting the ``TEMP``
 environment variable before running Borg.
 
-If a new version is released, you will have to manually download it and replace
+If a new version is released, you will have to download it manually and replace
 the old version using the same steps as shown above.
 
 .. _pyinstaller: http://www.pyinstaller.org
@@ -331,7 +331,7 @@ optional, but recommended except for the most simple use cases.
     If you install into a virtual environment, you need to **activate** it
     first (``source borg-env/bin/activate``), before running ``borg``.
     Alternatively, symlink ``borg-env/bin/borg`` into some directory that is in
-    your ``PATH`` so you can just run ``borg``.
+    your ``PATH`` so you can run ``borg``.
 
 This will use ``pip`` to install the latest release from PyPi::
 

docs/internals.rst

@@ -22,7 +22,7 @@ metadata, using :ref:`chunks` created by the chunker using the
 Buzhash_ algorithm ("buzhash" chunker) or a simpler fixed blocksize
 algorithm ("fixed" chunker).
 
-To actually perform the repository-wide deduplication, a hash of each
+To perform the repository-wide deduplication, a hash of each
 chunk is checked against the :ref:`chunks cache <cache>`, which is a
 hash-table of all chunks that already exist.
 

docs/internals/data-structures.rst

@@ -157,8 +157,8 @@ An object (the payload part of a segment file log entry) must be like:
 
   - compressed data (with an optional all-zero-bytes obfuscation trailer)
 
-This new, more complex repo v2 object format was implemented to be able to efficiently
-query the metadata without having to read, transfer and decrypt the (usually much bigger)
+This new, more complex repo v2 object format was implemented to be able to query the
+metadata efficiently without having to read, transfer and decrypt the (usually much bigger)
 data part.
 
 The metadata is encrypted not to disclose potentially sensitive information that could be