From 41f392490e97c46bf8b304e34bc578ea4087f3c2 Mon Sep 17 00:00:00 2001
From: Yu Watanabe <watanabe.yu+github@gmail.com>
Date: Fri, 7 Feb 2025 15:20:25 +0900
Subject: [PATCH] man/kernel-install: update documents for plugins

Addresses the post-merge comments in #36218.
---
 man/kernel-install.xml   | 145 ++++++++++++++++++++++++---------------
 tools/command_ignorelist |   6 ++
 2 files changed, 97 insertions(+), 54 deletions(-)

diff --git a/man/kernel-install.xml b/man/kernel-install.xml
index 7c0ef0efc9f..9beff5c4de7 100644
--- a/man/kernel-install.xml
+++ b/man/kernel-install.xml
@@ -90,9 +90,7 @@
     <para>The following commands are understood:</para>
     <variablelist>
       <varlistentry>
-        <term>
-          <command>add [[[<replaceable>KERNEL-VERSION</replaceable>] <replaceable>KERNEL-IMAGE</replaceable>] [<replaceable>INITRD-FILE</replaceable> ...]]</command>
-        </term>
+        <term><command>add [[[<replaceable>KERNEL-VERSION</replaceable>] <replaceable>KERNEL-IMAGE</replaceable>] [<replaceable>INITRD-FILE</replaceable> ...]]</command></term>
 
         <listitem>
           <para>This command takes a kernel version string and a path to a kernel image file as arguments. If
