Merge pull request #23217 from keszybz/oomd-docs

More cross-references in bootctl/systemctl man pages

TODO

@@ -31,6 +31,7 @@ External:
 * zsh shell completion:
   - <command> <verb> -<TAB> should complete options, but currently does not
   - systemctl add-wants,add-requires
+  - systemctl reboot --boot-loader-entry=
 
 * systemctl status should know about 'systemd-analyze calendar ... --iterations='
 * If timer has just OnInactiveSec=..., it should fire after a specified time
@@ -207,8 +208,6 @@ Features:
   sd_device object, so that data passed into sd_device_new_from_devnum() can
   also be queried.
 
-* bootctl: show whether UEFI audit mode is available
-
 * sd-event: optionally, if per-event source rate limit is hit, downgrade
   priority, but leave enabled, and once ratelimit window is over, upgrade
   priority again. That way we can combat event source starvation without
@@ -1353,10 +1352,12 @@ Features:
 * bootctl,sd-boot: actually honour the "architecture" key
 
 * bootctl:
+  - show whether UEFI audit mode is available
   - teach it to prepare an ESP wholesale, i.e. with mkfs.vfat invocation
   - teach it to copy in unified kernel images and maybe type #1 boot loader spec entries from host
   - make it operate on loopback files, dissecting enough to find ESP to operate on
   - bootspec: properly support boot attempt counters when parsing entry file names
+  - support --quiet in is-installed, update
 
 * kernel-install:
   - optionally, support generating type #2 entries instead of type #1, including signing them

man/bootctl.xml

@@ -62,7 +62,12 @@
         boolean argument which controls whether to show the firmware setup on next system reboot. If the
         argument is omitted shows the current status of the flag, or whether the flag is supported. This
         controls the same flag as <command>systemctl reboot --firmware-setup</command>, but is more low-level
-        and allows setting the flag independently from actually requesting a reboot.</para></listitem>
+        and allows setting the flag independently from actually requesting a reboot.</para>
+
+        <para>Hint: use <command>systemctl reboot --firmware-setup</command> to reboot into firmware setup
+        once. See
+        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        for details.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -107,7 +112,10 @@
         pattern as argument. The <option>set-oneshot</option> command will set the default entry only for the next boot,
         the <option>set-default</option> will set it persistently for all future boots.</para>
 
-        <para>Optionally, the boot loader entry ID may be specified as one of: <option>@default</option>,
+        <para><command>bootctl list</command> can be used to list available boot loader entries and their
+        IDs.</para>
+
+        <para>In addition, the boot loader entry ID may be specified as one of: <option>@default</option>,
         <option>@oneshot</option> or <option>@current</option>, which correspond to the current default boot loader
         entry for all future boots, the current default boot loader entry for the next boot, and the currently booted
         boot loader entry. These special IDs are resolved to the current values of the EFI variables
@@ -120,8 +128,15 @@
         <para>If set to <option>@saved</option> the chosen entry will be saved as an EFI variable
         on every boot and automatically selected the next time the boot loader starts.</para>
 
-        <para>When an empty string ("") is specified as an ID, then the corresponding EFI variable will be unset.
-        </para></listitem>
+        <para>When an empty string ("") is specified as the ID, then the corresponding EFI variable will be
+        unset.</para>
+
+        <para>Hint: use <command>systemctl reboot --boot-loader-entry=<replaceable>ID</replaceable></command>
+        to reboot into a specific boot entry and
+        <command>systemctl reboot --boot-loader-menu=<replaceable>timeout</replaceable></command>
+        to reboot into the boot loader menu once. See
+        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        for details.</para></listitem>
       </varlistentry>
 
       <varlistentry>

man/systemctl.xml

@@ -1447,10 +1447,12 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
           <term><command>reboot</command></term>
 
           <listitem>
-            <para>Shut down and reboot the system. This is mostly equivalent to <command>systemctl start reboot.target
-            --job-mode=replace-irreversibly --no-block</command>, but also prints a wall message to all users. This
-            command is asynchronous; it will return after the reboot operation is enqueued, without waiting for it to
-            complete.</para>
+            <para>Shut down and reboot the system.</para>
+
+            <para>This command mostly equivalent to <command>systemctl start reboot.target
+            --job-mode=replace-irreversibly --no-block</command>, but also prints a wall message to all
+            users. This command is asynchronous; it will return after the reboot operation is enqueued,
+            without waiting for it to complete.</para>
 
             <para>If combined with <option>--force</option>, shutdown of all running services is skipped, however all
             processes are killed and all file systems are unmounted or mounted read-only, immediately followed by the
@@ -1463,6 +1465,10 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
             <para>If the switch <option>--reboot-argument=</option> is given, it will be passed as the optional
             argument to the <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
             system call.</para>
+
+            <para>Options <option>--boot-loader-entry=</option>, <option>--boot-loader-menu=</option>, and
+            <option>--firmware-setup</option> can be used to select what to do <emphasis>after</emphasis> the
+            reboot. See the descriptions of those options for details.</para>
           </listitem>
         </varlistentry>
 
@@ -2249,7 +2255,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
       </varlistentry>
 
       <varlistentry>
-        <term><option>--boot-loader-menu=</option></term>
+        <term><option>--boot-loader-menu=<replaceable>timeout</replaceable></option></term>
 
         <listitem>
           <para>When used with the <command>reboot</command> command, indicate to the system's boot loader to
@@ -2260,7 +2266,7 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
       </varlistentry>
 
       <varlistentry>
-        <term><option>--boot-loader-entry=</option></term>
+        <term><option>--boot-loader-entry=<replaceable>ID</replaceable></option></term>
 
         <listitem>
           <para>When used with the <command>reboot</command> command, indicate to the system's boot loader to