docs: offline-media: improve read- and understandability

by rephrasing parts to be easier to read or adding more context.

Signed-off-by: Aaron Lauterer <a.lauterer@proxmox.com>

diff --git a/docs/offline-media.rst b/docs/offline-media.rst
index bba9a0e9a61cf1af8a3087d82f39270981663385..994aef6dbca59b382e419de5f356abac246957e7 100644 (file)
--- a/docs/offline-media.rst
+++ b/docs/offline-media.rst
@@ -1,9 +1,9 @@
 Offline Media
 =============
 
-A Medium is a file system location on which mirrors and subscription info will be saved at.
-This can be an external, portable disk (for example, USB pen drive) or a local network filesystem
-export.
+A medium is a file system location on which mirrored repositories and subscription information can
+be saved at to make it available to the offline Proxmox systems.  This can be an external portable
+disk (for example a USB pen drive) or a local network share.
 
 Setting Up a Medium
 -------------------
@@ -31,20 +31,21 @@ Syncing a Medium
 To sync the local mirrors to a medium, the following command can be used:
 
 .. code-block:: console
-  
+
   proxmox-offline-mirror medium sync --id pve-bullseye
 
-This command will sync all mirrors linked with this medium to the medium's mountpoint, as well as
-sync all offline keys for further processing by ``proxmox-apt-repo`` on the target system.
+This command will sync all mirrors linked with this medium to the medium's mount point.
+Additionally, it will sync all offline keys for further processing by ``proxmox-apt-repo`` on the
+target system.
 
 Using a Medium
 --------------
 
-After syncing a medium, unmount it and make it accessible on the (offline)
-target system. You can now either manually point apt at the synced snapshots,
-or run ``proxmox-apt-repo setup`` to generate a sources.list.d snippet referecing
-selected mirrors and snapshots. Don't forget to remove the snippet again after
-the upgrade is done.
+After syncing a medium, unmount it and make it accessible on the (offline) target system.  Either
+point `apt` directly at the synced snapshots on the medium or run ``proxmox-apt-repo setup``.  The
+setup will let you select the mirrors and snapshots and can generate a `sources.list.d` snippet.
+This snippet can be saved to the ``/etc/apt/sources.list.d`` directory. The default file name is
+``offline-mirror.list``.  Don't forget to remove the snippet after the upgrade is done.
 
 To activate or update an offline subscription key, either use ``proxmox-apt-repo offline-key`` or
 ``proxmox-apt-repo setup``.

diff --git a/docs/offline-mirror.rst b/docs/offline-mirror.rst
index 0529b75d2a7e0a9492ecce2cdffe0b3fe9feaf98..c5f03c1911890c7f14d88ae02ebac6ab11b10726 100644 (file)
--- a/docs/offline-mirror.rst
+++ b/docs/offline-mirror.rst
@@ -1,26 +1,26 @@
 Offline Repository Mirrors
 ==========================
 
-Offline repository mirrors are pointing to APT repos, for example, those from Proxmox VE, Proxmox
-Backup Server or Debian. After initial setup you can mirror all of the available packages locally,
-organised by creating point in time snapshots of the repositories. Those snapshots can then be
-exported to configured media.
+Offline repository mirrors are pointing to APT repositories, for example from Proxmox VE, Proxmox
+Backup Server or Debian. After the initial setup, you can mirror all the available packages locally.
+They are organized by creating point-in-time snapshots of the repositories. Those snapshots can then
+be exported to a configured medium.
 
 Setting Up a Mirror
 -------------------
 
-First either run the ``setup`` wizard (``proxmox-offline-mirror setup``), or the
+First, either run the ``setup`` wizard (``proxmox-offline-mirror setup``), or the
 ``config mirror add`` command.
 
-.. tip:: The quickest way to setup all relevant repositories for a Proxmox project is to use the
-   ``setup`` wizard, choose the product when adding a mirror and confirm the quesiton about
+.. tip:: The quickest way to set up all relevant repositories for a Proxmox solution is to use the
+   ``setup`` wizard. Choose the product when adding a mirror and confirm the question regarding
    auto-adding the Debian base repos.
 
 For example, to manually add a mirror entry for the Debian Bullseye security repository, the
 following command can be used:
 
 .. code-block:: console
-  
+
   proxmox-offline-mirror config mirror add \
    --id debian-bullseye-security \
    --architectures amd64 \
@@ -32,7 +32,7 @@ following command can be used:
    --dir /path/to/mirror/dir/debian-bullseye-security
 
 .. note:: The `all` architecture is meant for architecture independent packages, not for all
-   possible architectures, and is normally always sensible to add in addition to the host specific
+   possible architectures. It is usually always sensible to add it in addition to the host-specific
    architecture.
 
 Syncing a Mirror
@@ -41,7 +41,7 @@ Syncing a Mirror
 To create the first (and subsequent) snapshots, the following command can be used:
 
 .. code-block:: console
-  
+
   proxmox-offline-mirror mirror snapshot create debian-bullseye-security
 
 .. note:: Depending on the parameters used and the size of the original repository, creating a
@@ -52,5 +52,5 @@ Space Management
 ----------------
 
 After removing a snapshot with ``proxmox-offline-mirror mirror snapshot remove``, a
-``proxmox-offline-mirror mirror gc`` invocation is needed to trigger an garbage collection and
-actually remove any no longer needed contents from the underlying hard link pool.
+``proxmox-offline-mirror mirror gc`` invocation is needed to trigger the garbage collection to
+actually remove any contents from the underlying hard link pool that are no longer needed.