[pbs-devel] [PATCH proxmox-backup] docs: language fixup: faq and appendix
Dylan Whyte
d.whyte at proxmox.com
Wed Oct 27 16:19:27 CEST 2021
minor formatting and language fixes to the faq section and the appendix
Signed-off-by: Dylan Whyte <d.whyte at 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
More information about the pbs-devel
mailing list