Re: [PATCH] Document menuentry --id option

[Andrey Borzenkov]

В Mon, 21 Jan 2013 20:48:51 +0100
Vladimir 'φ-coder/phcoder' Serbinenko <address@hidden> пишет:

> On 21.01.2013 15:44, Andrey Borzenkov wrote:
> 
> > В Sun, 20 Jan 2013 23:51:46 +0100
> > Vladimir 'φ-coder/phcoder' Serbinenko <address@hidden> пишет:
> > 
> >>>  @deffn Command menuentry @var{title} @
> >>>   address@hidden @dots{}] address@hidden @
> >>> - address@hidden address@hidden @
> >>> + address@hidden address@hidden address@hidden @
> >>>   @{ @var{command}; @dots{} @}
> >>>  This defines a GRUB menu entry named @var{title}.  When this entry is
> >>>  selected from the menu, GRUB will set the @var{chosen} environment 
> >>> variable
> >>> -to @var{title}, execute the list of commands given within braces, and if 
> >>> the
> >>> +to value of @option{--id} or @var{title} if @option{--id} is not given,
> >>> +execute the list of commands given within braces, and if the
> >>
> >> It's better to not mention the possible usage of title for this at all.
> >> Ehile it's kept for backward compatibility it has problems when language
> >> or disk name changes and hence discouraged.
> >>
> > 
> > I understand that, but you still need to explain what happens when --id
> > is not given. Or make it mandatory argument.
> 
> Such an entry would be considered as not identifiable other than by its
> number. The only reason why it's not so is because of backward
> compatibility.
> Documentation isn't just a description of the code but certain
> committment to what is considered right and supported. If user relies on
> something intentionally undocumented and gets bitten by it he has only
> himself to blame while if he does something according to doc it will be
> another case of figure.
> 
> > 
> >>>  last command in the list returned successfully and a kernel was loaded it
> >>>  will execute the @command{boot} command.
> >>>  
> >>> @@ -3135,6 +3136,9 @@
> >>>  The @option{--hotkey} option associates a hotkey with a menu entry.
> >>>  @var{key} may be a single letter, or one of the aliases @samp{backspace},
> >>>  @samp{tab}, or @samp{delete}.
> >>> +
> >>> +The @option{--id} may be used to associate unique identifier with a menu 
> >>> entry.
> >>> address@hidden is arbitrary string.
> >>
> >> It has to be
> >> [a-zA-Z_][0-9a-zA-Z_]*
> > 
> > It is not what grub currently does :) Do you really mean underscore?
> > Grub is currently using hyphen.
> > 
> 
> [a-zA-Z_-][0-9a-zA-Z_-]*
> 
> >> (while arbitrary string would work it's not a good idea.
> >>
> > 
> > Sure, but again - it can be arbitrary string. Nothing restricts
> > character set used.
> 
> You're wrong on this. '>' has special meaning and purely numerical id
> wouldn't work either. Only [a-zA-Z_-][0-9a-zA-Z_-]* are guaranteed to
> work in future versions.
> 
> > My goal is to document current grub behavior. Lying
> > about what it does just adds to confusion. I'm fine with adding "it is
> > recommended to restrict value @var{id} to alphanumeric ASCII
> > characters, hyphen and underscore for portability".
> > 
> 
> Again specifying in documentation what happens on bad ids would be
> committing to some form of handling of them which is counterproductive.

I understands. Please review update patch.

From: Andrey Borzenkov <address@hidden>
Subject: [PATCH] document menuentry --id option

Signed-off-by: Andrey Borzenkov <address@hidden>

---
 ChangeLog      |    4 ++++
 docs/grub.texi |   16 ++++++++++------
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f3a9fa0..69f18e1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2013-01-21  Andrey Borzenkov  <address@hidden>
+
+       * docs/grub.texi: Document menuentry --id option.
+
 2013-01-21  Vladimir Serbinenko  <address@hidden>
 
        * grub-core/lib/libgcrypt_wrap/cipher_wrap.h: Include sys/types.h rather
diff --git a/docs/grub.texi b/docs/grub.texi
index 9941b47..9997c6b 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -1521,7 +1521,7 @@ definitions do not affect the exit status in @code{$?}.  
When executed, the
 exit status of a function is the exit status of the last command executed in
 the body.
 
address@hidden menuentry @var{title} address@hidden @dots{}] address@hidden 
address@hidden address@hidden @{ @var{command}; @dots{} @}
address@hidden menuentry @var{title} address@hidden @dots{}] address@hidden 
address@hidden address@hidden address@hidden @{ @var{command}; @dots{} @}
 @xref{menuentry}.
 @end table
 
@@ -3177,13 +3177,13 @@ These commands can only be used in the menu:
 
 @deffn Command menuentry @var{title} @
  address@hidden @dots{}] address@hidden @
- address@hidden address@hidden @
+ address@hidden address@hidden address@hidden @
  @{ @var{command}; @dots{} @}
 This defines a GRUB menu entry named @var{title}.  When this entry is
 selected from the menu, GRUB will set the @var{chosen} environment variable
-to @var{title}, execute the list of commands given within braces, and if the
-last command in the list returned successfully and a kernel was loaded it
-will execute the @command{boot} command.
+to value of @option{--id} if @option{--id} is given, execute the list of
+commands given within braces, and if the last command in the list returned
+successfully and a kernel was loaded it will execute the @command{boot} 
command.
 
 The @option{--class} option may be used any number of times to group menu
 entries into classes.  Menu themes may display different classes using
@@ -3198,6 +3198,10 @@ entries.  @xref{Security}.
 The @option{--hotkey} option associates a hotkey with a menu entry.
 @var{key} may be a single letter, or one of the aliases @samp{backspace},
 @samp{tab}, or @samp{delete}.
+
+The @option{--id} may be used to associate unique identifier with a menu entry.
address@hidden is string of ASCII aphanumeric characters, underscore and hyphen
+and should not start with a digit.
 @end deffn
 
 
@@ -3206,7 +3210,7 @@ The @option{--hotkey} option associates a hotkey with a 
menu entry.
 
 @deffn Command submenu @var{title} @
  address@hidden @dots{}] address@hidden @
- address@hidden address@hidden @
+ address@hidden address@hidden address@hidden @
  @{ @var{menu entries} @dots{} @}
 This defines a submenu.  An entry called @var{title} will be added to the
 menu; when that entry is selected, a new menu will be displayed showing all
-- 
tg: (c73a276..) fu/menuentry-id-option (depends on: master)

signature.asc
Description: PGP signature