From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.71) id 1Txc9z-0006GH-8K for mharc-grub-devel@gnu.org; Tue, 22 Jan 2013 06:36:59 -0500 Received: from eggs.gnu.org ([208.118.235.92]:60113) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Txc9v-0006Dr-K4 for grub-devel@gnu.org; Tue, 22 Jan 2013 06:36:57 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Txc9t-0008TG-VC for grub-devel@gnu.org; Tue, 22 Jan 2013 06:36:55 -0500 Received: from mail-lb0-f180.google.com ([209.85.217.180]:34897) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Txc9t-0008T4-GE for grub-devel@gnu.org; Tue, 22 Jan 2013 06:36:53 -0500 Received: by mail-lb0-f180.google.com with SMTP id q12so102572lbc.25 for ; Tue, 22 Jan 2013 03:36:52 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=x-received:date:from:to:subject:message-id:in-reply-to:references :x-mailer:mime-version:content-type; bh=/8/SdtO6bUhL85BFfsbwB6cOeadfQykoviFEMYlIL/U=; b=XGmtry3VCBLEIW87rPkhH3HkbY00pQwSku7uSu4deyk1LB7XLyuz8/Oc9eU8gkK0j0 W4RzxLbfQGj5qCBHyxwz/X2pokg4uGT9FwxeX5Sw30BMwExChv+7J7N6ihrqDTJCCXlI zO0bqRe9/A9H+ft+cx1dI5EwqiKO3GNsgH4kPwE+Fd6IlpGKoDQwbdEBz4mlL+xgya2+ nlYw/CIuu86gLFk4G5Pw0+01xBSSiov9rAJXRWVlkMyXLvTWcDRMQ/e03CNhscBRNqwW a5OvEOcf5VU3IJoztVzorHPdhwLBmv+NTNUD3Dbex/Stic4dBYYV69DoOFRVGVEAHyGg VchA== X-Received: by 10.152.121.212 with SMTP id lm20mr20666466lab.42.1358854612397; Tue, 22 Jan 2013 03:36:52 -0800 (PST) Received: from opensuse.site (ppp91-78-198-46.pppoe.mtu-net.ru. [91.78.198.46]) by mx.google.com with ESMTPS id ft8sm6798667lab.9.2013.01.22.03.36.50 (version=SSLv3 cipher=RC4-SHA bits=128/128); Tue, 22 Jan 2013 03:36:51 -0800 (PST) Date: Tue, 22 Jan 2013 15:36:49 +0400 From: Andrey Borzenkov To: grub-devel@gnu.org Subject: Re: [PATCH] Document menuentry --id option Message-ID: <20130122153649.60e6584f@opensuse.site> In-Reply-To: <50FD9BA3.10805@gmail.com> References: <1347987201.1612.5.camel@opensuse.site> <50FC7502.2070006@gmail.com> <20130121184446.5ab5fe87@opensuse.site> <50FD9BA3.10805@gmail.com> X-Mailer: Claws Mail 3.9.0 (GTK+ 2.24.10; x86_64-suse-linux-gnu) Mime-Version: 1.0 Content-Type: multipart/signed; micalg=PGP-SHA1; boundary="Sig_/mGYJzd9XVUbD+TMqomb9uMz"; protocol="application/pgp-signature" X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 209.85.217.180 X-BeenThere: grub-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list Reply-To: The development of GNU GRUB List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 22 Jan 2013 11:36:57 -0000 --Sig_/mGYJzd9XVUbD+TMqomb9uMz Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable =D0=92 Mon, 21 Jan 2013 20:48:51 +0100 Vladimir '=CF=86-coder/phcoder' Serbinenko =D0=BF=D0=B8= =D1=88=D0=B5=D1=82: > On 21.01.2013 15:44, Andrey Borzenkov wrote: >=20 > > =D0=92 Sun, 20 Jan 2013 23:51:46 +0100 > > Vladimir '=CF=86-coder/phcoder' Serbinenko =D0=BF= =D0=B8=D1=88=D0=B5=D1=82: > >=20 > >>> @deffn Command menuentry @var{title} @ > >>> [@option{--class=3Dclass} @dots{}] [@option{--users=3Dusers}] @ > >>> - [@option{--unrestricted}] [@option{--hotkey=3Dkey}] @ > >>> + [@option{--unrestricted}] [@option{--hotkey=3Dkey}] [@option{--id= =3Did}] @ > >>> @{ @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 v= ariable > >>> -to @var{title}, execute the list of commands given within braces, an= d if the > >>> +to value of @option{--id} or @var{title} if @option{--id} is not giv= en, > >>> +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 langua= ge > >> or disk name changes and hence discouraged. > >> > >=20 > > I understand that, but you still need to explain what happens when --id > > is not given. Or make it mandatory argument. >=20 > 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. >=20 > >=20 > >>> last command in the list returned successfully and a kernel was load= ed it > >>> will execute the @command{boot} command. > >>> =20 > >>> @@ -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{backsp= ace}, > >>> @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_]* > >=20 > > It is not what grub currently does :) Do you really mean underscore? > > Grub is currently using hyphen. > >=20 >=20 > [a-zA-Z_-][0-9a-zA-Z_-]* >=20 > >> (while arbitrary string would work it's not a good idea. > >> > >=20 > > Sure, but again - it can be arbitrary string. Nothing restricts > > character set used. >=20 > 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. >=20 > > 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". > >=20 >=20 > 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 =20 * 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. =20 -@item menuentry @var{title} [@option{--class=3Dclass} @dots{}] [@option{--= users=3Dusers}] [@option{--unrestricted}] [@option{--hotkey=3Dkey}] @{ @var= {command}; @dots{} @} +@item menuentry @var{title} [@option{--class=3Dclass} @dots{}] [@option{--= users=3Dusers}] [@option{--unrestricted}] [@option{--hotkey=3Dkey}] [@optio= n{--id=3Did}] @{ @var{command}; @dots{} @} @xref{menuentry}. @end table =20 @@ -3177,13 +3177,13 @@ These commands can only be used in the menu: =20 @deffn Command menuentry @var{title} @ [@option{--class=3Dclass} @dots{}] [@option{--users=3Dusers}] @ - [@option{--unrestricted}] [@option{--hotkey=3Dkey}] @ + [@option{--unrestricted}] [@option{--hotkey=3Dkey}] [@option{--id=3Did}] @ @{ @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 t= he -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} co= mmand. =20 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 e= ntry. +@var{id} is string of ASCII aphanumeric characters, underscore and hyphen +and should not start with a digit. @end deffn =20 =20 @@ -3206,7 +3210,7 @@ The @option{--hotkey} option associates a hotkey with= a menu entry. =20 @deffn Command submenu @var{title} @ [@option{--class=3Dclass} @dots{}] [@option{--users=3Dusers}] @ - [@option{--unrestricted}] [@option{--hotkey=3Dkey}] @ + [@option{--unrestricted}] [@option{--hotkey=3Dkey}] [@option{--id=3Did}] @ @{ @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 --=20 tg: (c73a276..) fu/menuentry-id-option (depends on: master) --Sig_/mGYJzd9XVUbD+TMqomb9uMz Content-Type: application/pgp-signature; name=signature.asc Content-Disposition: attachment; filename=signature.asc -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) iEYEARECAAYFAlD+edEACgkQR6LMutpd94wnEwCdH5Y4wOB+chvXGIIT8P9VcoTY /YQAn1vPTab0TEvNNvNlx0HPIIiTD07Y =89MS -----END PGP SIGNATURE----- --Sig_/mGYJzd9XVUbD+TMqomb9uMz--