docs: backup-client: langauge and formatting fixup

also remove todo item for scheduling garbage collect with cron, and add
note about schedule configuration through proxmox-backup-manager/PBS GUI

Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>

docs/backup-client.rst

@@ -1,31 +1,33 @@
 Backup Client Usage
 ===================
 
-The command line client is called :command:`proxmox-backup-client`.
+The command line client for Proxmox Backup Server is called
+:command:`proxmox-backup-client`.
 
 .. _client_repository:
 
 Backup Repository Locations
 ---------------------------
 
-The client uses the following notation to specify a datastore repository
+The client uses the following format to specify a datastore repository
-on the backup server.
+on the backup server (where username is specified in the form of user@realm):
 
   [[username@]server[:port]:]datastore
 
 The default value for ``username`` is ``root@pam``. If no server is specified,
 the default is the local host (``localhost``).
 
-You can specify a port if your backup server is only reachable on a different
+You can specify a port if your backup server is only reachable on a non-default
-port (e.g. with NAT and port forwarding).
+port (for example, with NAT and port forwarding configurations).
 
-Note that if the server is an IPv6 address, you have to write it with square
+Note that if the server uses an IPv6 address, you have to write it with square
 brackets (for example, `[fe80::01]`).
 
 You can pass the repository with the ``--repository`` command line option, or
 by setting the ``PBS_REPOSITORY`` environment variable.
 
-Here some examples of valid repositories and the real values
+Below are some examples of valid repositories and their corresponding real
+values:
 
 ================================ ================== ================== ===========
 Example                          User               Host:Port          Datastore
@@ -46,8 +48,8 @@ Environment Variables
   The default backup repository.
 
 ``PBS_PASSWORD``
-  When set, this value is used for the password required for the backup server.
+  When set, this value is used as the password for the backup server.
-  You can also set this to a API token secret.
+  You can also set this to an API token secret.
 
 ``PBS_PASSWORD_FD``, ``PBS_PASSWORD_FILE``, ``PBS_PASSWORD_CMD``
   Like ``PBS_PASSWORD``, but read data from an open file descriptor, a file
@@ -63,15 +65,14 @@ Environment Variables
   a file name or from the `stdout` of a command, respectively. The first
   defined environment variable from the order above is preferred.
 
-``PBS_FINGERPRINT`` When set, this value is used to verify the server
+``PBS_FINGERPRINT``
-  certificate (only used if the system CA certificates cannot validate the
+  When set, this value is used to verify the server certificate (only used if
-  certificate).
+  the system CA certificates cannot validate the certificate).
 
 
-.. Note:: Passwords must be valid UTF8 an may not contain
+.. Note:: Passwords must be valid UTF-8 and may not contain newlines. For your
-   newlines. For your convienience, we just use the first line as
+   convienience, Proxmox Backup Server only uses the first line as password, so
-   password, so you can add arbitrary comments after the
+   you can add arbitrary comments after the first newline.
-   first newline.
 
 
 Output Format
@@ -86,14 +87,15 @@ Creating Backups
 ----------------
 
 This section explains how to create a backup from within the machine. This can
-be a physical host, a virtual machine, or a container. Such backups may contain file
+be a physical host, a virtual machine, or a container. Such backups may contain
-and image archives. There are no restrictions in this case.
+file and image archives. There are no restrictions in this case.
 
-.. note:: If you want to backup virtual machines or containers on Proxmox VE, see :ref:`pve-integration`.
+.. Note:: If you want to backup virtual machines or containers on Proxmox VE,
+   see :ref:`pve-integration`.
 
-For the following example you need to have a backup server set up, working
+For the following example, you need to have a backup server set up, have working
-credentials and need to know the repository name.
+credentials, and know the repository name.
-In the following examples we use ``backup-server:store1``.
+In the following examples, we use ``backup-server:store1``.
 
 .. code-block:: console
 
@@ -107,12 +109,12 @@ In the following examples we use ``backup-server:store1``.
   Uploaded 12129 chunks in 87 seconds (564 MB/s).
   End Time: 2019-12-03T10:36:29+01:00
 
-This will prompt you for a password and then uploads a file archive named
+This will prompt you for a password, then upload a file archive named
 ``root.pxar`` containing all the files in the ``/`` directory.
 
-.. Caution:: Please note that the proxmox-backup-client does not
+.. Caution:: Please note that proxmox-backup-client does not
    automatically include mount points. Instead, you will see a short
-   ``skip mount point`` notice for each of them. The idea is to
+   ``skip mount point`` message for each of them. The idea is to
    create a separate file archive for each mounted disk. You can
    explicitly include them using the ``--include-dev`` option
    (i.e. ``--include-dev /boot/efi``). You can use this option
@@ -120,19 +122,19 @@ This will prompt you for a password and then uploads a file archive named
 
 The ``--repository`` option can get quite long and is used by all
 commands. You can avoid having to enter this value by setting the
