man: add annotated example for bootctl status & list

This is based on the output on my laptop, with various manual adjustments.
If people have other types of entries, it'd be useful to add them here. In
particular, some dual-boot entries would be nice.

1 files changed, 112 insertions, 4 deletions

diff --git a/man/bootctl.xml b/man/bootctl.xml
index c8e774d439..4aab53ece1 100644
--- a/man/bootctl.xml
+++ b/man/bootctl.xml
@@ -49,7 +49,10 @@
         <listitem><para>Shows brief information about the system firmware, the boot loader that was used to
         boot the system, the boot loaders currently available in the ESP, the boot loaders listed in the
         firmware's list of boot loaders and the current default boot loader entry. If no command is
-        specified, this is the implied default.</para></listitem>
+        specified, this is the implied default.</para>
+
+        <para>See the example below for details of the output.</para>
+        </listitem>
       </varlistentry>
 
       <varlistentry>
@@ -89,10 +92,10 @@
         <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>
+        url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.
+        JSON output may be requested with <option>--json=</option>.</para>
 
-        <para>JSON output may be requested with <option>--json=</option>.</para>
+        <para>See the example below for details of the output.</para>
         </listitem>
       </varlistentry>
 
@@ -345,6 +348,111 @@
   </refsect1>
 
   <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Output from <command>status</command> and <command>list</command></title>
+
+      <programlisting>$ <command>bootctl status</command>
+System:
+     Firmware: UEFI 2.40 (<replaceable>firmware-version</replaceable>)  ← firmware vendor and version
+  Secure Boot: disabled (setup)              ← secure boot status
+ TPM2 Support: yes
+ Boot into FW: supported                     ← does the firmware support booting into itself
+
+Current Boot Loader:                         ← details about sd-boot or another boot loader
+      Product: systemd-boot <replaceable>version</replaceable>            implementing the <ulink
+    url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
+     Features: ✓ Boot counting
+               ✓ Menu timeout control
+               ✓ One-shot menu timeout control
+               ✓ Default entry control
+               ✓ One-shot entry control
+               ✓ Support for XBOOTLDR partition
+               ✓ Support for passing random seed to OS
+               ✓ Load drop-in drivers
+               ✓ Boot loader sets ESP information
+          ESP: /dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000
+         File: └─/EFI/systemd/systemd-bootx64.efi
+
+Random Seed:                                 ← random seed used for entropy in early boot
+ Passed to OS: yes
+ System Token: set
+       Exists: yes
+
+Available Boot Loaders on ESP:
+          ESP: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
+         File: └─/EFI/systemd/systemd-bootx64.efi (systemd-boot 251
+         File: └─/EFI/BOOT/BOOTX64.EFI (systemd-boot 251
+
+Boot Loaders Listed in EFI Variables:
+        Title: Linux Boot Manager
+           ID: 0x0001
+       Status: active, boot-order
+    Partition: /dev/disk/by-partuuid/…
+         File: └─/EFI/systemd/systemd-bootx64.efi
+
+        Title: Fedora
+           ID: 0x0000
+       Status: active, boot-order
+    Partition: /dev/disk/by-partuuid/…
+         File: └─/EFI/fedora/shimx64.efi
+
+        Title: Linux-Firmware-Updater
+           ID: 0x0002
+       Status: active, boot-order
+    Partition: /dev/disk/by-partuuid/…
+         File: └─/EFI/fedora/fwupdx64.efi
+
+Boot Loader Entries:
+        $BOOT: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
+
+Default Boot Loader Entry:
+         type: Boot Loader Specification Type #1 (.conf)
+        title: Fedora Linux 36 (Workstation Edition)
+           id: …
+       source: /boot/efi/loader/entries/<replaceable>entry-token</replaceable>-<replaceable>kernel-version</replaceable>.conf
+      version: <replaceable>kernel-version</replaceable>
+   machine-id: …
+        linux: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/linux
+       initrd: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/initrd
+      options: root=…
+</programlisting>
+
+      <programlisting>$ <command>bootctl list</command>
+Boot Loader Entries:
+         type: Boot Loader Specification Type #1 (.conf)
+        title: Fedora Linux 36 (Workstation Edition) (default) (selected)
+           id: …
+       source: /boot/efi/loader/entries/<replaceable>entry-token</replaceable>-<replaceable>kernel-version</replaceable>.conf
+      version: <replaceable>kernel-version</replaceable>
+   machine-id: …
+        linux: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/linux
+       initrd: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/initrd
+      options: root=…
+
+         type: Boot Loader Specification Type #2 (.efi)
+        title: Fedora Linux 35 (Workstation Edition)
+           id: …
+       source: /boot/efi/EFI/Linux/fedora-<replaceable>kernel-version</replaceable>.efi
+      version: <replaceable>kernel-version</replaceable>
+   machine-id: …
+        linux: /EFI/Linux/fedora-<replaceable>kernel-version</replaceable>.efi
+      options: root=…
+
+         type: Automatic
+        title: Reboot Into Firmware Interface
+           id: auto-reboot-to-firmware-setup
+       source: /sys/firmware/efi/efivars/LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
+</programlisting>
+
+       <para>In the listing, <literal>(default)</literal> specifies the entry that will be
+       used by default, and <literal>(selected)</literal> specifies the entry that was
+       selected the last time (i.e. is currently running).</para>
+    </example>
+  </refsect1>
+
+  <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,