[pbs-devel] [PATCH proxmox-backup] tape: documentation language fixup

[pbs-devel] [PATCH proxmox-backup] tape: documentation language fixup

[Dylan Whyte]

Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
---
 docs/pmt/options.rst |   4 +-
 docs/tape-backup.rst | 220 +++++++++++++++++++++----------------------
 2 files changed, 112 insertions(+), 112 deletions(-)

diff --git a/docs/pmt/options.rst b/docs/pmt/options.rst
index adf2ff06..ac8a91e4 100644
--- a/docs/pmt/options.rst
+++ b/docs/pmt/options.rst
@@ -1,11 +1,11 @@
-All command supports the following parameters to specify the tape device:
+All commands support the following parameters to specify the tape device:
 
 --device <path>  Path to the Linux tape device
 
 --drive <name>  Use drive from Proxmox Backup Server configuration.
 
 
-Commands generating output supports the ``--output-format``
+Commands which generate output support the ``--output-format``
 parameter. It accepts the following values:
 
 :``text``: Text format (default). Human readable.
diff --git a/docs/tape-backup.rst b/docs/tape-backup.rst
index b39ab36c..6b523865 100644
--- a/docs/tape-backup.rst
+++ b/docs/tape-backup.rst
@@ -4,7 +4,7 @@ Tape Backup
 ===========
 
 .. CAUTION:: Tape Backup is a technical preview feature, not meant for
-   production usage. To enable the GUI, you need to issue the
+   production use. To enable it in the GUI, you need to issue the
    following command (as root user on the console):
 
    .. code-block:: console
@@ -14,36 +14,36 @@ Tape Backup
 Proxmox tape backup provides an easy way to store datastore content
 onto magnetic tapes. This increases data safety because you get:
 
-- an additional copy of the data
-- to a different media type (tape)
+- an additional copy of the data,
+- on a different media type (tape),
 - to an additional location (you can move tapes off-site)
 
 In most restore jobs, only data from the last backup job is restored.
-Restore requests further decline the older the data
+Restore requests further decline, the older the data
 gets. Considering this, tape backup may also help to reduce disk
-usage, because you can safely remove data from disk once archived on
-tape. This is especially true if you need to keep data for several
+usage, because you can safely remove data from disk, once it's archived on
+tape. This is especially true if you need to retain data for several
 years.
 
 Tape backups do not provide random access to the stored data. Instead,
-you need to restore the data to disk before you can access it
+you need to restore the data to disk, before you can access it
 again. Also, if you store your tapes off-site (using some kind of tape
-vaulting service), you need to bring them on-site before you can do any
-restore. So please consider that restores from tapes can take much
-longer than restores from disk.
+vaulting service), you need to bring them back on-site, before you can do any
+restores. So please consider that restoring from tape can take much
+longer than restoring from disk.
 
 
 Tape Technology Primer
 ----------------------
 
-.. _Linear Tape Open: https://en.wikipedia.org/wiki/Linear_Tape-Open
+.. _Linear Tape-Open: https://en.wikipedia.org/wiki/Linear_Tape-Open
 
-As of 2021, the only broadly available tape technology standard is
-`Linear Tape Open`_, and different vendors offers LTO Ultrium tape
-drives, auto-loaders and LTO tape cartridges.
+As of 2021, the only widely available tape technology standard is
+`Linear Tape-Open`_ (LTO). Different vendors offer LTO Ultrium tape
+drives, auto-loaders, and LTO tape cartridges.
 
-There are a few vendors offering proprietary drives with
-slight advantages in performance and capacity, but they have
+There are a few vendors that offer proprietary drives with
+slight advantages in performance and capacity. Nevertheless, they have
 significant disadvantages:
 
 - proprietary (single vendor)
@@ -53,13 +53,13 @@ So we currently do not test such drives.
 
 In general, LTO tapes offer the following advantages:
 
