[pbs-devel] [PATCH proxmox-backup] docs: language fixup: faq and appendix

[pbs-devel] [PATCH proxmox-backup] docs: language fixup: faq and appendix

[Dylan Whyte]

minor formatting and language fixes to the faq section and the appendix

Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
---
 docs/backup-protocol.rst            | 71 +++++++++++++++--------------
 docs/calendarevents.rst             | 12 ++---
 docs/command-syntax.rst             |  2 +-
 docs/config/acl/format.rst          |  6 +--
 docs/config/datastore/format.rst    |  6 +--
 docs/config/media-pool/format.rst   |  4 +-
 docs/config/remote/format.rst       |  4 +-
 docs/config/sync/format.rst         |  4 +-
 docs/config/tape-job/format.rst     |  2 +-
 docs/config/tape/format.rst         |  6 +--
 docs/config/user/format.rst         |  4 +-
 docs/config/verification/format.rst |  2 +-
 docs/configuration-files.rst        |  2 +-
 docs/faq.rst                        |  6 +--
 docs/file-formats.rst               | 30 ++++++------
 docs/glossary.rst                   | 12 ++---
 docs/output-format.rst              |  4 +-
 17 files changed, 90 insertions(+), 87 deletions(-)

diff --git a/docs/backup-protocol.rst b/docs/backup-protocol.rst
index 41a2e9f2..47f6a6bc 100644
--- a/docs/backup-protocol.rst
+++ b/docs/backup-protocol.rst
@@ -1,10 +1,10 @@
 Backup Protocol
 ===============
 
-Proxmox Backup Server uses a REST based API. While the management
-interface use normal HTTP, the actual backup and restore interface use
+Proxmox Backup Server uses a REST-based API. While the management
+interface uses normal HTTP, the actual backup and restore interface uses
 HTTP/2 for improved performance. Both HTTP and HTTP/2 are well known
-standards, so the following section assumes that you are familiar on
+standards, so the following section assumes that you are familiar with
 how to use them.
 
 
@@ -13,35 +13,35 @@ Backup Protocol API
 
 To start a new backup, the API call ``GET /api2/json/backup`` needs to
 be upgraded to a HTTP/2 connection using
-``proxmox-backup-protocol-v1`` as protocol name::
+``proxmox-backup-protocol-v1`` as the protocol name::
 
   GET /api2/json/backup HTTP/1.1
   UPGRADE: proxmox-backup-protocol-v1
 
-The server replies with HTTP 101 Switching Protocol status code,
-and you can then issue REST commands on that updated HTTP/2 connection.
+The server replies with the ``HTTP 101 Switching Protocol`` status code,
+and you can then issue REST commands on the updated HTTP/2 connection.
 
 The backup protocol allows you to upload three different kind of files:
 
 - Chunks and blobs (binary data)
 
-- Fixed Indexes (List of chunks with fixed size)
+- Fixed indexes (List of chunks with fixed size)
 
-- Dynamic Indexes (List of chunk with variable size)
+- Dynamic indexes (List of chunks with variable size)
 
-The following section gives a short introduction how to upload such
+The following section provides a short introduction on how to upload such
 files. Please use the `API Viewer <api-viewer/index.html>`_ for
-details about available REST commands.
+details about the available REST commands.
 
 
 Upload Blobs
 ~~~~~~~~~~~~
 
-Uploading blobs is done using ``POST /blob``. The HTTP body contains the
-data encoded as :ref:`Data Blob <data-blob-format>`).
+Blobs are uploaded using ``POST /blob``. The HTTP body contains the
+data encoded as :ref:`Data Blob <data-blob-format>`.
 
-The file name needs to end with ``.blob``, and is automatically added
-to the backup manifest.
+The file name must end with ``.blob``, and is automatically added
+to the backup manifest, following the call to ``POST /finish``.
 
 
 Upload Chunks
@@ -56,40 +56,41 @@ encoded as :ref:`Data Blob <data-blob-format>`).
 Upload Fixed Indexes
 ~~~~~~~~~~~~~~~~~~~~
 
-Fixed indexes are use to store VM image data. The VM image is split
+Fixed indexes are used to store VM image data. The VM image is split
 into equally sized chunks, which are uploaded individually. The index
-file simply contains a list to chunk digests.
+file simply contains a list of chunk digests.
 