@@ -107,8 +105,7 @@
           <filename>/etc/kernel/install.d/*.install</filename> (i.e. the plugins) are called with the
           following arguments:</para>
 
-          <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> \
-          [<replaceable>INITRD-FILE</replaceable> ...]</programlisting>
+          <programlisting>add <replaceable>KERNEL-VERSION</replaceable> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename> <replaceable>KERNEL-IMAGE</replaceable> [<replaceable>INITRD-FILE</replaceable> ...]</programlisting>
 
           <para>The third argument directly refers to the path where to place kernel images, initrd
           images and other resources for
@@ -119,41 +116,66 @@
           <para>The <replaceable>ENTRY-TOKEN</replaceable> string is typically the machine ID and is supposed
           to identify the local installation on the system. For details see below.</para>
 
-          <para>Two default plugins execute the following operations in this case:</para>
-
-          <itemizedlist>
-            <listitem><para><command>kernel-install</command> creates
-            <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable></filename>,
-            if enabled (see <varname>$KERNEL_INSTALL_LAYOUT</varname>).</para></listitem>
-
-            <listitem><para><filename>50-depmod.install</filename> runs
-            <citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
-            <replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
-
-            <listitem><para><filename>90-loaderentry.install</filename> copies
-            <replaceable>KERNEL-IMAGE</replaceable> to
-            <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
-            If <replaceable>INITRD-FILE</replaceable>s are provided, it also copies them to
-            <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>.
-            This can also be used to prepend microcode before the actual initrd. It also creates a boot loader entry according to the <ulink
-            url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> (Type #1) in
-            <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
-            The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
-            <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the former
-            is missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para>
-
-            <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "bls", this plugin does nothing.</para></listitem>
-
-            <listitem><para><filename>90-uki-copy.install</filename> copies a file
-            <filename>uki.efi</filename> from <varname>$KERNEL_INSTALL_STAGING_AREA</varname> or if it does
-            not exist the <replaceable>KERNEL-IMAGE</replaceable> argument, only if it has a
-            <literal>.efi</literal> extension, to
-            <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi</filename>.</para>
-
-            <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "uki", this plugin does nothing.</para></listitem>
-          </itemizedlist>
+          <para><command>kernel-install</command> creates
+          <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable></filename>,
+          if enabled (see <varname>$KERNEL_INSTALL_LAYOUT</varname>).</para>
+
+          <para>Three default plugins execute the following operations in this case:</para>
+
+          <variablelist>
+            <varlistentry>
+              <term><filename>50-depmod.install</filename></term>
+              <listitem>
+                <para>The plugin runs
+                <citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+                for the <replaceable>KERNEL-VERSION</replaceable>.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><filename>90-loaderentry.install</filename></term>
+              <listitem>
+                <para>The plugin copies <replaceable>KERNEL-IMAGE</replaceable> to
+                <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/linux</filename>.
+                If <replaceable>INITRD-FILE</replaceable>s are provided, it also copies them to
+                <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>.
+                This can also be used to prepend microcode before the actual initrd. It also creates a boot
+                loader entry according to the
+                <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>
+                (Type #1) in
+                <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
+                The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
+                <filename>/etc/os-release</filename> or <filename>/usr/lib/os-release</filename> (if the
+                former is missing), or "Linux <replaceable>KERNEL-VERSION</replaceable>", if unset.</para>
+
+                <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "bls", this plugin does nothing.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><filename>90-uki-copy.install</filename></term>
+              <listitem>
+                <para>If <varname>$KERNEL_INSTALL_STAGING_AREA/uki.efi</varname> exists, the plugin copies it
+                to
+                <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi</filename>.
+                Also, files in <filename>$KERNEL_INSTALL_STAGING_AREA/uki.efi.extra.d"/</filename> are copied
+                to
+                <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi.extra.d/</filename>.</para>
+
+                <para>If <varname>$KERNEL_INSTALL_STAGING_AREA/uki.efi</varname> does not exist, and the
+                <replaceable>KERNEL-IMAGE</replaceable> argument has a <literal>.efi</literal> extension, the
+                plugin copies the image to
+                <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi</filename>.
+                Also, files in <filename><replaceable>KERNEL-IMAGE</replaceable>.extra.d/</filename> and
+                <filename>$KERNEL_INSTALL_STAGING_AREA/uki.efi.extra.d"/</filename> are copied to
+                <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi.extra.d/</filename>.</para>
+
+                <para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "uki", this plugin does nothing.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
 
-            <xi:include href="version-info.xml" xpointer="v198"/>
+          <xi:include href="version-info.xml" xpointer="v198"/>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -185,22 +207,37 @@
           <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL-VERSION</replaceable>/</filename>
           and its contents, if it exists.</para>
 
-          <para>Two default plugins execute the following operations in this case:</para>
-
-          <itemizedlist>
-            <listitem><para><filename>50-depmod.install</filename> removes the files generated by
-            <command>depmod</command> for this kernel again.</para></listitem>
-
-            <listitem><para><filename>90-loaderentry.install</filename> removes the file
-            <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
-            </para></listitem>
+          <para>Three default plugins execute the following operations in this case:</para>
+
+          <variablelist>
+            <varlistentry>
+              <term><filename>50-depmod.install</filename></term>
+              <listitem>
+                <para>The plugin removes the files generated by <command>depmod</command> for this kernel again.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><filename>90-loaderentry.install</filename></term>
+              <listitem>
+                <para>The plugin removes the file
+                <filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
+                </para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term><filename>90-uki-copy.install</filename></term>
+              <listitem>
+                <para>The plugin removes the file
+                <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi</filename> and
+                <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi.extra.d/</filename>
+                directory including its contents.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
 
-            <listitem><para><filename>90-uki-copy.install</filename> removes the file
-            <filename>$BOOT/EFI/Linux/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.efi</filename>.
-            </para></listitem>
-          </itemizedlist>
-
-            <xi:include href="version-info.xml" xpointer="v198"/>
+          <xi:include href="version-info.xml" xpointer="v198"/>
         </listitem>
       </varlistentry>
       <varlistentry>
diff --git a/tools/command_ignorelist b/tools/command_ignorelist
index d868c55b15e..aca6b8c93bd 100644
--- a/tools/command_ignorelist
+++ b/tools/command_ignorelist
@@ -14,6 +14,12 @@ journald.conf.xml /refsect1[title="Options"]/variablelist/varlistentry[term="Com
 journald.conf.xml /refsect1[title="Options"]/variablelist/varlistentry[term="RateLimitIntervalSec="]
 journald.conf.xml /refsect1[title="Options"]/variablelist/varlistentry[term="SystemMaxUse="]
 journald.conf.xml /refsect1[title="Options"]/variablelist/varlistentry[term="ForwardToSyslog="]
+kernel-install.xml /refsect1[title="Commands"]/variablelist/varlistentry[term="add [[[KERNEL-VERSION] KERNEL-IMAGE] [INITRD-FILE ...]]"]/listitem/variablelist/varlistentry[term="50-depmod.install"]
+kernel-install.xml /refsect1[title="Commands"]/variablelist/varlistentry[term="add [[[KERNEL-VERSION] KERNEL-IMAGE] [INITRD-FILE ...]]"]/listitem/variablelist/varlistentry[term="90-loaderentry.install"]
+kernel-install.xml /refsect1[title="Commands"]/variablelist/varlistentry[term="add [[[KERNEL-VERSION] KERNEL-IMAGE] [INITRD-FILE ...]]"]/listitem/variablelist/varlistentry[term="90-uki-copy.install"]
+kernel-install.xml /refsect1[title="Commands"]/variablelist/varlistentry[term="remove KERNEL-VERSION"]/listitem/variablelist/varlistentry[term="50-depmod.install"]
+kernel-install.xml /refsect1[title="Commands"]/variablelist/varlistentry[term="remove KERNEL-VERSION"]/listitem/variablelist/varlistentry[term="90-loaderentry.install"]
+kernel-install.xml /refsect1[title="Commands"]/variablelist/varlistentry[term="remove KERNEL-VERSION"]/listitem/variablelist/varlistentry[term="90-uki-copy.install"]
 loginctl.xml /refsect1[title="Options"]/variablelist/varlistentry[term="-p"]
 loginctl.xml /refsect1[title="Options"]/variablelist/varlistentry[term="-a"]
 loginctl.xml /refsect1[title="Options"]/variablelist/varlistentry[term="--no-ask-password"]
-- 
2.47.3