[PATCH 10/10] Mention new 'guix system' features in the manual

[cmmarusich]

From: Chris Marusich <address@hidden>

* doc/guix.texi (GRUB Configuration, Invoking guix system): Mention the new
  <menu-entry> field 'device', update the custom <menu-entry> example, and
  mention the new actions 'guix system roll-back' and 'guix system
  switch-generation' in the manual.

* gnu/system/grub.scm (strip-mount-point): Add a TODO comment.

* guix/scripts/system.scm (show-help): Point users to the manual for details.
---
 doc/guix.texi           | 90 +++++++++++++++++++++++++++++++++++++++++++------
 gnu/system/grub.scm     |  4 +++
 guix/scripts/system.scm |  2 +-
 3 files changed, 85 insertions(+), 11 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 1293b8b..26fb930 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -11064,35 +11064,66 @@ along these lines:
 @example
 (menu-entry
   (label "The Other Distro")
-  (linux "/boot/old/vmlinux-2.6.32")
+  (device #f)
+  (linux "(hd0,msdos2)/boot/old/vmlinux-2.6.32")
   (linux-arguments '("root=/dev/sda2"))
-  (initrd "/boot/old/initrd"))
+  (initrd "(hd0,msdos2)/boot/old/initrd"))
 @end example
 
 Details below.
 
 @deftp {Data Type} menu-entry
-The type of an entry in the GRUB boot menu.
+The type of an entry in the GRUB boot menu.  Below, the phrase
+``string-valued G-Expression'' means a string or any object which can be
+inserted (via @code{ungexp}) as a string in a G-Expression
+(@pxref{G-Expressions}).
 
 @table @asis
 
 @item @code{label}
-The label to show in the menu---e.g., @code{"GNU"}.
+The label to show in the menu---e.g., @code{"GNU"}.  This is a string-valued 
G-Expression.
 
 @item @code{linux}
-The Linux kernel image to boot, for example:
+The Linux kernel image to boot.  This is a string-valued G-Expression.
+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:
+
address@hidden
+"(hd0,msdos1)/bzImage"
address@hidden example
+
+If the device is specified explicitly as above, then the @code{device}
+field is ignored entirely.
+
address@hidden @code{device}
+The device to use as GRUB's root for this menu entry (@pxref{root,,,
+grub, GNU GRUB manual}).  This may be a file system label (a string), a
+file system UUID (@pxref{File Systems}), or @code{#f}, in which case
+GRUB will automatically find the device containing the file specified by
+the @code{linux} field via a file-based search (@pxref{search,,, grub,
+GNU GRUB manual}).
+
address@hidden For details, see (guix gnu system).
+Currently, the @code{device} field is not suitable for use in custom
+menu entries.  Therefore, if you need to specify a custom menu entry,
+for now it is best to just pass a dummy value to it (such as @code{#f})
+and specify the device explicitly using GRUB's device naming convention,
+as in the example above.
+
 @item @code{linux-arguments} (default: @code{()})
 The list of extra Linux kernel command-line arguments---e.g.,
address@hidden("console=ttyS0")}.
address@hidden("console=ttyS0")}.  This is a list of string-valued
+G-Expressions.
 
 @item @code{initrd}
-A G-Expression or string denoting the file name of the initial RAM disk
-to use (@pxref{G-Expressions}).
+The initial RAM disk file to use.  This is a string-valued G-Expression.
 
 @end table
 @end deftp
@@ -11126,8 +11157,9 @@ supported:
 @table @code
 @item reconfigure
 Build the operating system described in @var{file}, activate it, and
-switch to address@hidden action is usable only on systems already
-running GuixSD.}.
+switch to address@hidden action and the related actions
address@hidden and @code{roll-back}) are usable only on
+systems already running GuixSD.}.
 
 This effects all the configuration specified in @var{file}: user
 accounts, system services, global package list, setuid programs, etc.
@@ -11149,6 +11181,44 @@ guix pull}).  Failing to do that you would see an 
older version of Guix
 once @command{reconfigure} has completed.
 @end quotation
 
address@hidden switch-generation
+Switch to an existing system generation.  This action rearranges the
+existing GRUB menu entries.  It makes the menu entry for the target
+system generation the default, and it moves the entries for the other
+system 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
+generation 7:
+
address@hidden
+guix system switch-generation 7
address@hidden example
+
+The target generation can also be specified relative to the current
+generation with the form @code{+N} or @code{-N}, where @code{+3} means
+``3 generations ahead of the current generation,'' and @code{-1} means
+``1 generation prior to the current generation.''
+
+Currently, the effect of invoking this action is only to rearrange the
+GRUB menu entries.  Therefore, 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.
+
address@hidden roll-back
+Switch to the preceding system generation.  The next time the system
+boots, it will use the preceding system generation.  This is the inverse
+of @command{reconfigure}, and it is exactly the same as invoking
address@hidden -1}.
+
+Currently, as with @command{switch-system}, you must reboot after
+running this action to actually start using the preceding system
+generation.
+
 @item build
 Build the derivation of the operating system, which includes all the
 configuration files and programs needed to boot and run the system.
diff --git a/gnu/system/grub.scm b/gnu/system/grub.scm
index d45fdca..5b520ca 100644
--- a/gnu/system/grub.scm
+++ b/gnu/system/grub.scm
@@ -65,6 +65,10 @@
 (define (strip-mount-point mount-point file)
   "Strip MOUNT-POINT from FILE, which is a gexp or other lowerable
 object denoting a file name."
+  ;; TODO: gracefully handle the case where the file resides in a location
+  ;; outside of the store, for example "/home/alice/vmlinuz".  Currently, any
+  ;; attempt to create a custom <menu-entry> with a 'linux' field set to
+  ;; something like that will likely result in an un-bootable GRUB entry.
   (if (string=? mount-point "/")
       file
       #~(let ((file #$file))
diff --git a/guix/scripts/system.scm b/guix/scripts/system.scm
index 2ee145a..54c6eeb 100644
--- a/guix/scripts/system.scm
+++ b/guix/scripts/system.scm
@@ -704,7 +704,7 @@ building anything."
 (define (show-help)
   (display (_ "Usage: guix system [OPTION ...] ACTION [ARG ...] [FILE]
 Build the operating system declared in FILE according to ACTION.
-Some ACTIONS support additional ARGS.\n"))
+Some ACTIONS support additional ARGS.  See 'info guix' for details.\n"))
   (newline)
   (display (_ "The valid values for ACTION are:\n"))
   (newline)
-- 
2.9.2