bug#26339: [PATCH] doc: Adapt to multiple bootloader support.

[Mathieu Othacehe]

* doc/guix.texi (GRUB configuration): Rename to "Bootloader
  configuration".
  [menu-entry]: Switch to "boot-parameters" and adapt fields.
  Adapt occurences of "GRUB" in other sections.
---

Hi,

Here's the doc patch. While writting it, I noticed that using
<boot-parameters> for <bootloader-configuration>'s menu-entry fields
was maybe not a good idea.

<boot-parameters> has no default values and it might be hard to understand
by final users. WDYT ?

Thanks,

Mathieu

 doc/guix.texi | 208 +++++++++++++++++++++++++++++++++-------------------------
 1 file changed, 118 insertions(+), 90 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 7baf6ee38..455dbbc84 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -198,7 +198,7 @@ System Configuration
 * X.509 Certificates::          Authenticating HTTPS servers.
 * Name Service Switch::         Configuring libc's name service switch.
 * Initial RAM Disk::            Linux-Libre bootstrapping.
-* GRUB Configuration::          Configuring the boot loader.
+* Bootloader Configuration::    Configuring the boot loader.
 * Invoking guix system::        Instantiating a system configuration.
 * Running GuixSD in a VM::      How to run GuixSD in a virtual machine.
 * Defining Services::           Adding new service definitions.
@@ -7731,7 +7731,7 @@ instance to support new system services.
 * X.509 Certificates::          Authenticating HTTPS servers.
 * Name Service Switch::         Configuring libc's name service switch.
 * Initial RAM Disk::            Linux-Libre bootstrapping.
-* GRUB Configuration::          Configuring the boot loader.
+* Bootloader Configuration::    Configuring the boot loader.
 * Invoking guix system::        Instantiating a system configuration.
 * Running GuixSD in a VM::      How to run GuixSD in a virtual machine.
 * Defining Services::           Adding new service definitions.
@@ -7914,7 +7914,7 @@ system, should you ever need to.
 Speaking of roll-back, each time you run @command{guix system
 reconfigure}, a new @dfn{generation} of the system is created---without
 modifying or deleting previous generations.  Old system generations get
-an entry in the GRUB boot menu, allowing you to boot them in case
+an entry in the bootloader boot menu, allowing you to boot them in case
 something went wrong with the latest generation.  Reassuring, no?  The
 @command{guix system list-generations} command lists the system
 generations available on disk.  It is also possible to roll back the
@@ -7970,7 +7970,7 @@ List of strings or gexps representing additional 
arguments to pass on
 the command-line of the kernel---e.g., @code{("console=ttyS0")}.
 
 @item @code{bootloader}
-The system bootloader configuration object.  @xref{GRUB Configuration}.
+The system bootloader configuration object.  @xref{Bootloader Configuration}.
 
 @item @code{initrd} (default: @code{base-initrd})
 @cindex initrd
@@ -15229,32 +15229,41 @@ upon booting.  All the derivations referenced by 
@var{exp} are
 automatically copied to the initrd.
 @end deffn
 
address@hidden GRUB Configuration
address@hidden GRUB Configuration
address@hidden Bootloader Configuration
address@hidden Bootloader Configuration
 
address@hidden GRUB
address@hidden Bootloader
 @cindex boot loader
 
-The operating system uses address@hidden as its boot loader
-(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}).  It is
-configured using a @code{grub-configuration} declaration.  This data type
-is exported by the @code{(gnu system grub)} module and described below.
+The operating system supports multiple bootloaders. The bootloader is
+configured using @code{bootloader-configuration} declaration. All the
+fields of this structure are bootloader agnostic except for one field,
address@hidden that indicates the bootloader to be configured and
+installed.
 
address@hidden {Data Type} grub-configuration
-The type of a GRUB configuration declaration.
+Note that all fields of @code{bootloader-configuration} are not
+necessarily handled by all GuixSD supported bootloaders.
+
address@hidden {Data Type} bootloader-configuration
+The type of a bootloader configuration declaration.
 
 @table @asis
 
