[PATCH v2] Clarify documentation for special environment variable "default"

[Daniel Kahn Gillmor]

The current documentation for the special environment variable
"default" is confusing and unclear.  This patch attempts to clean it
up.

In particular, the current documentation refers to the "number or
title", but then in the example it gives, the menu entries and
submenus all have numbers *in* their title; furthermore, there is no
example given about how to choose the number, or any indication about
whether counting is zero-indexed or 1-indexed.

Having a cleaner example and presenting all variants (numeric, title,
and id) should make it clearer to the user.

Signed-off-by: Daniel Kahn Gillmor <address@hidden>
---
 docs/grub.texi | 37 ++++++++++++++++++++-----------------
 1 file changed, 20 insertions(+), 17 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index b9ddb9b8a..e935af33e 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -3218,9 +3218,10 @@ source for more details.
 @node default
 @subsection default
 
-If this variable is set, it identifies a menu entry that should be selected
-by default, possibly after a timeout (@pxref{timeout}).  The entry may be
-identified by number or by id.
+If this variable is set, it identifies a menu entry that should be
+selected by default, possibly after a timeout (@pxref{timeout}).  The
+entry may be identified by number (starting from 0 at each level of
+the hierarchy), by title, or by id.
 
 For example, if you have:
 
@@ -3236,24 +3237,26 @@ then you can make this the default using:
 default=example-gnu-linux
 @end example
 
-If the entry is in a submenu, then it must be identified using the titles of
-each of the submenus starting from the top level followed by the number or
-title of the menu entry itself, separated by @samp{>}.  For example, take
-the following menu structure:
+If the entry is in a submenu, then it must be identified using the
+number, title, or id of each of the submenus starting from the top
+level, followed by the number, title, or id of the menu entry itself,
+with each element separated by @samp{>}.  For example, take the
+following menu structure:
 
 @example
-Submenu 1
-  Menu Entry 1
-  Menu Entry 2
-Submenu 2
-  Submenu 3
-    Menu Entry 3
-    Menu Entry 4
-  Menu Entry 5
+GNU/Hurd --id gnu-hurd
+  Standard Boot --id=gnu-hurd-std
+  Rescue shell --id=gnu-hurd-rescue
+Other platforms --id=other
+  Minix --id=minix
+    Version 3.4.0 --id=minix-3.4.0
+    Version 3.3.0 --id=minix-3.3.0
+  GRUB Invaders --id=grub-invaders
 @end example
 
-``Menu Entry 3'' would then be identified as
address@hidden 2>Submenu 3>Menu Entry 3}.
+The more recent release of Minix would then be identified as
address@hidden platforms>Minix>Version 3.4.0}, or as @samp{1>0>0}, or as
address@hidden>minix>minix-3.4.0}.
 
 This variable is often set by @samp{GRUB_DEFAULT} (@pxref{Simple
 configuration}), @command{grub-set-default}, or @command{grub-reboot}.
-- 
2.11.0