man: update systemd-boot(7) man page in many ways

Let's fully document where the list of entries come from, including unified
images and such.

Let's add a "Files" section (replacing the "Configuration" section), and
let's move it after they keybinding section (why? because keybinds are
primary UI material, while configuration is one level more complex than
that).

Also, reword lot's of stuff to make it more precise.

Fixes: #5127

1 files changed, 56 insertions, 38 deletions

diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml
index 0a1543d59..5cd8a3815 100644
--- a/man/systemd-boot.xml
+++ b/man/systemd-boot.xml
@@ -25,48 +25,51 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>systemd-boot</command> or <command>sd-boot</command> is a simple
-    UEFI boot manager, previously known as <command>gummiboot</command>. It provides
-    a graphical menu to select the entry to boot and an editor for the kernel command
-    line. systemd-boot is only useful on machines using UEFI.
-    </para>
-
-    <para>systemd-boot loads information from the EFI system partition (ESP), usually
-    mounted at <filename>/boot</filename>, <filename>/efi</filename>, or
-    <filename>/boot/efi</filename>. Configuration file fragments, kernels, initrds,
-    other EFI images need to reside on the ESP. Linux kernels must be built with
-    <option>CONFIG_EFI_STUB</option> to be able to be directly executed as an EFI
-    image. systemd-boot will automatically list other boot entries registered as EFI boot
-    variables, and a list of kernels from configuration files following the <ulink
-    url="https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec">Boot Loader
-    Specification</ulink> located under <filename>/loader/entries/</filename> on the
-    ESP.</para>
-
-    <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    may be used to copy kernel images onto the ESP and to generate entries compliant
-    with the Boot Loader Specification.
-    <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    may be used from a running system to locate the ESP, list available entries, and
-    install systemd-boot itself.</para>
-
-    <para>systemd-boot will provide information about the time spent in UEFI firmware
-    using the
-    <ulink url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>.
-    This information can be displayed using
+    <para><command>systemd-boot</command> (short: <command>sd-boot</command>) is a simple UEFI boot manager. It
+    provides a graphical menu to select the entry to boot and an editor for the kernel command line. systemd-boot
+    supports systems with an UEFI firmware only.</para>
+
+    <para>systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at
+    <filename>/boot</filename>, <filename>/efi</filename>, or <filename>/boot/efi</filename> during OS
+    runtime. Configuration file fragments, kernels, initrds and other EFI images to boot generally need to reside on
+    the ESP. Linux kernels must be built with <option>CONFIG_EFI_STUB</option> to be able to be directly executed as an
+    EFI image. During boot systemd-boot automatically assembles a list of boot entries from the following
+    sources:</para>
+
+    <itemizedlist>
+      <listitem><para>Boot entries defined with <ulink
+      url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader
+      Specification</ulink> description files located in <filename>/loader/entries/</filename> on the ESP. These
+      usually describe Linux kernel images with associated initrd images, but alternatively may also describe
+      arbitrary other EFI executables.</para></listitem>
+
+      <listitem><para>Unified kernel images following the <ulink
+      url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot
+      Loader Specification</ulink>, as executable EFI binaries in
+      <filename>/EFI/Linux/</filename> on the ESP</para></listitem>
+
+      <listitem><para>The Microsoft Windows EFI boot manager, if installed</para></listitem>
+
+      <listitem><para>The Apple MacOS X boot manager, if installed</para></listitem>
+
+      <listitem><para>The EFI Shell binary, if installed</para></listitem>
+
+      <listitem><para>A reboot into the UEFI firmware setup option, if supported by the firmware</para></listitem>
+    </itemizedlist>
+
+    <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> may be
+    used to copy kernel images onto the ESP and to generate description files compliant with the Boot Loader
+    Specification. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> may be
+    used from a running system to locate the ESP, list available entries, and install systemd-boot itself.</para>
+
+    <para>systemd-boot will provide information about the time spent in UEFI firmware using the <ulink
+    url="https://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface">Boot Loader Interface</ulink>. This
+    information can be displayed using
     <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
     </para>
   </refsect1>
 
   <refsect1>
-    <title>Configuration</title>
-
-    <para>systemd-boot reads configuration like the timeout and default entry from
-    <filename>/loader/loader.conf</filename> on the ESP and from EFI variables. See
-    <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-    </para>
-  </refsect1>
-
-  <refsect1>
     <title>Key bindings</title>
     <para>The following keys may be used in the boot menu:</para>
 
@@ -171,7 +174,7 @@
         <term>7</term>
         <term>8</term>
         <term>9</term>
-        <listitem><para>Entry number 1 .. 9</para></listitem>
+        <listitem><para>Boot entry number 1 … 9</para></listitem>
       </varlistentry>
     </variablelist>
 
@@ -220,6 +223,21 @@
   </refsect1>
 
   <refsect1>
+    <title>Files</title>
+
+    <para>The files systemd-boot reads generally reside on the UEFI ESP which is usually mounted to
+    <filename>/boot/</filename>, <filename>/efi/</filename> or <filename>/boot/efi</filename> during OS
+    runtime. systemd-boot reads runtime configuration such as the boot timeout and default entry from
+    <filename>/loader/loader.conf</filename> on the ESP (in combination with data read from EFI variables). See
+    <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Boot entry
+    description files following the <ulink
+    url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot Loader
+    Specification</ulink> are read from <filename>/loader/entries/</filename> on the ESP. Unified kernel boot entries
+    following the <ulink url="https://github.com/systemd/systemd/blob/master/doc/BOOT_LOADER_SPECIFICATION.md">Boot
+    Loader Specification</ulink> are read from <filename>/EFI/Linux/</filename> on the ESP.</para>
+  </refsect1>
+
+  <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,