Merge pull request #243 from cgwalters/man-improvements

vrothberg · web-flow · commit 226227f167a3 · 2024-01-02T08:52:42.000+01:00
Man improvements
diff --git a/lib/src/cli.rs b/lib/src/cli.rs
@@ -152,23 +152,49 @@ pub(crate) enum TestingOpts {
 #[clap(rename_all = "kebab-case")]
 #[allow(clippy::large_enum_variant)]
 pub(crate) enum Opt {
-    /// Look for updates to the booted container image.
+    /// Download and queue an updated container image to apply.
+    ///
+    /// This does not affect the running system; updates operate in an "A/B" style by default.
+    ///
+    /// A queued update is visible as `staged` in `bootc status`.
+    ///
+    /// Currently by default, the update will be applied at shutdown time via `ostree-finalize-staged.service`.
+    /// There is also an explicit `bootc upgrade --apply` verb which will automatically take action (rebooting)
+    /// if the system has changed.
+    ///
+    /// However, in the future this is likely to change such that reboots outside of a `bootc upgrade --apply`
+    /// do *not* upgrade.
     #[clap(alias = "update")]
     Upgrade(UpgradeOpts),
     /// Target a new container image reference to boot.
+    ///
+    /// This operates in a very similar fashion to `upgrade`, but changes the container image reference
+    /// instead.
     Switch(SwitchOpts),
-    /// Change host specification
+    /// Apply full changes to the host specification.
+    ///
+    /// This command operates very similarly to `kubectl apply`; if invoked interactively,
+    /// then the current host specification will be presented in the system default `$EDITOR`
+    /// for interactive changes.
+    ///
+    /// It is also possible to directly provide new contents via `bootc edit --filename`.
+    ///
+    /// Only changes to the `spec` section are honored.
     Edit(EditOpts),
     /// Display status
     ///
     /// This will output a YAML-formatted object using a schema intended to match a Kubernetes resource
-    /// that describes the state of the booted container.
+    /// that describes the state of the booted system.
+    ///
     /// The exact API format is not currently declared stable.
     Status(StatusOpts),
     /// Add a transient writable overlayfs on `/usr` that will be discarded on reboot.
     #[clap(alias = "usroverlay")]
     UsrOverlay,
-    /// Install the running container to a target
+    /// Install the running container to a target.
+    ///
+    /// This has two main sub-commands `to-disk` (which expects an empty block device) and `to-filesystem`
+    /// which supports installation to an already extant filesystem.
     #[clap(subcommand)]
     #[cfg(feature = "install")]
     Install(InstallOpts),
diff --git a/manpages-md/bootc-edit.md b/manpages-md/bootc-edit.md
@@ -1,6 +1,6 @@
 # NAME
 
-bootc-edit - Change host specification
+bootc-edit - Apply full changes to the host specification
 
 # SYNOPSIS
 
@@ -9,7 +9,16 @@ bootc-edit - Change host specification
 
 # DESCRIPTION
 
-Change host specification
+Apply full changes to the host specification.
+
+This command operates very similarly to \`kubectl apply\`; if invoked
+interactively, then the current host specification will be presented in
+the system default \`\$EDITOR\` for interactive changes.
+
+It is also possible to directly provide new contents via \`bootc edit
+\--filename\`.
+
+Only changes to the \`spec\` section are honored.
 
 # OPTIONS
 
@@ -23,7 +32,7 @@ Change host specification
 
 **-h**, **\--help**
 
-:   Print help
+:   Print help (see a summary with -h)
 
 **-V**, **\--version**
 
diff --git a/manpages-md/bootc-install-to-disk.md b/manpages-md/bootc-install-to-disk.md
@@ -6,7 +6,7 @@ bootc-install-to-disk - Install to the target block device
 
 **bootc-install-to-disk** \[**\--wipe**\] \[**\--block-setup**\]
 \[**\--filesystem**\] \[**\--root-size**\] \[**\--target-transport**\]
-\[**\--target-imgref**\] \[**\--target-no-signature-verification**\]
+\[**\--target-imgref**\] \[**\--enforce-container-sigpolicy**\]
 \[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\]
 \[**\--disable-selinux**\] \[**\--karg**\] \[**\--generic-image**\]
 \[**-h**\|**\--help**\] \[**-V**\|**\--version**\] \<*DEVICE*\>
@@ -53,9 +53,12 @@ By default, all remaining space on the disk will be used.
 
 :   Specify the image to fetch for subsequent updates
 
-**\--target-no-signature-verification**
+**\--enforce-container-sigpolicy**
 
-:   Explicitly opt-out of requiring any form of signature verification
+:   This is the inverse of the previous
+    \`\--target-no-signature-verification\` (which is now a no-op).
+    Enabling this option enforces that \`/etc/containers/policy.json\`
+    includes a default policy which requires signatures
 
 **\--target-ostree-remote**=*TARGET_OSTREE_REMOTE*
 
@@ -68,11 +71,9 @@ By default, all remaining space on the disk will be used.
     suppresses the check; use this when you know the issues it might
     find are addressed.
 
-Two main reasons this might fail:
-
-\- Forgetting \`\--target-no-signature-verification\` if needed - Using
-a registry which requires authentication, but not embedding the pull
-secret in the image.
+A common reason this may fail is when one is using an image which
+requires registry authentication, but not embedding the pull secret in
+the image so that updates can be fetched by the installed OS \"day 2\".
 
 **\--disable-selinux**
 
diff --git a/manpages-md/bootc-install-to-filesystem.md b/manpages-md/bootc-install-to-filesystem.md
@@ -7,10 +7,10 @@ bootc-install-to-filesystem - Install to the target filesystem
 **bootc-install-to-filesystem** \[**\--root-mount-spec**\]
 \[**\--root-options**\] \[**\--boot-mount-spec**\] \[**\--replace**\]
 \[**\--target-transport**\] \[**\--target-imgref**\]
-\[**\--target-no-signature-verification**\]
-\[**\--target-ostree-remote**\] \[**\--skip-fetch-check**\]
-\[**\--disable-selinux**\] \[**\--karg**\] \[**\--generic-image**\]
-\[**-h**\|**\--help**\] \[**-V**\|**\--version**\] \<*ROOT_PATH*\>
+\[**\--enforce-container-sigpolicy**\] \[**\--target-ostree-remote**\]
+\[**\--skip-fetch-check**\] \[**\--disable-selinux**\] \[**\--karg**\]
+\[**\--generic-image**\] \[**-h**\|**\--help**\]
+\[**-V**\|**\--version**\] \<*ROOT_PATH*\>
 
 # DESCRIPTION
 
@@ -62,9 +62,12 @@ be used.
 
 :   Specify the image to fetch for subsequent updates
 
-**\--target-no-signature-verification**
+**\--enforce-container-sigpolicy**
 
-:   Explicitly opt-out of requiring any form of signature verification
+:   This is the inverse of the previous
+    \`\--target-no-signature-verification\` (which is now a no-op).
+    Enabling this option enforces that \`/etc/containers/policy.json\`
+    includes a default policy which requires signatures
 
 **\--target-ostree-remote**=*TARGET_OSTREE_REMOTE*
 
@@ -77,11 +80,9 @@ be used.
     suppresses the check; use this when you know the issues it might
     find are addressed.
 
-Two main reasons this might fail:
-
-\- Forgetting \`\--target-no-signature-verification\` if needed - Using
-a registry which requires authentication, but not embedding the pull
-secret in the image.
+A common reason this may fail is when one is using an image which
+requires registry authentication, but not embedding the pull secret in
+the image so that updates can be fetched by the installed OS \"day 2\".
 
 **\--disable-selinux**
 
diff --git a/manpages-md/bootc-install.md b/manpages-md/bootc-install.md
@@ -9,13 +9,17 @@ bootc-install - Install the running container to a target
 
 # DESCRIPTION
 
-Install the running container to a target
+Install the running container to a target.
+
+This has two main sub-commands \`to-disk\` (which expects an empty block
+device) and \`to-filesystem\` which supports installation to an already
+extant filesystem.
 
 # OPTIONS
 
 **-h**, **\--help**
 
-:   Print help
+:   Print help (see a summary with -h)
 
 **-V**, **\--version**
 
diff --git a/manpages-md/bootc-status.md b/manpages-md/bootc-status.md
@@ -13,7 +13,9 @@ Display status
 
 This will output a YAML-formatted object using a schema intended to
 match a Kubernetes resource that describes the state of the booted
-container. The exact API format is not currently declared stable.
+system.
+
+The exact API format is not currently declared stable.
 
 # OPTIONS
 
diff --git a/manpages-md/bootc-switch.md b/manpages-md/bootc-switch.md
@@ -5,13 +5,16 @@ bootc-switch - Target a new container image reference to boot
 # SYNOPSIS
 
 **bootc-switch** \[**\--quiet**\] \[**\--transport**\]
-\[**\--no-signature-verification**\] \[**\--ostree-remote**\]
+\[**\--enforce-container-sigpolicy**\] \[**\--ostree-remote**\]
 \[**\--retain**\] \[**-h**\|**\--help**\] \[**-V**\|**\--version**\]
 \<*TARGET*\>
 
 # DESCRIPTION
 
-Target a new container image reference to boot
+Target a new container image reference to boot.
+
+This operates in a very similar fashion to \`upgrade\`, but changes the
+container image reference instead.
 
 # OPTIONS
 
@@ -23,9 +26,13 @@ Target a new container image reference to boot
 
 :   The transport; e.g. oci, oci-archive. Defaults to \`registry\`
 
-**\--no-signature-verification**
+**\--enforce-container-sigpolicy**
+
+:   This is the inverse of the previous
+    \`\--target-no-signature-verification\` (which is now a no-op).
 
-:   Explicitly opt-out of requiring any form of signature verification
+Enabling this option enforces that \`/etc/containers/policy.json\`
+includes a default policy which requires signatures.
 
 **\--ostree-remote**=*OSTREE_REMOTE*
 
@@ -37,7 +44,7 @@ Target a new container image reference to boot
 
 **-h**, **\--help**
 
-:   Print help
+:   Print help (see a summary with -h)
 
 **-V**, **\--version**
 
diff --git a/manpages-md/bootc-upgrade.md b/manpages-md/bootc-upgrade.md
@@ -1,6 +1,6 @@
 # NAME
 
-bootc-upgrade - Look for updates to the booted container image
+bootc-upgrade - Download and queue an updated container image to apply
 
 # SYNOPSIS
 
@@ -10,7 +10,20 @@ bootc-upgrade - Look for updates to the booted container image
 
 # DESCRIPTION
 
-Look for updates to the booted container image
+Download and queue an updated container image to apply.
+
+This does not affect the running system; updates operate in an \"A/B\"
+style by default.
+
+A queued update is visible as \`staged\` in \`bootc status\`.
+
+Currently by default, the update will be applied at shutdown time via
+\`ostree-finalize-staged.service\`. There is also an explicit \`bootc
+upgrade \--apply\` verb which will automatically take action (rebooting)
+if the system has changed.
+
+However, in the future this is likely to change such that reboots
+outside of a \`bootc upgrade \--apply\` do \*not\* upgrade.
 
 # OPTIONS
 
diff --git a/manpages-md/bootc.md b/manpages-md/bootc.md
@@ -29,15 +29,15 @@ Changes in \`/etc\` and \`/var\` persist.
 
 bootc-upgrade(8)
 
-:   Look for updates to the booted container image
+:   Download and queue an updated container image to apply
 
 bootc-switch(8)
 
 :   Target a new container image reference to boot
 
 bootc-edit(8)
 
-:   Change host specification
+:   Apply full changes to the host specification
 
 bootc-status(8)
 
diff --git a/xtask/src/xtask.rs b/xtask/src/xtask.rs
@@ -103,7 +103,7 @@ fn man2markdown(sh: &Shell) -> Result<()> {
             .file_stem()
             .and_then(|name| name.to_str())
             .ok_or_else(|| anyhow!("Expected filename in {path:?}"))?;
-        let target = format!("docs/man/{filename}.md");
+        let target = format!("manpages-md/{filename}.md");
         cmd!(
             sh,
             "pandoc --from=man --to=markdown --output={target} {path}"