-environment variable ``PBS_REPOSITORY``. Note that if you would like this to remain set
+environment variable ``PBS_REPOSITORY``. Note that if you would like this to
-over multiple sessions, you should instead add the below line to your
+remain set over multiple sessions, you should instead add the below line to your
 ``.bashrc`` file.
 
 .. code-block:: console
 
   # export PBS_REPOSITORY=backup-server:store1
 
-After this you can execute all commands without specifying the ``--repository``
+After this, you can execute all commands without having to specify the
-option.
+``--repository`` option.
 
-One single backup is allowed to contain more than one archive. For example, if
+A single backup is allowed to contain more than one archive. For example, if
-you want to backup two disks mounted at ``/mnt/disk1`` and ``/mnt/disk2``:
+you want to back up two disks mounted at ``/mnt/disk1`` and ``/mnt/disk2``:
 
 .. code-block:: console
 
@@ -146,26 +148,26 @@ archive source at the client. The format is:
 
     <archive-name>.<type>:<source-path>
 
-Common types are ``.pxar`` for file archives, and ``.img`` for block
+Common types are ``.pxar`` for file archives and ``.img`` for block
-device images. To create a backup of a block device run the following command:
+device images. To create a backup of a block device, run the following command:
 
 .. code-block:: console
 
   # proxmox-backup-client backup mydata.img:/dev/mylvm/mydata
 
 
-Excluding files/folders from a backup
+Excluding Files/Directories from a Backup
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sometimes it is desired to exclude certain files or folders from a backup archive.
+Sometimes it is desired to exclude certain files or directories from a backup archive.
 To tell the Proxmox Backup client when and how to ignore files and directories,
-place a text file called ``.pxarexclude`` in the filesystem hierarchy.
+place a text file named ``.pxarexclude`` in the filesystem hierarchy.
 Whenever the backup client encounters such a file in a directory, it interprets
-each line as glob match patterns for files and directories that are to be excluded
+each line as a glob match pattern for files and directories that are to be excluded
 from the backup.
 
-The file must contain a single glob pattern per line. Empty lines are ignored.
+The file must contain a single glob pattern per line. Empty lines and lines
-The same is true for lines starting with ``#``, which indicates a comment.
+starting with ``#`` (indicating a comment) are ignored.
 A ``!`` at the beginning of a line reverses the glob match pattern from an exclusion
 to an explicit inclusion. This makes it possible to exclude all entries in a
 directory except for a few single files/subdirectories.
@@ -176,23 +178,24 @@ the given patterns. It is only possible to match files in this directory and its
 ``\`` is used to escape special glob characters.
 ``?`` matches any single character.
 ``*`` matches any character, including an empty string.
-``**`` is used to match subdirectories. It can be used to, for example, exclude
+``**`` is used to match current directory and subdirectories. For example, with
-all files ending in ``.tmp`` within the directory or subdirectories with the
+the pattern ``**/*.tmp``, it would exclude all files ending in ``.tmp`` within
-following pattern ``**/*.tmp``.
+a directory and its subdirectories.
 ``[...]`` matches a single character from any of the provided characters within
 the brackets. ``[!...]`` does the complementary and matches any single character
 not contained within the brackets. It is also possible to specify ranges with two
 characters separated by ``-``. For example, ``[a-z]`` matches any lowercase
-alphabetic character and ``[0-9]`` matches any one single digit.
+alphabetic character, and ``[0-9]`` matches any single digit.
 
 The order of the glob match patterns defines whether a file is included or
-excluded, that is to say later entries override previous ones.
+excluded, that is to say, later entries override earlier ones.
 This is also true for match patterns encountered deeper down the directory tree,
 which can override a previous exclusion.
-Be aware that excluded directories will **not** be read by the backup client.
+
-Thus, a ``.pxarexclude`` file in an excluded subdirectory will have no effect.
+.. Note:: Excluded directories will **not** be read by the backup client. Thus,
-``.pxarexclude`` files are treated as regular files and will be included in the
+   a ``.pxarexclude`` file in an excluded subdirectory will have no effect.
-backup archive.
+   ``.pxarexclude`` files are treated as regular files and will be included in
+   the backup archive.
 
 For example, consider the following directory structure:
 
@@ -280,7 +283,7 @@ You can avoid entering the passwords by setting the environment
 variables ``PBS_PASSWORD`` and ``PBS_ENCRYPTION_PASSWORD``.
 
 
-Using a master key to store and recover encryption keys
+Using a Master Key to Store and Recover Encryption Keys
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can also use ``proxmox-backup-client key`` to create an RSA public/private
@@ -360,7 +363,7 @@ To set up a master key:
   keep keys ordered and in a place that is separate from the contents being
   backed up. It can happen, for example, that you back up an entire system, using
   a key on that system. If the system then becomes inaccessible for any reason