-You create a fixed index with ``POST /fixed_index``. Then upload
+You create a fixed index with ``POST /fixed_index``. Then, upload
 chunks with ``POST /fixed_chunk``, and append them to the index with
 ``PUT /fixed_index``. When finished, you need to close the index using
 ``POST /fixed_close``.
 
 The file name needs to end with ``.fidx``, and is automatically added
-to the backup manifest.
+to the backup manifest, following the call to ``POST /finish``.
 
 
 Upload Dynamic Indexes
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Dynamic indexes are use to store file archive data. The archive data
+Dynamic indexes are used to store file archive data. The archive data
 is split into dynamically sized chunks, which are uploaded
-individually. The index file simply contains a list to chunk digests
+individually. The index file simply contains a list of chunk digests
 and offsets.
 
-You create a dynamic sized index with ``POST /dynamic_index``. Then
+You can create a dynamically sized index with ``POST /dynamic_index``. Then,
 upload chunks with ``POST /dynamic_chunk``, and append them to the index with
 ``PUT /dynamic_index``. When finished, you need to close the index using
 ``POST /dynamic_close``.
 
-The file name needs to end with ``.didx``, and is automatically added
-to the backup manifest.
+The filename needs to end with ``.didx``, and is automatically added
+to the backup manifest, following the call to ``POST /finish``.
+
 
 Finish Backup
 ~~~~~~~~~~~~~
 
-Once you have uploaded all data, you need to call ``POST
-/finish``. This commits all data and ends the backup protocol.
+Once you have uploaded all data, you need to call ``POST /finish``. This
+commits all data and ends the backup protocol.
 
 
 Restore/Reader Protocol API
@@ -102,39 +103,39 @@ be upgraded to a HTTP/2 connection using
   GET /api2/json/reader HTTP/1.1
   UPGRADE: proxmox-backup-reader-protocol-v1
 
-The server replies with HTTP 101 Switching Protocol status code,
+The server replies with the ``HTTP 101 Switching Protocol`` status code,
 and you can then issue REST commands on that updated HTTP/2 connection.
 
-The reader protocol allows you to download three different kind of files:
+The reader protocol allows you to download three different kinds of files:
 
 - Chunks and blobs (binary data)
 
-- Fixed Indexes (List of chunks with fixed size)
+- Fixed indexes (list of chunks with fixed size)
 
-- Dynamic Indexes (List of chunk with variable size)
+- Dynamic indexes (list of chunks with variable size)
 
-The following section gives a short introduction how to download such
+The following section provides a short introduction on how to download such
 files. Please use the `API Viewer <api-viewer/index.html>`_ for details about
-available REST commands.
+the available REST commands.
 
 
 Download Blobs
 ~~~~~~~~~~~~~~
 
-Downloading blobs is done using ``GET /download``. The HTTP body contains the
+Blobs are downloaded using ``GET /download``. The HTTP body contains the
 data encoded as :ref:`Data Blob <data-blob-format>`.
 
 
 Download Chunks
 ~~~~~~~~~~~~~~~
 
-Downloading chunks is done using ``GET /chunk``. The HTTP body contains the
-data encoded as :ref:`Data Blob <data-blob-format>`).
+Chunks are downloaded using ``GET /chunk``. The HTTP body contains the
+data encoded as :ref:`Data Blob <data-blob-format>`.
 
 
 Download Index Files
 ~~~~~~~~~~~~~~~~~~~~
 
-Downloading index files is done using ``GET /download``. The HTTP body
+Index files are downloaded using ``GET /download``. The HTTP body
 contains the data encoded as :ref:`Fixed Index <fixed-index-format>`
 or :ref:`Dynamic Index <dynamic-index-format>`.
diff --git a/docs/calendarevents.rst b/docs/calendarevents.rst
index cffd124f..82e252fc 100644
--- a/docs/calendarevents.rst
+++ b/docs/calendarevents.rst
@@ -37,7 +37,7 @@ Each field can contain multiple values in the following formats:
 * and a combination of the above: e.g., 01,05..10,12/02
 * or a `*` for every possible value: e.g., \*:00
 
-There are some special values that have specific meaning:
+There are some special values that have a specific meaning:
 
 =================================  ==============================
 Value                              Syntax
@@ -81,19 +81,19 @@ Not all features of systemd calendar events are implemented:
 
 * no Unix timestamps (e.g. `@12345`): instead use date and time to specify
   a specific point in time
