В Mon, 21 Jan 2013 20:48:51 +0100 Vladimir 'φ-coder/phcoder' Serbinenko пишет: > On 21.01.2013 15:44, Andrey Borzenkov wrote: > > > В Sun, 20 Jan 2013 23:51:46 +0100 > > Vladimir 'φ-coder/phcoder' Serbinenko пишет: > > > >>> @deffn Command menuentry @var{title} @ > >>> [@option{--class=class} @dots{}] [@option{--users=users}] @ > >>> - [@option{--unrestricted}] [@option{--hotkey=key}] @ > >>> + [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @ > >>> @{ @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. > >>> +@var{id} 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 Subject: [PATCH] document menuentry --id option Signed-off-by: Andrey Borzenkov --- 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 + + * docs/grub.texi: Document menuentry --id option. + 2013-01-21 Vladimir Serbinenko * 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. -@item menuentry @var{title} [@option{--class=class} @dots{}] [@option{--users=users}] [@option{--unrestricted}] [@option{--hotkey=key}] @{ @var{command}; @dots{} @} +@item menuentry @var{title} [@option{--class=class} @dots{}] [@option{--users=users}] [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @{ @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} @ [@option{--class=class} @dots{}] [@option{--users=users}] @ - [@option{--unrestricted}] [@option{--hotkey=key}] @ + [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @ @{ @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. +@var{id} 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} @ [@option{--class=class} @dots{}] [@option{--users=users}] @ - [@option{--unrestricted}] [@option{--hotkey=key}] @ + [@option{--unrestricted}] [@option{--hotkey=key}] [@option{--id=id}] @ @{ @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)