From 4eb5636b6ce2a605361c1ff1fd62c9ac0c301def Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Fri, 22 Jun 2018 20:19:27 +0200
Subject: [PATCH] man: various updates to the bootctl man page

---
 man/bootctl.xml | 52 +++++++++++++++++++++++++------------------------
 1 file changed, 27 insertions(+), 25 deletions(-)

diff --git a/man/bootctl.xml b/man/bootctl.xml
index 03d01ffe44..9aa5a6b59d 100644
--- a/man/bootctl.xml
+++ b/man/bootctl.xml
@@ -34,10 +34,10 @@
   <refsect1>
     <title>Description</title>
 
-    <para><command>bootctl</command> can check the EFI boot loader status, list
-    available 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 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>
   </refsect1>
 
   <refsect1>
@@ -62,7 +62,7 @@
 
       <varlistentry>
         <term><option>--no-variables</option></term>
-        <listitem><para>Do not touch the EFI boot variables.</para></listitem>
+        <listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para></listitem>
       </varlistentry>
 
       <xi:include href="standard-options.xml" xpointer="no-pager"/>
@@ -78,42 +78,44 @@
       <varlistentry>
         <term><option>status</option></term>
 
-        <listitem><para>Shows the currently installed versions of the boot loader binaries and all current
-        EFI boot variables. If no command is specified, this is the implied default.</para></listitem>
+        <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>
       </varlistentry>
 
       <varlistentry>
         <term><option>list</option></term>
 
-        <listitem><para>Shows all configured boot loader entries.</para></listitem>
+        <listitem><para>Shows all available boot loader entries implementing the <ulink
+        url="https://github.com/systemd/systemd/blob/master/docs/BOOT_LOADER_SPECIFICATION.md">Boot Loader
+        Specification</ulink>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>install</option></term>
+
+        <listitem><para>Installs systemd-boot into the EFI system partition. A copy of <command>systemd-boot</command>
+        will be stored as the EFI default/fallback loader at
+        <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot loader is then added to the
+        top of the firmware's boot loader list.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><option>update</option></term>
 
         <listitem><para>Updates all installed versions of
-        <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-        if the current version is newer than the version installed in the EFI system
-        partition. This also includes the EFI default/fallback loader at
-        <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. A
-        systemd-boot entry in the EFI boot variables is created if there is no current
-        entry. The created entry will be added to the end of the boot order list.</para></listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><option>install</option></term>
-
-        <listitem><para>Installs systemd-boot into the EFI system partition. A copy of systemd-boot will
-        be stored as the EFI default/fallback loader at
-        <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. A systemd-boot entry in
-        the EFI boot variables is created and added to the top of the boot order list.</para></listitem>
+        <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, if the
+        available version is newer than the version installed in the EFI system partition. This also includes the EFI
+        default/fallback loader at <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot
+        loader is then added to end of the firmware's boot loader list if missing.</para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><option>remove</option></term>
 
-        <listitem><para>Removes all installed versions of systemd-boot from the EFI system partition,
-        and removes systemd-boot from the EFI boot variables.</para></listitem>
+        <listitem><para>Removes all installed versions of <command>systemd-boot</command> from the EFI system partition
+        and the firmware's boot loader list.</para></listitem>
       </varlistentry>
 
     </variablelist>