-  and needs to be restored, this will not be possible as the encryption key will be
+  and needs to be restored, this will not be possible, as the encryption key will be
   lost along with the broken system.
 
 It is recommended that you keep your master key safe, but easily accessible, in
@@ -382,10 +385,10 @@ version of your master key. The following command sends the output of the
 Restoring Data
 --------------
 
-The regular creation of backups is a necessary step to avoiding data
+The regular creation of backups is a necessary step in avoiding data loss. More
-loss. More importantly, however, is the restoration. It is good practice to perform
+importantly, however, is the restoration. It is good practice to perform
-periodic recovery tests to ensure that you can access the data in
+periodic recovery tests to ensure that you can access the data in case of
-case of problems.
+disaster.
 
 First, you need to find the snapshot which you want to restore. The snapshot
 list command provides a list of all the snapshots on the server:
@@ -444,23 +447,22 @@ to use the interactive recovery shell.
 
 The interactive recovery shell is a minimal command line interface that
 utilizes the metadata stored in the catalog to quickly list, navigate and
-search files in a file archive.
+search for files in a file archive.
 To restore files, you can select them individually or match them with a glob
 pattern.
 
 Using the catalog for navigation reduces the overhead considerably because only
 the catalog needs to be downloaded and, optionally, decrypted.
-The actual chunks are only accessed if the metadata in the catalog is not enough
+The actual chunks are only accessed if the metadata in the catalog is
-or for the actual restore.
+insufficient or for the actual restore.
 
-Similar to common UNIX shells ``cd`` and ``ls`` are the commands used to change
+Similar to common UNIX shells, ``cd`` and ``ls`` are the commands used to change
 working directory and list directory contents in the archive.
 ``pwd`` shows the full path of the current working directory with respect to the
 archive root.
 
-Being able to quickly search the contents of the archive is a commonly needed feature.
+The ability to quickly search the contents of the archive is a commonly required
-That's where the catalog is most valuable.
+feature. That's where the catalog is most valuable. For example:
-For example:
 
 .. code-block:: console
 
@@ -471,8 +473,8 @@ For example:
   pxar:/ > restore-selected /target/path
   ...
 
-This will find and print all files ending in ``.txt`` located in ``etc/`` or a
+This will find and print all files ending in ``.txt`` located in ``etc/`` or its
-subdirectory and add the corresponding pattern to the list for subsequent restores.
+subdirectories, and add the corresponding pattern to the list for subsequent restores.
 ``list-selected`` shows these patterns and ``restore-selected`` finally restores
 all files in the archive matching the patterns to ``/target/path`` on the local
 host. This will scan the whole archive.
@@ -497,7 +499,7 @@ Mounting of Archives via FUSE
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The :term:`FUSE` implementation for the pxar archive allows you to mount a
-file archive as a read-only filesystem to a mountpoint on your host.
+file archive as a read-only filesystem to a mount point on your host.
 
 .. code-block:: console
 
@@ -513,7 +515,7 @@ This allows you to access the full contents of the archive in a seamless manner.
     load on your host, depending on the operations you perform on the mounted
     filesystem.
 
-To unmount the filesystem use the ``umount`` command on the mountpoint:
+To unmount the filesystem, use the ``umount`` command on the mount point:
 
 .. code-block:: console
 
@@ -522,7 +524,7 @@ To unmount the filesystem use the ``umount`` command on the mountpoint:
 Login and Logout
 ----------------
 
-The client tool prompts you to enter the logon password as soon as you
+The client tool prompts you to enter the login password as soon as you
 want to access the backup server. The server checks your credentials
 and responds with a ticket that is valid for two hours. The client
 tool automatically stores that ticket and uses it for further requests
@@ -551,7 +553,7 @@ Changing the Owner of a Backup Group
 By default, the owner of a backup group is the user which was used to originally
 create that backup group (or in the case of sync jobs, ``root@pam``). This
 means that if a user ``mike@pbs`` created a backup, another user ``john@pbs``
-can not be used to create backups in that same backup group.  In case you want
+can not be used to create backups in that same backup group. In case you want
 to change the owner of a backup, you can do so with the below command, using a
 user that has ``Datastore.Modify`` privileges on the datastore.
 
@@ -677,7 +679,7 @@ unused data blocks are removed.
    (access time) property. Filesystems are mounted with the ``relatime`` option
    by default. This results in a better performance by only updating the
    ``atime`` property if the last access has been at least 24 hours ago. The
-   downside is, that touching a chunk within these 24 hours will not always
+   downside is that touching a chunk within these 24 hours will not always
    update its ``atime`` property.
 
    Chunks in the grace period will be logged at the end of the garbage
@@ -701,8 +703,8 @@ unused data blocks are removed.
   Average chunk size: 2486565
   TASK OK
 
-
+Garbage collection can also be scheduled using ``promxox-backup-manager`` or
-.. todo:: howto run garbage-collection at regular intervals (cron)
+from the Proxmox Backup Server's web interface.
 
 Benchmarking
 ------------