-- Durable (30 years)
+- Durability (30 year lifespan)
 - High Capacity (12 TB)
 - Relatively low cost per TB
 - Cold Media
 - Movable (storable inside vault)
 - Multiple vendors (for both media and drives)
-- Build in AES-CGM Encryption engine
+- Build in AES-GCM Encryption engine
 
 Note that `Proxmox Backup Server` already stores compressed data, so using the
 tape compression feature has no advantage.
@@ -68,41 +68,40 @@ tape compression feature has no advantage.
 Supported Hardware
 ------------------
 
-Proxmox Backup Server supports `Linear Tape Open`_ generation 4 (LTO4)
-or later. In general, all SCSI2 tape drives supported by the Linux
-kernel should work, but feature like hardware encryptions needs LTO4
+Proxmox Backup Server supports `Linear Tape-Open`_ generation 4 (LTO-4)
+or later. In general, all SCSI-2 tape drives supported by the Linux
+kernel should work, but features like hardware encryption need LTO-4
 or later.
 
-Tape changer support is done using the Linux 'mtx' command line
-tool. So any changer device supported by that tool should work.
+Tape changing is carried out using the Linux 'mtx' command line
+tool, so any changer device supported by this tool should work.
 
 
 Drive Performance
 ~~~~~~~~~~~~~~~~~
 
-Current LTO-8 tapes provide read/write speeds up to 360 MB/s. This means,
+Current LTO-8 tapes provide read/write speeds of up to 360 MB/s. This means,
 that it still takes a minimum of 9 hours to completely write or
 read a single tape (even at maximum speed).
 
 The only way to speed up that data rate is to use more than one
-drive. That way you can run several backup jobs in parallel, or run
+drive. That way, you can run several backup jobs in parallel, or run
 restore jobs while the other dives are used for backups.
 
-Also consider that you need to read data first from your datastore
-(disk). But a single spinning disk is unable to deliver data at this
+Also consider that you first need to read data from your datastore
+(disk). However, a single spinning disk is unable to deliver data at this
 rate. We measured a maximum rate of about 60MB/s to 100MB/s in practice,
-so it takes 33 hours to read 12TB to fill up an LTO-8 tape. If you want
-to run your tape at full speed, please make sure that the source
+so it takes 33 hours to read the 12TB needed to fill up an LTO-8 tape. If you want
+to write to your tape at full speed, please make sure that the source
 datastore is able to deliver that performance (e.g, by using SSDs).
 
 
 Terminology
 -----------
 
-:Tape Labels: are used to uniquely identify a tape. You normally use
-   some sticky paper labels and apply them on the front of the
-   cartridge. We additionally store the label text magnetically on the
-   tape (first file on tape).
+:Tape Labels: are used to uniquely identify a tape. You would normally apply a
+   sticky paper label to the front of the cartridge. We additionally store the
+   label text magnetically on the tape (first file on tape).
 
 .. _Code 39: https://en.wikipedia.org/wiki/Code_39
 
