Document menuentry --id option
PATCH 1/1 Document menuentry --id option
Document "menuentry --id" option.
-andrey
=== modified file 'ChangeLog'
ChangeLog +4 -0
@@ -1,3 +1,7 @@ +2012-09-18 Andrey Borzenkov <[email protected]> + + * docs/grub.texi: Document menuentry --id option. + 2012-09-18 Vladimir Serbinenko <[email protected]> * util/grub-mkconfig_lib.in (grub_tab): New variable.
=== modified file 'docs/grub.texi'
docs/grub.texi +8 -4
@@ -1502,7 +1502,7 @@ 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
@@ -3114,11 +3114,12 @@ @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 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. @end deffn
@@ -3143,7 +3147,7 @@ @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
Quoted 27 lines · Andrey Borzenkov
=== modified file 'ChangeLog'
ChangeLog +4
-0@@ -1,3 +1,7 @@ +2012-09-18 Andrey Borzenkov <[email protected]> + + * docs/grub.texi: Document menuentry --id option. + 2012-09-18 Vladimir Serbinenko <[email protected]> * util/grub-mkconfig_lib.in (grub_tab): New variable.=== modified file 'docs/grub.texi'
docs/grub.texi +1
-1@@ -1502,7 +1502,7 @@ 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@@ -3114,11 +3114,12 @@
docs/grub.texi line 3122
Quoted 10 lines
docs/grub.texi +3
-2@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.
docs/grub.texi line 3141
Quoted 10 lines
docs/grub.texi +3
-0last 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_]*
(while arbitrary string would work it's not a good idea.
Quoted 13 lines
docs/grub.texi +1
-1@end deffn@@ -3143,7 +3147,7 @@ @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
Signature · 2 lines
Regards Vladimir 'φ-coder/phcoder' Serbinenko
В Sun, 20 Jan 2013 23:51:46 +0100
Vladimir 'φ-coder/phcoder' Serbinenko <[email protected]> пишет:
Quoted 6 lines
Quoted 6 lines
@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
Quoted 9 lines
docs/grub.texi line 3122
Quoted 4 lines
selected from the menu, GRUB will set the @var{chosen} environment variable
docs/grub.texi +2
-1-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 theIt'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.
Quoted 13 lines
docs/grub.texi line 3141
Quoted 10 lines
last command in the list returned successfully and a kernel was loaded it will execute the @command{boot} command.
docs/grub.texi +3
-0@@ -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.
Quoted 2 lines
(while arbitrary string would work it's not a good idea.
Sure, but again - it can be arbitrary string. Nothing restricts character set used. 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".
Quoted 19 lines · Andrey Borzenkov
В Sun, 20 Jan 2013 23:51:46 +0100
Vladimir 'φ-coder/phcoder' Serbinenko <[email protected]> пишет:Quoted 6 lines
Quoted 6 lines
@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 isQuoted 9 lines
docs/grub.texi line 3122
Quoted 4 lines
selected from the menu, GRUB will set the @var{chosen} environment variable
docs/grub.texi +2
-1-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 theIt'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.
Quoted 2 lines
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.
Quoted 15 lines
Quoted 4 lines
Quoted 4 lines
last command in the list returned successfully and a kernel was loaded it will execute the @command{boot} command.
Quoted 10 lines
docs/grub.texi line 3141
Quoted 7 lines
docs/grub.texi +3
-0@@ -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_]*
Quoted 3 lines
It is not what grub currently does :) Do you really mean underscore? Grub is currently using hyphen.
[a-zA-Z_-][0-9a-zA-Z_-]*
Quoted 5 lines
Quoted 2 lines
(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.
Quoted 5 lines
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.
Signature · 2 lines
Regards Vladimir 'φ-coder/phcoder' Serbinenko
В Mon, 21 Jan 2013 20:48:51 +0100
Vladimir 'φ-coder/phcoder' Serbinenko <[email protected]> пишет:
Quoted 64 lines · Andrey Borzenkov
Quoted 20 lines
В Sun, 20 Jan 2013 23:51:46 +0100
Vladimir 'φ-coder/phcoder' Serbinenko <[email protected]> пишет:Quoted 6 lines
Quoted 6 lines
@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 isQuoted 9 lines
Review
Quoted 4 lines
selected from the menu, GRUB will set the @var{chosen} environment variable
(quoted diff) +2
-1-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 theIt'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.
Quoted 2 lines
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.Quoted 15 lines
Quoted 4 lines
Quoted 4 lines
last command in the list returned successfully and a kernel was loaded it will execute the @command{boot} command.
Quoted 10 lines
Review line 3141
Quoted 7 lines
(quoted diff) +3
-0@@ -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_]*Quoted 3 lines
It is not what grub currently does :) Do you really mean underscore? Grub is currently using hyphen.
[a-zA-Z_-][0-9a-zA-Z_-]*
Quoted 5 lines
Quoted 2 lines
(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.
Quoted 8 lines
Quoted 5 lines
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 <[email protected]>
Subject: [PATCH] document menuentry --id option
--- ChangeLog | 4 ++++ docs/grub.texi | 16 ++++++++++------ 2 files changed, 14 insertions(+), 6 deletions(-)
ChangeLog +4 -0
@@ -1,3 +1,7 @@ +2013-01-21 Andrey Borzenkov <[email protected]> + + * docs/grub.texi: Document menuentry --id option. + 2013-01-21 Vladimir Serbinenko <[email protected]> * grub-core/lib/libgcrypt_wrap/cipher_wrap.h: Include sys/types.h rather
docs/grub.texi +10 -6
@@ -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
Signature · 1 line
tg: (c73a276..) fu/menuentry-id-option (depends on: master)