* [PATCH] Document menuentry --id option
@ 2012-09-18 16:53 Andrey Borzenkov
2013-01-20 22:51 ` Vladimir 'φ-coder/phcoder' Serbinenko
0 siblings, 1 reply; 5+ messages in thread
From: Andrey Borzenkov @ 2012-09-18 16:53 UTC (permalink / raw)
To: grub-devel
[-- Attachment #1: Type: text/plain, Size: 44 bytes --]
Document "menuentry --id" option.
-andrey
[-- Attachment #2: menuentry-id.patch --]
[-- Type: text/x-patch, Size: 2518 bytes --]
=== modified file 'ChangeLog'
--- old/ChangeLog 2012-09-18 11:04:06 +0000
+++ new/ChangeLog 2012-09-18 16:28:12 +0000
@@ -1,3 +1,7 @@
+2012-09-18 Andrey Borzenkov <arvidjaar@gmail.com>
+
+ * docs/grub.texi: Document menuentry --id option.
+
2012-09-18 Vladimir Serbinenko <phcoder@gmail.com>
* util/grub-mkconfig_lib.in (grub_tab): New variable.
=== modified file 'docs/grub.texi'
--- old/docs/grub.texi 2012-07-31 22:18:57 +0000
+++ new/docs/grub.texi 2012-09-18 16:02:26 +0000
@@ -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
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH] Document menuentry --id option 2012-09-18 16:53 [PATCH] Document menuentry --id option Andrey Borzenkov @ 2013-01-20 22:51 ` Vladimir 'φ-coder/phcoder' Serbinenko 2013-01-21 14:44 ` Andrey Borzenkov 0 siblings, 1 reply; 5+ messages in thread From: Vladimir 'φ-coder/phcoder' Serbinenko @ 2013-01-20 22:51 UTC (permalink / raw) To: The development of GNU GRUB [-- Attachment #1: Type: text/plain, Size: 3105 bytes --] On 18.09.2012 18:53, Andrey Borzenkov wrote: > > === modified file 'ChangeLog' > --- old/ChangeLog 2012-09-18 11:04:06 +0000 > +++ new/ChangeLog 2012-09-18 16:28:12 +0000 > @@ -1,3 +1,7 @@ > +2012-09-18 Andrey Borzenkov <arvidjaar@gmail.com> > + > + * docs/grub.texi: Document menuentry --id option. > + > 2012-09-18 Vladimir Serbinenko <phcoder@gmail.com> > > * util/grub-mkconfig_lib.in (grub_tab): New variable. > > === modified file 'docs/grub.texi' > --- old/docs/grub.texi 2012-07-31 22:18:57 +0000 > +++ new/docs/grub.texi 2012-09-18 16:02:26 +0000 > @@ -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 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. > 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_]* (while arbitrary string would work it's not a good idea. > @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 > -- Regards Vladimir 'φ-coder/phcoder' Serbinenko [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 294 bytes --] ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Document menuentry --id option 2013-01-20 22:51 ` Vladimir 'φ-coder/phcoder' Serbinenko @ 2013-01-21 14:44 ` Andrey Borzenkov 2013-01-21 19:48 ` Vladimir 'φ-coder/phcoder' Serbinenko 0 siblings, 1 reply; 5+ messages in thread From: Andrey Borzenkov @ 2013-01-21 14:44 UTC (permalink / raw) To: grub-devel [-- Attachment #1: Type: text/plain, Size: 2134 bytes --] В Sun, 20 Jan 2013 23:51:46 +0100 Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет: > > @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. > > 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. > (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". [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 198 bytes --] ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Document menuentry --id option 2013-01-21 14:44 ` Andrey Borzenkov @ 2013-01-21 19:48 ` Vladimir 'φ-coder/phcoder' Serbinenko 2013-01-22 11:36 ` Andrey Borzenkov 0 siblings, 1 reply; 5+ messages in thread From: Vladimir 'φ-coder/phcoder' Serbinenko @ 2013-01-21 19:48 UTC (permalink / raw) To: grub-devel [-- Attachment #1: Type: text/plain, Size: 3095 bytes --] On 21.01.2013 15:44, Andrey Borzenkov wrote: > В Sun, 20 Jan 2013 23:51:46 +0100 > Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет: > >>> @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. -- Regards Vladimir 'φ-coder/phcoder' Serbinenko [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 294 bytes --] ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] Document menuentry --id option 2013-01-21 19:48 ` Vladimir 'φ-coder/phcoder' Serbinenko @ 2013-01-22 11:36 ` Andrey Borzenkov 0 siblings, 0 replies; 5+ messages in thread From: Andrey Borzenkov @ 2013-01-22 11:36 UTC (permalink / raw) To: grub-devel [-- Attachment #1: Type: text/plain, Size: 6792 bytes --] В Mon, 21 Jan 2013 20:48:51 +0100 Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет: > On 21.01.2013 15:44, Andrey Borzenkov wrote: > > > В Sun, 20 Jan 2013 23:51:46 +0100 > > Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет: > > > >>> @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 <arvidjaar@gmail.com> Subject: [PATCH] document menuentry --id option Signed-off-by: Andrey Borzenkov <arvidjaar@gmail.com> --- 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 <arvidjaar@gmail.com> + + * docs/grub.texi: Document menuentry --id option. + 2013-01-21 Vladimir Serbinenko <phcoder@gmail.com> * 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) [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 198 bytes --] ^ permalink raw reply related [flat|nested] 5+ messages in thread
end of thread, other threads:[~2013-01-22 11:36 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2012-09-18 16:53 [PATCH] Document menuentry --id option Andrey Borzenkov 2013-01-20 22:51 ` Vladimir 'φ-coder/phcoder' Serbinenko 2013-01-21 14:44 ` Andrey Borzenkov 2013-01-21 19:48 ` Vladimir 'φ-coder/phcoder' Serbinenko 2013-01-22 11:36 ` Andrey Borzenkov
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.