Re: [PATCH] Clarify documentation for special environment variable "default"

[Andrei Borzenkov]

03.02.2017 03:19, 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 (e.g. does it start at 1
> or at 0?).
> 
> Having a cleaner example and presenting both the numeric version and
> the title version will make it clearer.
> 
> In my patch here i've tried to make it clear and understandable.  I've
> also assumed that the number counting starts at 1, but haven't
> verified that.  If that's wrong, please commit the corrected version
> :)

Menu items count start with 0 in every submenu. We really need some
place with overall description of what happens when grub starts (akin to
bootup(7) in systemd). But at least example needs to be correct in this
case.

> 
> Signed-off-by: Daniel Kahn Gillmor <address@hidden>
> ---
>  docs/grub.texi | 20 ++++++++++----------
>  1 file changed, 10 insertions(+), 10 deletions(-)
> 
> diff --git a/docs/grub.texi b/docs/grub.texi
> index b9ddb9b8a..e868f045d 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
> @@ -3242,18 +3242,18 @@ title of the menu entry itself, 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
> +  Standard Boot
> +  Rescue shell
> +Other platforms
> +  Minix
> +    Version 3.4.0
> +    Version 3.3.0
> +  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{2>1>1}.
>  

Note that preceding paragraph says "using the titles of each of the
submenus" which is already not complete and does not agree with your
second example. Could you extend it?

>  This variable is often set by @samp{GRUB_DEFAULT} (@pxref{Simple
>  configuration}), @command{grub-set-default}, or @command{grub-reboot}.
> 

Preferred way to identify menu entry is to use menu ID (--id option).
This is mentioned in preceding paragraph, but not for submenus. Could
you modify your patch to mention this and give example as well. Also at
the very beginning it says "entry may be identified by number or by id"
missing "by title"; would be good to fix as long as you are on it.