address@hidden @code{bootloader}
+The bootloader to use, as a @code{bootloader} object. For now
address@hidden, @code{grub-efi} and @code{syslinux} are supported.
+
 @item @code{device}
 This is a string denoting the boot device.  It must be a device name
-understood by the @command{grub-install} command, such as
address@hidden/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
+understood by the bootloader @command{installer} command, such as
address@hidden/dev/sda} or @code{(hd0)} (for GRUB, @pxref{Invoking 
grub-install,,, grub,
 GNU GRUB Manual}).
 
 @item @code{menu-entries} (default: @code{()})
-A possibly empty list of @code{menu-entry} objects (see below), denoting
-entries to appear in the GRUB boot menu, in addition to the current
-system entry and the entry pointing to previous system generations.
+A possibly empty list of @code{boot-parameters} objects (see below),
+denoting entries to appear in the bootloader menu, in addition to the
+current system entry and the entry pointing to previous system
+generations.
 
 @item @code{default-entry} (default: @code{0})
 The index of the default boot menu entry.  Index 0 is for the entry of the
@@ -15264,37 +15273,37 @@ current system.
 The number of seconds to wait for keyboard input before booting.  Set to
 0 to boot immediately, and to -1 to wait indefinitely.
 
address@hidden @code{theme} (default: @var{%default-theme})
-The @code{grub-theme} object describing the theme to use.
-
address@hidden @code{grub} (default: @code{grub})
-The GRUB package to use.
address@hidden @code{theme} (default: @var{#f})
+The bootloader theme object describing the theme to use. If no theme
+is provided, some bootloaders might use a default theme, that's true
+for GRUB.
 
 @item @code{terminal-outputs} (default: @code{'gfxterm})
-The output terminals used for the GRUB boot menu, as a list of symbols.
-These values are accepted: @code{console}, @code{serial},
address@hidden@address@hidden, @code{gfxterm}, @code{vga_text}, @code{mda_text},
address@hidden, and @code{pkmodem}.  This field corresponds to the GRUB
-variable GRUB_TERMINAL_OUTPUT (@pxref{Simple configuration,,, grub,GNU
-GRUB manual}).
+The output terminals used for the bootloader boot menu, as a list of
+symbols.  GRUB accepts the values: @code{console}, @code{serial},
address@hidden@address@hidden, @code{gfxterm}, @code{vga_text},
address@hidden, @code{morse}, and @code{pkmodem}.  This field
+corresponds to the GRUB variable GRUB_TERMINAL_OUTPUT (@pxref{Simple
+configuration,,, grub,GNU GRUB manual}).
 
 @item @code{terminal-inputs} (default: @code{'()})
-The input terminals used for the GRUB boot menu, as a list of symbols.
-The default is the native platform terminal as determined by GRUB at
-run-time.  These values are accepted: @code{console}, @code{serial},
address@hidden@address@hidden, @code{at_keyboard}, and @code{usb_keyboard}.
-This field corresponds to the GRUB variable GRUB_TERMINAL_INPUT
-(@pxref{Simple configuration,,, grub,GNU GRUB manual}).
+The input terminals used for the bootloader boot menu, as a list of
+symbols.  For GRUB, the default is the native platform terminal as
+determined at run-time.  GRUB accepts the values: @code{console},
address@hidden, @address@hidden@}}, @code{at_keyboard}, and
address@hidden  This field corresponds to the GRUB variable
+GRUB_TERMINAL_INPUT (@pxref{Simple configuration,,, grub,GNU GRUB
+manual}).
 
 @item @code{serial-unit} (default: @code{#f})
-The serial unit used by GRUB, as an integer from 0 to 3.  The default
-value is chosen by GRUB at run-time; currently GRUB chooses 0, which
+The serial unit used by the bootloader, as an integer from 0 to 3.
+For GRUB it is choosen at run-time; currently GRUB chooses 0, which
 corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
 
 @item @code{serial-speed} (default: @code{#f})
-The speed of the serial interface, as an integer.  The default value is
-chosen by GRUB at run-time; currently GRUB chooses address@hidden
-(@pxref{Serial terminal,,, grub,GNU GRUB manual}).
+The speed of the serial interface, as an integer.  For GRUB, the
+default value is chosen at run-time; currently GRUB chooses
address@hidden (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
 @end table
 
 @end deftp
@@ -15303,38 +15312,68 @@ chosen by GRUB at run-time; currently GRUB chooses 
address@hidden
 @cindex boot menu
 Should you want to list additional boot menu entries @i{via} the
 @code{menu-entries} field above, you will need to create them with the
address@hidden form.  For example, imagine you want to be able to
address@hidden form.  For example, imagine you want to be able to
 boot another distro (hard to imagine!), you can define a menu entry
 along these lines:
 
 @example
-(menu-entry
+(boot-parameters
   (label "The Other Distro")
-  (linux "/boot/old/vmlinux-2.6.32")
-  (linux-arguments '("root=/dev/sda2"))
+  (root-device "my-root")
+  (boot-name 'grub)
+  (store-device "my-root")
+  (store-mount-point "/")
+  (kernel "/boot/old/vmlinux-2.6.32")
+  (kernel-arguments '("root=/dev/sda2"))
   (initrd "/boot/old/initrd"))
 @end example
 
 Details below.
 
address@hidden {Data Type} menu-entry
-The type of an entry in the GRUB boot menu.
address@hidden {Data Type} boot-parameters
+The type of an entry in the bootloader boot menu.
 
 @table @asis
 
 @item @code{label}
 The label to show in the menu---e.g., @code{"GNU"}.
 
address@hidden @code{linux}
-The Linux kernel image to boot, for example:
address@hidden @code{root-device}
+The root device identifier. It has to correspond exactly to the device
+field of the <file-system> object representing the OS's root file
+system, so it might be a device path like @code{"/dev/sda3"}.
+
address@hidden @code{boot-device}
+The name of the bootloader used to boot this entry (@code{'grub} or
address@hidden'syslinux} for instance).
+
address@hidden @code{store-device}
+The device where the kernel and initrd are to be found---i.e., for GRUB
address@hidden for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
+
+Depending on the bootloader, this may be a file system label (a
+string), a file system UUID (a bytevector, @pxref{File Systems}), or
address@hidden If set to @code{#f}, GRUB will search the device containing
+the file specified by the @code{linux} field (@pxref{search,,, grub,
+GNU GRUB manual}).  It must @emph{not} be an OS device name such as
address@hidden/dev/sda1}.
+
address@hidden @code{store-mount-point}
+The mount point of the above device on the system.  You probably want
+to set it to @code{"/"}.  GuixSD uses it to strip the prefix of store
+file names for systems where @file{/gnu} or @file{/gnu/store} is on a
+separate partition.
+
address@hidden @code{kernel}
+The kernel image to boot, for example:
 
 @example
 (file-append linux-libre "/bzImage")
 @end example
 
-It is also possible to specify a device explicitly in the file path
-using GRUB's device naming convention (@pxref{Naming convention,,, grub,
-GNU GRUB manual}), for example:
+For GRUB, It is also possible to specify a device explicitly in the
+file path using GRUB's device naming convention (@pxref{Naming
+convention,,, grub, GNU GRUB manual}), for example:
 
 @example
 "(hd0,msdos1)/boot/vmlinuz"
@@ -15343,40 +15382,27 @@ GNU GRUB manual}), for example:
 If the device is specified explicitly as above, then the @code{device}
 field is ignored entirely.
 
address@hidden @code{linux-arguments} (default: @code{()})
-The list of extra Linux kernel command-line arguments---e.g.,
address@hidden @code{kernel-arguments}
+The list of extra kernel command-line arguments---e.g.,
 @code{("console=ttyS0")}.
 
 @item @code{initrd}
 A G-Expression or string denoting the file name of the initial RAM disk
 to use (@pxref{G-Expressions}).
-
address@hidden @code{device} (default: @code{#f})
-The device where the kernel and initrd are to be found---i.e., the GRUB
address@hidden for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
-
-This may be a file system label (a string), a file system UUID (a
-bytevector, @pxref{File Systems}), or @code{#f}, in which case GRUB will
-search the device containing the file specified by the @code{linux}
-field (@pxref{search,,, grub, GNU GRUB manual}).  It must @emph{not} be
-an OS device name such as @file{/dev/sda1}.
-
address@hidden @code{device-mount-point} (default: @code{"/"})
-The mount point of the above device on the system.  You probably do not
-need to change the default value.  GuixSD uses it to strip the prefix of
-store file names for systems where @file{/gnu} or @file{/gnu/store} is
-on a separate partition.
-
 @end table
 @end deftp
 
 @c FIXME: Write documentation once it's stable.
-Themes are created using the @code{grub-theme} form, which is not
-documented yet.
+Fow now only GRUB has theme support. GRUB Themes are created using
+the @code{grub-theme} form, which is not documented yet.
 
 @defvr {Scheme Variable} %default-theme
-This is the default GRUB theme used by the operating system, with a
-fancy background image displaying the GNU and Guix logos.
+This is the default GRUB theme used by the operating system if no
address@hidden field is specified in @code{bootloader-configuration}
+record.
+
+It comes with a fancy background image displaying the GNU and Guix
+logos.
 @end defvr
 
 
@@ -15416,9 +15442,9 @@ list-generations}).  If that generation already exists, 
it will be
 overwritten.  This behavior mirrors that of @command{guix package}
 (@pxref{Invoking guix package}).
 
-It also adds a GRUB menu entry for the new OS configuration, and moves
-entries for older configurations to a submenu---unless
address@hidden is passed.
+It also adds a bootloader menu entry for the new OS configuration,
+---unless @option{--no-bootloader} is passed.  For GRUB, it moves
+entries for older configurations to a submenu.
 
 @quotation Note
 @c The paragraph below refers to the problem discussed at
@@ -15432,11 +15458,12 @@ once @command{reconfigure} has completed.
 @item switch-generation
 @cindex generations
 Switch to an existing system generation.  This action atomically
-switches the system profile to the specified system generation.  It also
-rearranges the system's existing GRUB menu entries.  It makes the menu
-entry for the specified system generation the default, and it moves the
-entries for the other generations to a submenu.  The next time the
-system boots, it will use the specified system generation.
+switches the system profile to the specified system generation.  It
+also rearranges the system's existing bootloader menu entries.  It
+makes the menu entry for the specified system generation the default,
+and it moves the entries for the other generations to a submenu.  The
+next time the system boots, it will use the specified system
+generation.
 
 The target generation can be specified explicitly by its generation
 number.  For example, the following invocation would switch to system
@@ -15458,11 +15485,11 @@ guix system switch-generation -- -1
 @end example
 
 Currently, the effect of invoking this action is @emph{only} to switch
-the system profile to an existing generation and rearrange the GRUB menu
-entries.  To actually start using the target system generation, you must
-reboot after running this action.  In the future, it will be updated to
-do the same things as @command{reconfigure}, like activating and
-deactivating services.
+the system profile to an existing generation and rearrange the
+bootloader menu entries.  To actually start using the target system
+generation, you must reboot after running this action.  In the future,
+it will be updated to do the same things as @command{reconfigure},
+like activating and deactivating services.
 
 This action will fail if the specified generation does not exist.
 
@@ -15497,8 +15524,9 @@ files, packages, and so on.  It also creates other 
essential files
 needed for the system to operate correctly---e.g., the @file{/etc},
 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
 
-This command also installs GRUB on the device specified in
address@hidden, unless the @option{--no-bootloader} option was passed.
+This command also installs bootloader on the device specified in
address@hidden, unless the @option{--no-bootloader} option was
+passed.
 
 @item vm
 @cindex virtual machine
@@ -15638,7 +15666,7 @@ build users of the daemon (@pxref{Build Environment 
Setup}).
 Once you have built, configured, re-configured, and re-re-configured
 your GuixSD installation, you may find it useful to list the operating
 system generations available on disk---and that you can choose from the
-GRUB boot menu:
+bootloader boot menu:
 
 @table @code
 
-- 
2.13.0