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.

diff --git a/man/bootctl.xml b/man/bootctl.xml
index 6db048b63be3035a10081922308a541a5313052a..d908d52d972f7c9173b5010ccc46ad41c6cb7fe6 100644 (file)
--- 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,7 +51,69 @@
         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>
 
@@ -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>
 

diff --git a/src/boot/bootctl.c b/src/boot/bootctl.c
index f464882186fcc7b65e802c7a29ff1c53f61367c8..0e24f0a499a58c0c4da9dbe46fd7f762db9e71d5 100644 (file)
--- a/src/boot/bootctl.c
+++ b/src/boot/bootctl.c
@@ -1014,24 +1014,25 @@ static int help(int argc, char *argv[], void *userdata) {
         if (r < 0)
                 return log_oom();
 
-        printf("%s  [OPTIONS...] COMMAND ...\n"
-               "\n%sInstall/update/remove the systemd-boot EFI boot manager and list/select entries.%s\n"
-               "\nBoot Loader Commands:\n"
-               "  status              Show status of installed systemd-boot and EFI variables\n"
-               "  install             Install systemd-boot to the ESP and EFI variables\n"
-               "  update              Update systemd-boot in the ESP and EFI variables\n"
-               "  remove              Remove systemd-boot from the ESP and EFI variables\n"
-               "  is-installed        Test whether systemd-boot is installed in the ESP\n"
-               "  random-seed         Initialize random seed in ESP and EFI variables\n"
-               "  systemd-efi-options [STRING]\n"
-               "                      Query or set system options string in EFI variable\n"
+        printf("%1$s  [OPTIONS...] COMMAND ...\n"
+               "\n%5$sControl EFI firmware boot settings and manage boot loader.%6$s\n"
+               "\n%3$sGeneric EFI Firmware/Boot Loader Commands:%4$s\n"
+               "  status              Show status of installed boot loader and EFI variables\n"
                "  reboot-to-firmware [BOOL]\n"
                "                      Query or set reboot-to-firmware EFI flag\n"
-               "\nBoot Loader Entries Commands:\n"
+               "  systemd-efi-options [STRING]\n"
+               "                      Query or set system options string in EFI variable\n"
+               "\n%3$sBoot Loader Specification Commands:%4$s\n"
                "  list                List boot loader entries\n"
                "  set-default ID      Set default boot loader entry\n"
                "  set-oneshot ID      Set default boot loader entry, for next boot only\n"
-               "\nOptions:\n"
+               "\n%3$ssystemd-boot Commands:%4$s\n"
+               "  install             Install systemd-boot to the ESP and EFI variables\n"
+               "  update              Update systemd-boot in the ESP and EFI variables\n"
+               "  remove              Remove systemd-boot from the ESP and EFI variables\n"
+               "  is-installed        Test whether systemd-boot is installed in the ESP\n"
+               "  random-seed         Initialize random seed in ESP and EFI variables\n"
+               "\n%3$sOptions:%4$s\n"
                "  -h --help            Show this help\n"
                "     --version         Print version\n"
                "     --esp-path=PATH   Path to the EFI System Partition (ESP)\n"
@@ -1042,11 +1043,12 @@ static int help(int argc, char *argv[], void *userdata) {
                "     --no-pager        Do not pipe output into a pager\n"
                "     --graceful        Don't fail when the ESP cannot be found or EFI\n"
                "                       variables cannot be written\n"
-               "\nSee the %s for details.\n"
+               "\nSee the %2$s for details.\n"
                , program_invocation_short_name
-               , ansi_highlight()
-               , ansi_normal()
-               , link);
+               , link
+               , ansi_underline(), ansi_normal()
+               , ansi_highlight(), ansi_normal()
+        );
 
         return 0;
 }