@@ -116,10 +115,10 @@ Terminology
    Specification`_.
 
    You can either buy such barcode labels from your cartridge vendor,
-   or print them yourself. You can use our `LTO Barcode Generator`_ App
-   for that.
+   or print them yourself. You can use our `LTO Barcode Generator`_
+   app, if you would like to print them yourself.
 
-.. Note:: Physical labels and the associated adhesive shall have an
+.. Note:: Physical labels and the associated adhesive should have an
    environmental performance to match or exceed the environmental
    specifications of the cartridge to which it is applied.
 
@@ -133,7 +132,7 @@ Terminology
    media pool).
 
 :Tape drive: The device used to read and write data to the tape. There
-   are standalone drives, but drives often ship within tape libraries.
+   are standalone drives, but drives are usually shipped within tape libraries.
 
 :Tape changer: A device which can change the tapes inside a tape drive
    (tape robot). They are usually part of a tape library.
@@ -142,10 +141,10 @@ Terminology
 
 :`Tape library`_: A storage device that contains one or more tape drives,
    a number of slots to hold tape cartridges, a barcode reader to
-   identify tape cartridges and an automated method for loading tapes
+   identify tape cartridges, and an automated method for loading tapes
    (a robot).
 
-   This is also commonly known as 'autoloader', 'tape robot' or 'tape jukebox'.
+   This is also commonly known as an 'autoloader', 'tape robot' or 'tape jukebox'.
 
 :Inventory: The inventory stores the list of known tapes (with
    additional status information).
@@ -153,14 +152,14 @@ Terminology
 :Catalog: A media catalog stores information about the media content.
 
 
-Tape Quickstart
+Tape Quick Start
 ---------------
 
 1. Configure your tape hardware (drives and changers)
 
 2. Configure one or more media pools
 
-3. Label your tape cartridges.
+3. Label your tape cartridges
 
 4. Start your first tape backup job ...
 
@@ -169,7 +168,7 @@ Configuration
 -------------
 
 Please note that you can configure anything using the graphical user
-interface or the command line interface. Both methods results in the
+interface or the command line interface. Both methods result in the
 same configuration.
 
 .. _tape_changer_config:
@@ -180,7 +179,7 @@ Tape changers
 Tape changers (robots) are part of a `Tape Library`_. You can skip
 this step if you are using a standalone drive.
 
-Linux is able to auto detect those devices, and you can get a list
+Linux is able to auto detect these devices, and you can get a list
 of available devices using:
 
 .. code-block:: console
@@ -192,7 +191,7 @@ of available devices using:
  │ /dev/tape/by-id/scsi-CC2C52 │ Quantum │ Superloader3 │ CC2C52 │
  └─────────────────────────────┴─────────┴──────────────┴────────┘
 
-In order to use that device with Proxmox, you need to create a
+In order to use a device with Proxmox Backup Server, you need to create a
 configuration entry:
 
 .. code-block:: console
@@ -201,11 +200,11 @@ configuration entry:
 
 Where ``sl3`` is an arbitrary name you can choose.
 
-.. Note:: Please use stable device path names from inside
+.. Note:: Please use the persistent device path names from inside
    ``/dev/tape/by-id/``. Names like ``/dev/sg0`` may point to a
    different device after reboot, and that is not what you want.
 
-You can show the final configuration with:
+You can display the final configuration with:
 
 .. code-block:: console
 
@@ -255,12 +254,12 @@ Tape libraries usually provide some special import/export slots (also
 called "mail slots"). Tapes inside those slots are accessible from
 outside, making it easy to add/remove tapes to/from the library. Those
 tapes are considered to be "offline", so backup jobs will not use
-them. Those special slots are auto-detected and marked as
+them. Those special slots are auto-detected and marked as an
 ``import-export`` slot in the status command.
 
 It's worth noting that some of the smaller tape libraries don't have
-such slots. While they have something called "Mail Slot", that slot
-is just a way to grab the tape from the gripper. But they are unable
+such slots. While they have something called a "Mail Slot", that slot
+is just a way to grab the tape from the gripper. They are unable
 to hold media while the robot does other things. They also do not
 expose that "Mail Slot" over the SCSI interface, so you wont see them in
 the status output.
@@ -322,7 +321,7 @@ configuration entry:
 
  # proxmox-tape drive create mydrive --path  /dev/tape/by-id/scsi-12345-nst
 
-.. Note:: Please use stable device path names from inside
+.. Note:: Please use the persistent device path names from inside
    ``/dev/tape/by-id/``. Names like ``/dev/nst0`` may point to a
    different device after reboot, and that is not what you want.
 
@@ -334,10 +333,10 @@ changer device:
  # proxmox-tape drive update mydrive --changer sl3  --changer-drivenum 0
 
 The ``--changer-drivenum`` is only necessary if the tape library
-includes more than one drive (The changer status command lists all
+includes more than one drive (the changer status command lists all
 drive numbers).
 
-You can show the final configuration with:
+You can display the final configuration with:
 
 .. code-block:: console
 
@@ -353,7 +352,7 @@ You can show the final configuration with:
  └─────────┴────────────────────────────────┘
 
 .. NOTE:: The ``changer-drivenum`` value 0 is not stored in the
-   configuration, because that is the default.
+   configuration, because it is the default.
 
 To list all configured drives use:
 
@@ -383,7 +382,7 @@ For testing, you can simply query the drive status with:
  └───────────┴────────────────────────┘
 
 .. NOTE:: Blocksize should always be 0 (variable block size
-   mode). This is the default anyways.
+   mode). This is the default anyway.
 
 
 .. _tape_media_pool_config:
@@ -399,11 +398,11 @@ one media pool, so a job only uses tapes from that pool.
    A media set is a group of continuously written tapes, used to split
    the larger pool into smaller, restorable units. One or more backup
    jobs write to a media set, producing an ordered group of
-   tapes. Media sets are identified by an unique ID. That ID and the
-   sequence number is stored on each tape of that set (tape label).
+   tapes. Media sets are identified by a unique ID. That ID and the
+   sequence number are stored on each tape of that set (tape label).
 
-   Media sets are the basic unit for restore tasks, i.e. you need all
-   tapes in the set to restore the media set content. Data is fully
+   Media sets are the basic unit for restore tasks. This means that you need
+   every tape in the set to restore the media set contents. Data is fully
    deduplicated inside a media set.
 
 
@@ -414,20 +413,20 @@ one media pool, so a job only uses tapes from that pool.
 
    - Try to use the current media set.
 
-     This setting produce one large media set. While this is very
+     This setting produces one large media set. While this is very
      space efficient (deduplication, no unused space), it can lead to
-     long restore times, because restore jobs needs to read all tapes in the
+     long restore times, because restore jobs need to read all tapes in the
      set.
 
-     .. NOTE:: Data is fully deduplicated inside a media set. That
+     .. NOTE:: Data is fully deduplicated inside a media set. This
         also means that data is randomly distributed over the tapes in
-        the set. So even if you restore a single VM, this may have to
-        read data from all tapes inside the media set.
+        the set. Thus, even if you restore a single VM, data may have to be
+        read from all tapes inside the media set.
 
-     Larger media sets are also more error prone, because a single
-     damaged media makes the restore fail.
+     Larger media sets are also more error-prone, because a single
+     damaged tape makes the restore fail.
 
-     Usage scenario: Mostly used with tape libraries, and you manually
+     Usage scenario: Mostly used with tape libraries. You manually
      trigger new set creation by running a backup job with the
      ``--export`` option.
 
@@ -436,13 +435,13 @@ one media pool, so a job only uses tapes from that pool.
 
    - Always create a new media set.
 
-     With this setting each backup job creates a new media set. This
-     is less space efficient, because the last media from the last set
+     With this setting, each backup job creates a new media set. This
+     is less space efficient, because the media from the last set
      may not be fully written, leaving the remaining space unused.
 
      The advantage is that this procudes media sets of minimal
-     size. Small set are easier to handle, you can move sets to an
-     off-site vault, and restore is much faster.
+     size. Small sets are easier to handle, can be moved more conveniently
+     to an off-site vault, and can be restored much faster.
 
      .. NOTE:: Retention period starts with the creation time of the
         media set.
@@ -468,11 +467,11 @@ one media pool, so a job only uses tapes from that pool.
 
    - Current set contains damaged or retired tapes.
 
-   - Media pool encryption changed
+   - Media pool encryption has changed
 
-   - Database consistency errors, e.g. if the inventory does not
-     contain required media info, or contain conflicting infos
-     (outdated data).
+   - Database consistency errors, for example, if the inventory does not
+     contain the required media information, or it contains conflicting
+     information (outdated data).
 
 .. topic:: Retention Policy
 
@@ -489,26 +488,27 @@ one media pool, so a job only uses tapes from that pool.
 
 .. topic:: Hardware Encryption
 
-   LTO4 (or later) tape drives support hardware encryption. If you
+   LTO-4 (or later) tape drives support hardware encryption. If you
    configure the media pool to use encryption, all data written to the
    tapes is encrypted using the configured key.
 
-   That way, unauthorized users cannot read data from the media,
-   e.g. if you loose a media while shipping to an offsite location.
+   This way, unauthorized users cannot read data from the media,
+   for example, if you loose a tape while shipping to an offsite location.
 
-   .. Note:: If the backup client also encrypts data, data on tape
+   .. Note:: If the backup client also encrypts data, data on the tape
       will be double encrypted.
 
-   The password protected key is stored on each media, so it is
-   possbible to `restore the key <tape_restore_encryption_key_>`_ using the password. Please make sure
-   you remember the password in case you need to restore the key.
+   The password protected key is stored on each medium, so that it is
+   possbible to `restore the key <tape_restore_encryption_key_>`_ using 
+   the password. Please make sure to remember the password, in case
+   you need to restore the key.
 
 
-.. NOTE:: We use global content namespace, i.e. we do not store the
-   source datastore, so it is impossible to distinguish store1:/vm/100
-   from store2:/vm/100. Please use different media pools if the
-   sources are from different name spaces with conflicting names
-   (E.g. if the sources are from different Proxmox VE clusters).
+.. NOTE:: We use global content namespace, meaning we do not store the
+   source datastore name. Because of this, it is impossible to distinguish
+   store1:/vm/100 from store2:/vm/100. Please use different media pools
+   if the sources are from different namespaces with conflicting names
+   (for example, if the sources are from different Proxmox VE clusters).
 
 
 The following command creates a new media pool:
@@ -520,7 +520,7 @@ The following command creates a new media pool:
  # proxmox-tape pool create daily --drive mydrive
 
 
-Additional option can be set later using the update command:
+Additional option can be set later, using the update command:
 
 .. code-block:: console
 
@@ -544,8 +544,8 @@ Tape Backup Jobs
 ~~~~~~~~~~~~~~~~
 
 To automate tape backup, you can configure tape backup jobs which
-store datastore content to a media pool at a specific time
-schedule. Required settings are:
+write datastore content to a media pool, based on a specific time schedule.
+The required settings are:
 
 - ``store``: The datastore you want to backup
 
@@ -564,14 +564,14 @@ use:
  # proxmox-tape backup-job create job2 --store vmstore1 \
    --pool yourpool --drive yourdrive --schedule daily
 
-Backup includes all snapshot from a backup group by default. You can
+The backup includes all snapshots from a backup group by default. You can
 set the ``latest-only`` flag to include only the latest snapshots:
 
 .. code-block:: console
 
  # proxmox-tape backup-job update job2 --latest-only
 
-Backup jobs can use email to send tape requests notifications or
+Backup jobs can use email to send tape request notifications or
 report errors. You can set the notification user with:
 
 .. code-block:: console
@@ -581,7 +581,7 @@ report errors. You can set the notification user with:
 .. Note:: The email address is a property of the user (see :ref:`user_mgmt`).
 
 It is sometimes useful to eject the tape from the drive after a
-backup. For a standalone drive, the ``eject-media`` option eject the
+backup. For a standalone drive, the ``eject-media`` option ejects the
 tape, making sure that the following backup cannot use the tape
 (unless someone manually loads the tape again). For tape libraries,
 this option unloads the tape to a free slot, which provides better
@@ -591,11 +591,11 @@ dust protection than inside a drive:
 
  # proxmox-tape backup-job update job2 --eject-media
 
-.. Note:: For failed jobs, the tape remain in the drive.
+.. Note:: For failed jobs, the tape remains in the drive.
 
-For tape libraries, the ``export-media`` options moves all tapes from
+For tape libraries, the ``export-media`` option moves all tapes from
 the media set to an export slot, making sure that the following backup
-cannot use the tapes. An operator can pickup those tapes and move them
+cannot use the tapes. An operator can pick up those tapes and move them
 to a vault.
 
 .. code-block:: console
@@ -622,9 +622,9 @@ To remove a job, please use:
 Administration
 --------------
 
-Many sub-command of the ``proxmox-tape`` command line tools take a
+Many sub-commands of the ``proxmox-tape`` command line tools take a
 parameter called ``--drive``, which specifies the tape drive you want
-to work on. For convenience, you can set that in an environment
+to work on. For convenience, you can set this in an environment
 variable:
 
 .. code-block:: console
@@ -639,27 +639,27 @@ parameter from commands that needs a changer device, for example:
 
  # proxmox-tape changer status
 
-Should displays the changer status of the changer device associated with
+should display the changer status of the changer device associated with
 drive ``mydrive``.
 
 
 Label Tapes
 ~~~~~~~~~~~
 
-By default, tape cartidges all looks the same, so you need to put a
-label on them for unique identification. So first, put a sticky paper
+By default, tape cartridges all look the same, so you need to put a
+label on them for unique identification. First, put a sticky paper
 label with some human readable text on the cartridge.
 
 If you use a `Tape Library`_, you should use an 8 character string
-encoded as `Code 39`_, as definded in the `LTO Ultrium Cartridge Label
-Specification`_. You can either bye such barcode labels from your
-cartidge vendor, or print them yourself. You can use our `LTO Barcode
-Generator`_ App for that.
+encoded as `Code 39`_, as defined in the `LTO Ultrium Cartridge Label
+Specification`_. You can either buy such barcode labels from your
+cartridge vendor, or print them yourself. You can use our `LTO Barcode
+Generator`_ app to print them.
 
 Next, you need to write that same label text to the tape, so that the
 software can uniquely identify the tape too.
 
-For a standalone drive, manually insert the new tape cartidge into the
+For a standalone drive, manually insert the new tape cartridge into the
 drive and run:
 
 .. code-block:: console
@@ -668,7 +668,7 @@ drive and run:
 
 You may omit the ``--pool`` argument to allow the tape to be used by any pool.
 
-.. Note:: For safety reasons, this command fails if the tape contain
+.. Note:: For safety reasons, this command fails if the tape contains
    any data. If you want to overwrite it anyway, erase the tape first.
 
 You can verify success by reading back the label:
@@ -718,7 +718,7 @@ The following options are available:
 --eject-media  Eject media upon job completion.
 
   It is normally good practice to eject the tape after use. This unmounts the
-  tape from the drive and prevents the tape from getting dirty with dust.
+  tape from the drive and prevents the tape from getting dusty.
 
 --export-media-set  Export media set upon job completion.
 
@@ -737,7 +737,7 @@ catalogs, you need to restore them first. Please note that you need
 the catalog to find your data, but restoring a complete media-set does
 not need media catalogs.
 
-The following command shows the media content (from catalog):
+The following command lists the media content (from catalog):
 
 .. code-block:: console
 
@@ -841,7 +841,7 @@ database. Further restore jobs automatically use any available key.
 Tape Cleaning
 ~~~~~~~~~~~~~
 
-LTO tape drives requires regular cleaning. This is done by loading a
+LTO tape drives require regular cleaning. This is done by loading a
 cleaning cartridge into the drive, which is a manual task for
 standalone drives.
 
@@ -876,7 +876,7 @@ This command does the following:
 
 - find the cleaning tape (in slot 3)
 
-- unload the current media from the drive (back to slot1)
+- unload the current media from the drive (back to slot 1)
 
 - load the cleaning tape into the drive
 
-- 
2.20.1

[pbs-devel] applied: [PATCH proxmox-backup] tape: documentation language fixup

[Dietmar Maurer]

applied, thanks!