bootctl: separate boot loader specific commands in man and --help

bootctl implements three types of operation: those that work with an EFI
boot loader, those which work with any EFI boot loader that implements
the boot loader spec + interface, and finally those specific to sd-boot.
Previously the --help text and the man page mixed them all up. Let's put
them clearly in three separate sections however, to communicate clearly
what is supposed to work everywhere, and what is specific to
systemd-boot or boot loaders implementing the two specs.

This adjusts wording here and there, but is mostly just about
re-ordering existing docs, and putting them under new sections.

1 files changed, 71 insertions, 46 deletions

diff --git a/man/bootctl.xml b/man/bootctl.xml
index 6db048b63b..d908d52d97 100644
--- a/man/bootctl.xml
+++ b/man/bootctl.xml
@@ -17,7 +17,7 @@
 
   <refnamediv>
     <refname>bootctl</refname>
-    <refpurpose>Control the firmware and boot manager settings</refpurpose>
+    <refpurpose>Control EFI firmware boot settings and manage boot loader</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
@@ -31,16 +31,18 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>bootctl</command> can check the EFI boot loader status, list available boot loaders and boot loader
-    entries, and install, update, or remove the
-    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> boot loader on the
-    current system.</para>
+    <para><command>bootctl</command> can check the EFI firmware and boot loader status, list and manage
+    available boot loaders and boot loader entries, and install, update, or remove the
+    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> boot
+    loader on the current system.</para>
   </refsect1>
 
   <refsect1>
-    <title>Commands</title>
-    <variablelist>
+    <title>Generic EFI Firmware/Boot Loader Commands</title>
+
+    <para>These commands are available on any EFI system, regardless of the boot loader used.</para>
 
+    <variablelist>
       <varlistentry>
         <term><option>status</option></term>
 
@@ -49,8 +51,70 @@
         loaders and the current default boot loader entry. If no command is specified, this is the implied
         default.</para></listitem>
       </varlistentry>
+    </variablelist>
+
+    <varlistentry>
+      <term><option>reboot-to-firmware</option> <optional><replaceable>BOOL</replaceable></optional></term>
+
+      <listitem><para>Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI firmware. Takes a
+      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>
+    </varlistentry>
+
+    <varlistentry>
+      <term><option>systemd-efi-options</option> <optional><replaceable>STRING</replaceable></optional></term>
+
+      <listitem><para>When called without the optional argument, prints the current value of the
+      <literal>SystemdOptions</literal> EFI variable. When called with an argument, sets the
+      variable to that value. See
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      for the meaning of that variable.</para></listitem>
+    </varlistentry>
+  </refsect1>
+
+  <refsect1>
+    <title>Boot Loader Specification Commands</title>
+
+    <para>These commands are available for all boot loaders that implement the <ulink
+    url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> and/or the <ulink
+    url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>, such as
+    <command>systemd-boot</command>.</para>
+
+    <variablelist>
 
       <varlistentry>
+        <term><option>list</option></term>
+
+        <listitem><para>Shows all available boot loader entries implementing the <ulink
+        url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, as well as any
+        other entries discovered or automatically generated by a boot loader implementing the <ulink
+        url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader
+        Interface</ulink>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>set-default</option> <replaceable>ID</replaceable></term>
+        <term><option>set-oneshot</option> <replaceable>ID</replaceable></term>
+
+        <listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string 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></listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title><command>systemd-boot</command> Commands</title>
+
+    <para>These commands manage the <command>systemd-boot</command> EFI boot loader, and do not work in
+    conjunction with other boot loaders.</para>
+
+    <variablelist>
+      <varlistentry>
         <term><option>install</option></term>
 
         <listitem><para>Installs <command>systemd-boot</command> into the EFI system partition. A copy of
@@ -101,45 +165,6 @@
         information.</para></listitem>
       </varlistentry>
 
-      <varlistentry>
-        <term><option>systemd-efi-options</option> <optional><replaceable>STRING</replaceable></optional></term>
-
-        <listitem><para>When called without the optional argument, prints the current value of the
-        <literal>SystemdOptions</literal> EFI variable. When called with an argument, sets the
-        variable to that value. See
-        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-        for the meaning of that variable.</para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>reboot-to-firmware</option> <optional><replaceable>BOOL</replaceable></optional></term>
-
-        <listitem><para>Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI firmware. Takes a
-        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>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>list</option></term>
-
-        <listitem><para>Shows all available boot loader entries implementing the <ulink
-        url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
-        Specification</ulink>, as well as any other entries discovered or automatically generated by the boot
-        loader.</para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>set-default</option> <replaceable>ID</replaceable></term>
-        <term><option>set-oneshot</option> <replaceable>ID</replaceable></term>
-
-        <listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string 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></listitem>
-      </varlistentry>
-
     </variablelist>
   </refsect1>