[PATCH v3] docs: Improve initrd documentation

[Glenn Washburn <development@efficientek.com>]

A list of improvements:
 * Remove reference to "initial ramdisk" and replace with "initrd". This
   then covers the case of ramdisk and ramfs, which is the usual method
   with kernels 2.6 and newer.
 * Add sentence with URL to initrd documentation Linux kernel.
 * Add a section documenting how to have the initrd command generate a
   new-style initrd via a specially crafted argument and include an example.
 * Update initrd16 to refer to the initrd section and make note that
   initrd16 is only on the pc platform.

Signed-off-by: Glenn Washburn <development@efficientek.com>
Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
Reviewed-by: Paul Menzel <pmenzel@molgen.mpg.de>
---
Range-diff against v2:
1:  28cda0c394d6 ! 1:  d6ca60159b40 docs: Improve initrd documentation
    @@ Metadata
      ## Commit message ##
         docs: Improve initrd documentation
     
    -    Remove reference to "initial ramdisk" and replace with "initrd". This then
    -    covers the case of ramdisk and ramfs, which is the usual method with kernels
    -    2.6 and greater. Add sentence with URL to initrd documentation Linux kernel.
    -    Also, add a section documenting how to have the initrd command generate a
    -    new-style initrd via a specially crafted argument and include an example.
    +    A list of improvements:
    +     * Remove reference to "initial ramdisk" and replace with "initrd". This
    +       then covers the case of ramdisk and ramfs, which is the usual method
    +       with kernels 2.6 and newer.
    +     * Add sentence with URL to initrd documentation Linux kernel.
    +     * Add a section documenting how to have the initrd command generate a
    +       new-style initrd via a specially crafted argument and include an example.
    +     * Update initrd16 to refer to the initrd section and make note that
    +       initrd16 is only on the pc platform.
     
    -    Update initrd16 to refer to the initrd section and make note that initrd16
    -    is only on the pc platform.
    +    Signed-off-by: Glenn Washburn <development@efficientek.com>
    +    Reviewed-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
    +    Reviewed-by: Paul Menzel <pmenzel@molgen.mpg.de>
     
      ## docs/grub.texi ##
     @@ docs/grub.texi: load a defective boot loader, such as SCO UnixWare 7.1.
    @@ docs/grub.texi: load a defective boot loader, such as SCO UnixWare 7.1.
     +See @ref{GNU/Linux} for more info on booting GNU/Linux.  For more
     +information on initrds see the GNU/Linux kernel
     +@uref{https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html,
    -+documentation} on them.
    ++documentation}.
     +
     +A new-style initrd (for kernels newer than 2.6) containing one file
     +with leading path components can also be generated at run time. This
    @@ docs/grub.texi: load a defective boot loader, such as SCO UnixWare 7.1.
     +in the path @samp{/init} and appended to the previous concatenation. Finally,
     +the result will be sent to the kernel when booted.
     +
    -+Keep in mind that paths that comes later will take precendence. So in the
    ++Keep in mind that paths that come later will take precedence. So in the
     +example above, the generated path @samp{/init} will overwrite any @samp{/init}
     +in @samp{/boot/initrd.gz}. This can be useful when changing the main initrd
     +is undesirable or difficult.

 docs/grub.texi | 48 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index 730e8c8d75a4..1d2f0a3d04fe 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -4076,10 +4076,43 @@ load a defective boot loader, such as SCO UnixWare 7.1.
 @subsection initrd
 
 @deffn Command initrd file [file @dots{}]
-Load, in order, all initial ramdisks for a Linux kernel image, and set
-the appropriate parameters in the Linux setup area in memory.  This may only
-be used after the @command{linux} command (@pxref{linux}) has been run.  See
-also @ref{GNU/Linux}.
+Load, in order, all initrds for a Linux kernel image, and set the
+appropriate parameters in the Linux setup area in memory.  This may only
+be used after the @command{linux} command (@pxref{linux}) has been run.
+See @ref{GNU/Linux} for more info on booting GNU/Linux.  For more
+information on initrds see the GNU/Linux kernel
+@uref{https://docs.kernel.org/filesystems/ramfs-rootfs-initramfs.html,
+documentation}.
+
+A new-style initrd (for kernels newer than 2.6) containing one file
+with leading path components can also be generated at run time. This
+can be done by prefixing an argument with @code{newc:} followed by the
+path of the file in the new initrd, a @code{:}, and then the GRUB file
+path to the file data to be be included.
+
+For example:
+@example
+initrd newc:/etc/ssh/config:(hd0,2)/home/user/.ssh/config \
+       newc:/etc/ssh/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
+       /boot/initrd.gz \
+       newc:/init:/home/user/init.fixed
+@end example
+
+This command will generate two new-style initrds on the fly. The first
+contains the path @samp{/etc/ssh/config} with the contents of
+@samp{(hd0,2)/home/user/.ssh/config} and the path
+@samp{/etc/ssh/ssh_host_rsa_key} with the contents of
+@samp{/etc/ssh/ssh_host_rsa_key} on the @var{root} device. Parent directory
+paths will automatically be generated as needed. This first generated initrd
+will then have @samp{/boot/initrd.gz} concatenated after it. Next, another
+new-style archive will be generated with the contents of @samp{/home/user/init.fixed}
+in the path @samp{/init} and appended to the previous concatenation. Finally,
+the result will be sent to the kernel when booted.
+
+Keep in mind that paths that come later will take precedence. So in the
+example above, the generated path @samp{/init} will overwrite any @samp{/init}
+in @samp{/boot/initrd.gz}. This can be useful when changing the main initrd
+is undesirable or difficult.
 @end deffn
 
 
@@ -4087,12 +4120,13 @@ also @ref{GNU/Linux}.
 @subsection initrd16
 
 @deffn Command initrd16 file [file @dots{}]
-Load, in order, all initial ramdisks for a Linux kernel image to be booted in
+Load, in order, all initrds for a Linux kernel image to be booted in
 16-bit mode, and set the appropriate parameters in the Linux setup area in
 memory.  This may only be used after the @command{linux16} command
-(@pxref{linux16}) has been run.  See also @ref{GNU/Linux}.
+(@pxref{linux16}) has been run.  See also @ref{GNU/Linux} and the @command{initrd}
+command (@pxref{initrd}) for more details on arguments.
 
-This command is only available on x86 systems.
+This command is only available on the pc platform for x86 systems.
 @end deffn
 
 
-- 
2.34.1