[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] Document menuentry --id option
From: |
Andrey Borzenkov |
Subject: |
Re: [PATCH] Document menuentry --id option |
Date: |
Tue, 22 Jan 2013 15:36:49 +0400 |
В 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