-* no timezone: all schedules use the set timezone on the server
+* no timezone: all schedules use the timezone of the server
 * no sub-second resolution
 * no reverse day syntax (e.g. 2020-03~01)
 * no repetition of ranges (e.g. 1..10/2)
 
-Notes on scheduling
+Notes on Scheduling
 -------------------
 
-In `Proxmox Backup`_ scheduling for most tasks is done in the
+In `Proxmox Backup`_, scheduling for most tasks is done in the
 `proxmox-backup-proxy`. This daemon checks all job schedules
-if they are due every minute. This means that even if
+every minute, to see if any are due. This means that even though
 `calendar events` can contain seconds, it will only be checked
-once a minute.
+once per minute.
 
 Also, all schedules will be checked against the timezone set
 in the `Proxmox Backup`_ server.
diff --git a/docs/command-syntax.rst b/docs/command-syntax.rst
index 3e3c8176..86dbd4a9 100644
--- a/docs/command-syntax.rst
+++ b/docs/command-syntax.rst
@@ -10,7 +10,7 @@ Command Syntax
 Catalog Shell Commands
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Those command are available when you start an interactive restore shell:
+The following commands are available in an interactive restore shell:
 
 .. code-block:: console
 
diff --git a/docs/config/acl/format.rst b/docs/config/acl/format.rst
index 82c61e44..a6f71500 100644
--- a/docs/config/acl/format.rst
+++ b/docs/config/acl/format.rst
@@ -2,13 +2,13 @@ This file contains the access control list for the Proxmox Backup
 Server API.
 
 Each line starts with ``acl:``, followed by 4 additional values
-separated by collon.
+separated by colon.
 
-:propagate: Propagate permissions down the hierachrchy
+:propagate: Propagate permissions down the hierarchy
 
 :path: The object path
 
-:User/Token: List of users and token
+:User/Token: List of users and tokens
 
 :Role: List of assigned roles
 
diff --git a/docs/config/datastore/format.rst b/docs/config/datastore/format.rst
index e93c86f2..858d7708 100644
--- a/docs/config/datastore/format.rst
+++ b/docs/config/datastore/format.rst
@@ -1,9 +1,9 @@
-The file contains a list of datastore configuration sections. Each
-section starts with a header ``datastore: <name>``, followed by the
+This file contains a list of datastore configuration sections. Each
+section starts with the header ``datastore: <name>``, followed by the
 datastore configuration options.
 
 ::
-  
+
   datastore: <name1>
      path <path1>
      <option1> <value1>
diff --git a/docs/config/media-pool/format.rst b/docs/config/media-pool/format.rst
index 5c7a08d9..21993c58 100644
--- a/docs/config/media-pool/format.rst
+++ b/docs/config/media-pool/format.rst
@@ -1,4 +1,4 @@
-Each entry starts with a header ``pool: <name>``, followed by the
+Each entry starts with the header ``pool: <name>``, followed by the
 media pool configuration options.
 
 ::
@@ -8,6 +8,6 @@ media pool configuration options.
 	retention overwrite
 
   pool: ...
-	
+
 
 You can use the ``proxmox-tape pool`` command to manipulate this file.
diff --git a/docs/config/remote/format.rst b/docs/config/remote/format.rst
index 1881e7d5..bfe34ac4 100644
--- a/docs/config/remote/format.rst
+++ b/docs/config/remote/format.rst
@@ -1,6 +1,6 @@
 This file contains information used to access remote servers.
 
-Each entry starts with a header ``remote: <name>``, followed by the
+Each entry starts with the header ``remote: <name>``, followed by the
 remote configuration options.
 
 ::
@@ -11,7 +11,7 @@ remote configuration options.
 	...
 
   remote: ...
-	
+
 
 You can use the ``proxmox-backup-manager remote`` command to manipulate
 this file.
diff --git a/docs/config/sync/format.rst b/docs/config/sync/format.rst
index f6a01363..66b0caf5 100644
--- a/docs/config/sync/format.rst
+++ b/docs/config/sync/format.rst
@@ -1,4 +1,4 @@
-Each entry starts with a header ``sync: <name>``, followed by the
+Each entry starts with the header ``sync: <name>``, followed by the
 job configuration options.
 
 ::
@@ -9,7 +9,7 @@ job configuration options.
 	remote lina
 
   sync: ...
