doc: Adjust for usroverlay --read-only

Signed-off-by: Evan Goode <mail@evangoo.de>

Author: evan-goode

crates/lib/src/cli.rs

@@ -269,7 +269,9 @@ pub(crate) struct StatusOpts {
 /// Add a transient overlayfs on /usr
 #[derive(Debug, Parser, PartialEq, Eq)]
 pub(crate) struct UsrOverlayOpts {
-    /// Mount the overlayfs as read-only.
+    /// Mount the overlayfs as read-only. A read-only overlayfs is useful since it may be remounted
+    /// as read/write in a private mount namespace and written to while the mount point remains
+    /// read-only to the rest of the system.
     #[clap(long)]
     pub(crate) read_only: bool,
 }
@@ -793,7 +795,7 @@ pub(crate) enum Opt {
     ///
     /// Shows bootc system state. Outputs YAML by default, human-readable if terminal detected.
     Status(StatusOpts),
-    /// Add a transient writable overlayfs on `/usr`.
+    /// Add a transient overlayfs on `/usr`.
     ///
     /// Allows temporary package installation that will be discarded on reboot.
     #[clap(alias = "usroverlay")]

docs/src/man/bootc-usr-overlay.8.md

@@ -1,16 +1,16 @@
 # NAME
 
-bootc-usr-overlay - Adds a transient writable overlayfs on `/usr` that
-will be discarded on reboot
+bootc-usr-overlay - Adds a transient overlayfs on `/usr` that will be discarded
+on reboot
 
 # SYNOPSIS
 
 **bootc usr-overlay** \[*OPTIONS...*\]
 
 # DESCRIPTION
 
-Adds a transient writable overlayfs on `/usr` that will be discarded
-on reboot.
+Adds a transient overlayfs on `/usr` that will be discarded on reboot. The
+overlayfs is read/write by default.
 
 ## USE CASES
 
@@ -31,7 +31,13 @@ Almost always, a system process will hold a reference to the open mount
 point. You can however invoke `umount -l /usr` to perform a "lazy
 unmount".
 
+# OPTIONS
+
 <!-- BEGIN GENERATED OPTIONS -->
+**--read-only**
+
+    Mount the overlayfs as read-only. A read-only overlayfs is useful since it may be remounted as read/write in a private mount namespace and written to while the mount point remains read-only to the rest of the system
+
 <!-- END GENERATED OPTIONS -->
 
 # VERSION

docs/src/man/bootc.8.md

@@ -30,7 +30,7 @@ pulled and `bootc upgrade`.
 | **bootc rollback** | Change the bootloader entry ordering; the deployment under `rollback` will be queued for the next boot, and the current will become rollback.  If there is a `staged` entry (an unapplied, queued upgrade) then it will be discarded |
 | **bootc edit** | Apply full changes to the host specification |
 | **bootc status** | Display status |
-| **bootc usr-overlay** | Add a transient writable overlayfs on `/usr` |
+| **bootc usr-overlay** | Add a transient overlayfs on `/usr` |
 | **bootc install** | Install the running container to a target |
 | **bootc container** | Operations which can be executed as part of a container build |
 | **bootc composefs-finalize-staged** |  |