Re: [PATCH] Documentation update for recent GRUB script changes

[Colin Watson]

On Fri, Aug 20, 2010 at 04:18:14PM +0530, BVK Chaitanya wrote:
> === modified file 'docs/grub.texi'
> --- docs/grub.texi    2010-08-01 16:25:09 +0000
> +++ docs/grub.texi    2010-08-20 10:38:22 +0000
> @@ -1206,8 +1206,10 @@
>  The backslash retains its special meaning only when followed by one of the
>  following characters: @samp{$}, @samp{"}, @samp{\}, or newline.  A
>  backslash-newline pair is treated as a line continuation (that is, it is
> -removed from the input stream and effectively ignored).  A double quote may
> -be quoted within double quotes by preceding it with a backslash.
> +removed from the input stream and effectively address@hidden
> +backslash-newline pair within a variable name is not handled properly, so
   ^ insert "a", so "a backslash-newline pair"

> @@ -1219,11 +1221,15 @@
>  Normal variable names begin with an alphabetic character, followed by zero
>  or more alphanumeric characters.
>  
> -Positional variable names consist of one or more digits.  These are reserved
> -for future expansion.
> +Positional variable names consist of one or more digits.  They represent
> +parameters passed to function calls, with @samp{$1} representing first
> +parameter, and so on.

"the first parameter"

>  The special variable name @samp{?} expands to the exit status of the most
> -recently executed command.
> +recently executed command.  When positional variable names are active, other
> +special variable names @samp{@@}, @samp{*} and @samp{#} are defined and they
> +expand to all positional parameters with necessary quoting, positional
> +parameters without any quoting, and positional parameter count respectively.

So does this have different magic quoting properties from bash, then?
In bash, $@ and $* have specially-defined expansions when they occur
within double quotes.  If GRUB script is different then I think it would
be worth spelling out the differences.

> address@hidden Built-in Commands
> +
> +Some built-in commands are also provided by GRUB script to help script
> +writers perform actions that are otherwise not possible.  For example, these
> +include commands to jump out of the loop statements without fully completing
> +them, etc.

"to jump out of the loop statements without fully completing them" reads
oddly to me; perhaps "to jump out of a loop without fully completing it"
instead.

> address@hidden @asis
> address@hidden break [n]
> +When this command is executed from loops, it jumps out of the @code{for},
> address@hidden, and @code{until} loops without executing any following

"from loops" -> "within a loop", and likewise below under "continue".

"or @code{until}" rather than "and @code{until}" (otherwise it sounds as
though it breaks out of all those loops at once or something).

> +commands in the loop body.  Optional integer argument @code{n} specifies the
> +number of enclosing loops to jump out off, and it defaults to one.

"Optional integer argument" -> "An optional integer argument", and
likewise below under "continue" and "while".

> address@hidden continue [n]
> +When this command is executed from loops, it skips the rest of commands in

"the rest of commands" -> "the remaining commands".

> +the loop body and proceeds with next iteration from the beginning.  For

"the next iteration".

> address@hidden and @code{until} loops, execution starts with their condition.
> +Optional integer argument @code{n} specifies the number of enclosing loops
> +to jump out off, and it defaults to one.

"out off" -> "out of".

> address@hidden shift [n]
> +When this command is executed with in a function, it adjusts its positional

"within".

> +variables by one, by replacing first variable value with second variables
> +value, and so on.  Last positional variable looses its value and values for

"The last positional variable loses its value, and ...".

> +special variables @samp{$@@}, @samp{$*} and @samp{$#} are adjusted
> +accordingly.  Optional integer argument @code{n} specifies number of times
> +to perform shifting, and it defaults to one.
> address@hidden table

Would it be better to just use the bash(1) text for "break", "continue",
and "shift", with small adjustments (e.g. omitting mention of "select")?
It seems at least as clear, and it documents things like return values,
what happens if @code{n} is greater than the number of enclosing loops,
etc.


Something along these lines looks great, though.  Thanks for helping
with the documentation!

-- 
Colin Watson                                       address@hidden