-	
+
 
 You can use the ``proxmox-backup-manager sync-job`` command to manipulate
 this file.
diff --git a/docs/config/tape-job/format.rst b/docs/config/tape-job/format.rst
index 6eaf60ad..aa773c7c 100644
--- a/docs/config/tape-job/format.rst
+++ b/docs/config/tape-job/format.rst
@@ -1,4 +1,4 @@
-Each entry starts with a header ``backup: <name>``, followed by the
+Each entry starts with the header ``backup: <name>``, followed by the
 job configuration options.
 
 ::
diff --git a/docs/config/tape/format.rst b/docs/config/tape/format.rst
index 51687471..45d80f35 100644
--- a/docs/config/tape/format.rst
+++ b/docs/config/tape/format.rst
@@ -1,7 +1,7 @@
-Each LTO drive configuration section starts with a header ``lto: <name>``,
+Each LTO drive configuration section starts with the header ``lto: <name>``,
 followed by the drive configuration options.
 
-Tape changer configurations starts with  ``changer: <name>``,
+Tape changer configurations start with the header ``changer: <name>``,
 followed by the changer configuration options.
 
 ::
@@ -18,5 +18,5 @@ followed by the changer configuration options.
 You can use the ``proxmox-tape drive`` and ``proxmox-tape changer``
 commands to manipulate this file.
 
-.. NOTE:: The ``virtual:`` drive type is experimental and onyl used
+.. NOTE:: The ``virtual:`` drive type is experimental and should only be used
    for debugging.
diff --git a/docs/config/user/format.rst b/docs/config/user/format.rst
index e7da6dd3..eac654eb 100644
--- a/docs/config/user/format.rst
+++ b/docs/config/user/format.rst
@@ -1,9 +1,9 @@
 This file contains the list of API users and API tokens.
 
-Each user configuration section starts with a header ``user: <name>``,
+Each user configuration section starts with the header ``user: <name>``,
 followed by the user configuration options.
 
-API token configuration starts with a header ``token:
+API token configuration starts with the header ``token:
 <userid!token_name>``, followed by the token configuration. The data
 used to authenticate tokens is stored in a separate file
 (``token.shadow``).
diff --git a/docs/config/verification/format.rst b/docs/config/verification/format.rst
index dbe8bf84..859fb13a 100644
--- a/docs/config/verification/format.rst
+++ b/docs/config/verification/format.rst
@@ -1,4 +1,4 @@
-Each entry starts with a header ``verification: <name>``, followed by the
+Each entry starts with the header ``verification: <name>``, followed by the
 job configuration options.
 
 ::
diff --git a/docs/configuration-files.rst b/docs/configuration-files.rst
index 6b21a111..047636a2 100644
--- a/docs/configuration-files.rst
+++ b/docs/configuration-files.rst
@@ -1,7 +1,7 @@
 Configuration Files
 ===================
 
-All Proxmox Backup Server configuration files resides inside directory
+All Proxmox Backup Server configuration files reside in the directory
 ``/etc/proxmox-backup/``.
 
 
diff --git a/docs/faq.rst b/docs/faq.rst
index 94d48ab4..a4bd517a 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -69,6 +69,6 @@ be able to read the data.
 Is the backup incremental/deduplicated?
 ---------------------------------------
 
-With Proxmox Backup Server, backups are sent incremental and data is
-deduplicated on the server.
-This minimizes both the storage consumed and the network impact.
+With Proxmox Backup Server, backups are sent incrementally to the server, and
+data is then deduplicated on the server. This minimizes both the storage
+consumed and the impact on the network.
diff --git a/docs/file-formats.rst b/docs/file-formats.rst
index c1b2c79a..43ecfefc 100644
--- a/docs/file-formats.rst
+++ b/docs/file-formats.rst
@@ -14,7 +14,8 @@ Proxmox File Archive Format (``.pxar``)
 Data Blob Format (``.blob``)
 ----------------------------
 
-The data blob format is used to store small binary data. The magic number decides the exact format:
+The data blob format is used to store small binary data. The magic number
+decides the exact format:
 
 .. list-table::
    :widths: auto
@@ -32,7 +33,8 @@ The data blob format is used to store small binary data. The magic number decide
      - encrypted
      - compressed
 
-Compression algorithm is ``zstd``. Encryption cipher is ``AES_256_GCM``.
+The compression algorithm used is ``zstd``. The encryption cipher is
+``AES_256_GCM``.
 
 Unencrypted blobs use the following format:
 
@@ -43,9 +45,9 @@ Unencrypted blobs use the following format:
    * - ``CRC32: [u8; 4]``
    * - ``Data: (max 16MiB)``
 
-Encrypted blobs additionally contains a 16 byte IV, followed by a 16
-byte Authenticated Encyryption (AE) tag, followed by the encrypted
-data:
+Encrypted blobs additionally contain a 16 byte initialization vector (IV),
+followed by a 16 byte authenticated encryption (AE) tag, followed by the
+encrypted data:
 
 .. list-table::
 
@@ -72,19 +74,19 @@ All numbers are stored as little-endian.
    * - ``ctime: i64``,
      - Creation Time (epoch)
    * - ``index_csum: [u8; 32]``,
-     - Sha256 over the index (without header) ``SHA256(digest1||digest2||...)``
+     - SHA-256 over the index (without header) ``SHA256(digest1||digest2||...)``
    * - ``size: u64``,
      - Image size
    * - ``chunk_size: u64``,
      - Chunk size
    * - ``reserved: [u8; 4016]``,
-     - overall header size is one page (4096 bytes)
+     - Overall header size is one page (4096 bytes)
    * - ``digest1: [u8; 32]``
-     - first chunk digest
+     - First chunk digest
    * - ``digest2: [u8; 32]``
-     - next chunk
+     - Second chunk digest
    * - ...
-     - next chunk ...
+     - Next chunk digest ...
 
 
 .. _dynamic-index-format:
@@ -103,16 +105,16 @@ All numbers are stored as little-endian.
    * - ``ctime: i64``,
      - Creation Time (epoch)
    * - ``index_csum: [u8; 32]``,
-     - Sha256 over the index (without header) ``SHA256(offset1||digest1||offset2||digest2||...)``
+     - SHA-256 over the index (without header) ``SHA256(offset1||digest1||offset2||digest2||...)``
    * - ``reserved: [u8; 4032]``,
      - Overall header size is one page (4096 bytes)
    * - ``offset1: u64``
      - End of first chunk
    * - ``digest1: [u8; 32]``
-     - first chunk digest
+     - First chunk digest
    * - ``offset2: u64``
      - End of second chunk
    * - ``digest2: [u8; 32]``
-     - second chunk digest
+     - Second chunk digest
    * - ...
-     - next chunk offset/digest
+     - Next chunk offset/digest
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 37e32a0e..98079723 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -11,7 +11,7 @@ Glossary
    `Container`_
 
       A container is an isolated user space. Programs run directly on
-      the host's kernel, but with limited access to the host resources.
+      the host's kernel, but with limited access to the host's resources.
 
    Datastore
 
@@ -23,19 +23,19 @@ Glossary
       Rust is a new, fast and memory-efficient system programming
       language. It has no runtime or garbage collector. Rust’s rich type
       system and ownership model guarantee memory-safety and
-      thread-safety. I can eliminate many classes of bugs
+      thread-safety. This can eliminate many classes of bugs
       at compile-time.
 
    `Sphinx`_
 
-      Is a tool that makes it easy to create intelligent and
-      beautiful documentation. It was originally created for the
-      documentation of the Python programming language. It has excellent facilities for the
+      Is a tool that makes it easy to create intelligent and nicely formatted
+      documentation. It was originally created for the documentation of the
+      Python programming language. It has excellent facilities for the
       documentation of software projects in a range of languages.
 
    `reStructuredText`_
 
-      Is an easy-to-read, what-you-see-is-what-you-get plaintext
+      Is an easy-to-read, what-you-see-is-what-you-get, plaintext
       markup syntax and parser system.
 
    `FUSE`
diff --git a/docs/output-format.rst b/docs/output-format.rst
index 79f8a10f..78611e16 100644
--- a/docs/output-format.rst
+++ b/docs/output-format.rst
@@ -1,5 +1,5 @@
-Most commands producing output supports the ``--output-format``
-parameter. It accepts the following values:
+Most commands that produce output support the ``--output-format``
+parameter. This accepts the following values:
 
 :``text``: Text format (default). Structured data is rendered as a table.
 
-- 
2.30.2

[pbs-devel] applied: [PATCH proxmox-backup] docs: language fixup: faq and appendix

[Dietmar Maurer]

applied, thanks!