Command documentation policy

Command documentation policy

[Andrey Borzenkov]

Quit a number of commands are not documented. Is it intentional
(because they are not considered "user level API")? Should
documentation for them go into grub or grub-dev?

Re: Command documentation policy

[Colin Watson]

On Tue, Jan 22, 2013 at 05:08:51PM +0400, Andrey Borzenkov wrote:
> Quit a number of commands are not documented. Is it intentional
> (because they are not considered "user level API")? Should
> documentation for them go into grub or grub-dev?

I spent some time documenting the list of commands a while back, but I
never completed the project: what you're seeing is simply how far I got
before getting distracted by other things.  IMO all commands should be
documented in grub.texi.

-- 
Colin Watson                                       [cjwatson@ubuntu.com]

Re: Command documentation policy

[Colin Watson]

On Tue, Jan 22, 2013 at 05:12:18PM +0000, Colin Watson wrote:
> On Tue, Jan 22, 2013 at 05:08:51PM +0400, Andrey Borzenkov wrote:
> > Quit a number of commands are not documented. Is it intentional
> > (because they are not considered "user level API")? Should
> > documentation for them go into grub or grub-dev?
> 
> I spent some time documenting the list of commands a while back, but I
> never completed the project: what you're seeing is simply how far I got
> before getting distracted by other things.  IMO all commands should be
> documented in grub.texi.

Oh, and to be clear: yes, there are some situations where something is
intentionally undocumented (although not really all that many, I think).
However, I don't think that justifies leaving it out of grub.texi
entirely, because that runs the risk of somebody else coming along later
and not realising that this thing was intentionally undocumented.

The approach I'd recommend for such cases is to add a comment (@c or
@ignore / @end ignore) to grub.texi explaining that such-and-such a
command is intentionally undocumented.  That way, it doesn't show up for
users in formatted documentation, but anyone editing the document will
see it.

-- 
Colin Watson                                       [cjwatson@ubuntu.com]

Command documentation part 1.

[Andrey Borzenkov]

В Tue, 22 Jan 2013 17:12:18 +0000
Colin Watson <cjwatson@ubuntu.com> пишет:

> On Tue, Jan 22, 2013 at 05:08:51PM +0400, Andrey Borzenkov wrote:
> > Quit a number of commands are not documented. Is it intentional
> > (because they are not considered "user level API")? Should
> > documentation for them go into grub or grub-dev?
> 
> I spent some time documenting the list of commands a while back, but I
> never completed the project: what you're seeing is simply how far I got
> before getting distracted by other things.  IMO all commands should be
> documented in grub.texi.
> 

Below is attempt to document most of user-relevant commands (I may have
missed a couple of them). Please review (formatting, language).

What is left are

- new file signature checks. I need some time to understand how to
  describe them

- non-Linux loaders. I do not have experience myself, so it will need
  some help probably

- the rest of commands which are more or less low-level, not normally
  expected to be used daily. I have the following suggestion:

* merge General commands and Command-line and menu entry commands into
  General commands. Current split seems to be artificial. Let normal
  user commands go into this section

* Add Advanced commands section where all the more exotic ones are described.

  Does it make sense?

Patch follows

From: Andrey Borzenkov <arvidjaar@gmail.com>
Subject: [PATCH] document grub commands

Add documentation for grub commands

Signed-off-by: Andrey Borzenkov <arvidjaar@gmail.com>

---
 docs/grub.texi |  262 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 259 insertions(+), 3 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index 9941b47..8329ee1 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -1553,6 +1553,10 @@ Causes a function to exit with the return value specified by @code{n}.  If
 in the function body.  If used outside a function the return status is
 false.
 
+@item setparams [@code{arg}] ...
+Replace positional parameters starting with @code{$1} with arguments to
+@command{setparams}.
+
 @item shift [@code{n}]
 The positional parameters from @code{n}+1 @dots{} are renamed to
 @code{$1}@dots{}.  Parameters represented by the numbers @code{$#} down to
@@ -3323,16 +3327,22 @@ you forget a command, you can run the command @command{help}
 (@pxref{help}).
 
 @menu
+* [::                           Check file types and compare values
 * acpi::                        Load ACPI tables
+* authenticate::                Check whether user is in user list
+* background_color::            Set background color for active terminal
+* background_image::            Load background image for active terminal
 * badram::                      Filter out bad regions of RAM
 * blocklist::                   Print a block list
 * boot::                        Start up your operating system
 * cat::                         Show the contents of a file
 * chainloader::                 Chain-load another boot loader
+* clear::                       Clear the screen
 * cmp::                         Compare two files
 * configfile::                  Load a configuration file
 * cpuid::                       Check for CPU features
 * crc::                         Calculate CRC32 checksums
+* cryptomount::                 Mount a crypto device
 * date::                        Display or set current date and time
 * drivemap::                    Map a drive to another
 * echo::                        Display a line of text
@@ -3341,6 +3351,7 @@ you forget a command, you can run the command @command{help}
 * gettext::                     Translate a string
 * gptsync::                     Fill an MBR based on GPT entries
 * halt::                        Shut down your computer
+* hashsum::                     Compute or check hash checksum
 * help::                        Show help messages
 * initrd::                      Load a Linux initrd
 * initrd16::                    Load a Linux initrd (16-bit mode)
@@ -3352,26 +3363,44 @@ you forget a command, you can run the command @command{help}
 * load_env::                    Load variables from environment block
 * loopback::                    Make a device from a filesystem image
 * ls::                          List devices or files
+* lsmod::                       Show loaded modules
+* md5sum::                      Calculate MD5 hash
 * normal::                      Enter normal mode
 * normal_exit::                 Exit from normal mode
 * parttool::                    Modify partition table entries
 * password::                    Set a clear-text password
 * password_pbkdf2::             Set a hashed password
 * play::                        Play a tune
+* probe::                       Retrieve device info
 * pxe_unload::                  Unload the PXE environment
 * read::                        Read user input
 * reboot::                      Reboot your computer
+* rmmod::                       Remove a module
 * save_env::                    Save variables to environment block
 * search::                      Search devices by file, label, or UUID
 * sendkey::                     Emulate keystrokes
 * set::                         Set an environment variable
+* sha1sum::                     Calculate SHA1 hash
+* sha256sum::                   Calculate SHA256 hash
+* sha512sum::                   Calculate SHA512 hash
+* sleep::                       Wait for a specified number of seconds
 * source::                      Read a configuration file in same context
+* test::                        Check file types and compare values
 * true::                        Do nothing, successfully
 * unset::                       Unset an environment variable
 * uppermem::                    Set the upper memory size
+* vbeinfo::                     List available video modes
+* videoinfo::                   List available video modes
 @end menu
 
 
+@node [
+@subsection [
+@deffn Command @code{[} expression @code{]}
+Alias for @code{test @var{expression}} (@pxref{test}).
+@end deffn
+
+
 @node acpi
 @subsection acpi
 
@@ -3393,6 +3422,35 @@ Normally, this command will replace the Root System Description Pointer
 GRUB, but may be used by GRUB's EFI emulation.
 @end deffn
 
+
+@node authenticate
+@subsection authenticate
+@deffn Command authenticate [userlist]
+Check whether user is in @var{userlist} or listed in the value of variable
+@samp{superusers}. See @pxref{superusers} for valid user list format.
+If @samp{superusers} is empty, this command returns true. @xref{Security}.
+@end deffn
+
+
+@node background_color
+@subsection background_color
+
+@deffn Command background_color color
+Set background color for active terminal. For valid color specifications see
+@pxref{Theme file format, ,Colors}.
+@end deffn
+
+
+@node background_image
+@subsection background_image
+
+@deffn Command background_image [[@option{--mode} @samp{stretch}|@samp{normal}] file]
+Load background image for active terminal from @var{file}. Image is stretched
+to fill up entire screen unless option @option{--mode} @samp{normal} is given.
+Without agruments remove currently loaded background image.
+@end deffn
+
+
 @node badram
 @subsection badram
 
@@ -3465,6 +3523,14 @@ load a defective boot loader, such as SCO UnixWare 7.1.
 @end deffn
 
 
+@node clear
+@subsection clear
+
+@deffn Command clear
+Clear the screen.
+@end deffn
+
+
 @node cmp
 @subsection cmp
 
@@ -3515,8 +3581,21 @@ invoked with @option{-l}.  This may change in the future.
 @node crc
 @subsection crc
 
-@deffn Command crc file
-Display the CRC32 checksum of @var{file}.
+@deffn Command crc arg ...
+Alias for @code{hashsum --hash crc32 arg ...}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node cryptomount
+@subsection cryptomount
+
+@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
+Setup access to encrypted device. If neccessary, passphrase
+is requested interactively. Option @var{device} configures specific grub device
+(@pxref{Naming convention}); option @option{-u} @var{uuid} configures device
+with specified @var{uuid}; option @option{-a} configures all encrypted devices;
+option @option{-b} configures all partitions that have boot flag set.
 @end deffn
 
 
@@ -3662,6 +3741,27 @@ is shut down using APM.
 @end deffn
 
 
+@node hashsum
+@subsection hashsum
+
+@deffn Command hashsum @option{--hash} hash @option{--keep-going} @option{--uncompress} @option{--check} file [@option{--prefix} dir]|file ...
+Compute or verify file hashes. Hash type is selected with option @option{--hash}.
+Supported hashes are @samp{crc32}, @samp{md5}, @samp{sha1}, @samp{sha256},
+@samp{sha512}. Option @option{--uncompress} uncompresses files before computing
+hash.
+
+When list of files is given, hash of each file is computed and printed,
+followed by file name, each file on a new line.
+
+When option @option{--check} is given, it points to a file that contains
+list of @var{hash name} pairs. File hash and file name are separated by
+single @key{SPACE} or @key{TAB}, one pair on a line. Option @option{--prefix}
+may be used to give directory where files are located. Hash verification
+stops after the first mismatch was found unless option @option{--keep-going}
+was given.
+@end deffn
+
+
 @node help
 @subsection help
 
@@ -3813,6 +3913,23 @@ name syntax}), then list the contents of that directory.
 @end deffn
 
 
+@node lsmod
+@subsection lsmod
+
+@deffn Command lsmod
+Show list of loaded modules.
+@end deffn
+
+
+@node md5sum
+@subsection md5sum
+
+@deffn Command md5sum arg ...
+Alias for @code{hashsum --hash md5 arg ...}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
 @node normal
 @subsection normal
 
@@ -3914,6 +4031,15 @@ a rest.
 @end deffn
 
 
+@node probe
+@subsection probe
+
+@deffn Command probe [@option{--set} var] @option{--driver}|@option{--partmap}|@option{--fs}|@option{--fs-uuid}|@option{--label} device
+Retrieve device information. If option @option{--set} is given, assign result
+to variable @var{var}, otherwise print information on the screen.
+@end deffn
+
+
 @node pxe_unload
 @subsection pxe_unload
 
@@ -3942,6 +4068,14 @@ Reboot the computer.
 @end deffn
 
 
+@node rmmod
+@subsection rmmod
+
+@deffn Command rmmod module
+Remove a loaded @var{module}.
+@end deffn
+
+
 @node save_env
 @subsection save_env
 
@@ -4134,6 +4268,43 @@ arguments, print all environment variables with their values.
 @end deffn
 
 
+@node sha1sum
+@subsection sha1sum
+
+@deffn Command sha1sum arg ...
+Alias for @code{hashsum --hash sha1 arg ...}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sha256sum
+@subsection sha256sum
+
+@deffn Command sha256sum arg ...
+Alias for @code{hashsum --hash sha256 arg ...}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sha512sum
+@subsection sha512sum
+
+@deffn Command sha512sum arg ...
+Alias for @code{hashsum --hash sha512 arg ...}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sleep
+@subsection sleep
+
+@deffn Command sleep [@option{--verbose}] [@option{--interruptible}] count
+Sleep for @var{count} of seconds. If option @option{--interruptible} is given,
+allow @key{ESC} to interrupt sleep. With @option{--verbose} show countdown
+of remaining seconds.
+@end deffn
+
+
 @node source
 @subsection source
 
@@ -4147,6 +4318,74 @@ will not be shown immediately.
 @end deffn
 
 
+@node test
+@subsection test
+
+@deffn Command test expression
+Evaluate @var{expression} and return zero exit status if result is true,
+non zero status otherwise.
+
+@var{expression} is one of:
+
+@table @asis
+@item @var{string1} @code{==} @var{string2}
+the strings are equal
+@item @var{string1} @code{!=} @var{string2}
+the strings are not equal
+@item @var{string1} @code{<} @var{string2}
+@var{string1} is lexicographically less than @var{string2}
+@item @var{string1} @code{<=} @var{string2}
+@var{string1} is lexicographically less or equal than @var{string2}
+@item @var{string1} @code{>} @var{string2}
+@var{string1} is lexicographically greater than @var{string2}
+@item @var{string1} @code{<=} @var{string2}
+@var{string1} is lexicographically greater or equal than @var{string2}
+@item @var{integer1} @code{-eq} @var{integer2}
+@var{integer1} is equal to @var{integer2}
+@item @var{integer1} @code{-ge} @var{integer2}
+@var{integer1} is greater than or equal to @var{integer2}
+@item @var{integer1} @code{-gt} @var{integer2}
+@var{integer1} is greater than @var{integer2}
+@item @var{integer1} @code{-le} @var{integer2}
+@var{integer1} is less than or equal to @var{integer2}
+@item @var{integer1} @code{-lt} @var{integer2}
+@var{integer1} is less than @var{integer2}
+@item @var{integer1} @code{-ne} @var{integer2}
+@var{integer1} is not equal to @var{integer2}
+@item @var{prefix}@var{integer1} @code{-pgt} @var{prefix}@var{integer2}
+@var{integer1} is greater than @var{integer2} after stripping off common non-numeric @var{prefix}.
+@item @var{prefix}@var{integer1} @code{-plt} @var{prefix}@var{integer2}
+@var{integer1} is less than @var{integer2} after stripping off common non-numeric @var{prefix}.
+@item @var{file1} @code{-nt} @var{file2}
+@var{file1} is newer than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-nt} in which case it is added to the first file modification time.
+@item @var{file1} @code{-ot} @var{file2}
+@var{file1} is older than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-ot} in which case it is added to the first file modification time.
+@item @code{-d} @var{file}
+@var{file} exists and is a directory
+@item @code{-e} @var{file}
+@var{file} exists
+@item @code{-f} @var{file}
+@var{file} exists and is not a directory
+@item @code{-s} @var{file}
+@var{file} exists and has a size greater than zero
+@item @code{-n} @var{string}
+the length of @var{string} is nonzero
+@item @var{string}
+@var{string} is equivalent to @code{-n @var{string}}
+@item @code{-z} @var{string}
+the length of @var{string} is zero
+@item @code{(} @var{expression} @code{)}
+@var{expression} is true
+@item @code{!} @var{expression}
+@var{expression} is false
+@item @var{expression1} @code{-a} @var{expression2}
+both @var{expression1} and @var{expression2} are true
+@item @var{expression1} @code{-o} @var{expression2}
+either @var{expression1} or @var{expression2} is true
+@end table
+@end deffn
+
+
 @node true
 @subsection true
 
@@ -4169,6 +4408,23 @@ Unset the environment variable @var{envvar}.
 
 This command is not yet implemented for GRUB 2, although it is planned.
 
+
+@node vbeinfo
+@subsection vbeinfo
+
+@deffn Command vbeinfo [[WxH]xD]
+Alias for command @command{videoinfo} (@pxref{videoinfo}). It is available
+only on PC BIOS platforms.
+@end deffn
+
+
+@node videoinfo
+@subsection videoinfo
+
+@deffn Command videoinfo [[WxH]xD]
+List available video modes. If resolution is given, show only mathing modes.
+@end deffn
+
 @node Internationalisation
 @chapter Charset
 GRUB uses UTF-8 internally other than in rendering where some GRUB-specific
@@ -4269,7 +4525,7 @@ Identifiers containing non-ASCII may work but aren't supported.
 Only the ASCII space characters (space U+0020, tab U+000b, CR U+000d and
 LF U+000a) are recognised. Other unicode space characters aren't a valid
 field separator.
-@command{test} tests <, >, <=, >=, -pgt and -plt compare the strings in the
+@command{test} (@pxref{test}) tests <, >, <=, >=, -pgt and -plt compare the strings in the
 lexicographical order of unicode codepoints, replicating the behaviour of
 test from coreutils.
 environment variables and commands are listed in the same order.
-- 
tg: (cd8fd59..) u/cmd-doc (depends on: master)

Re: Command documentation part 1.

[Francesco Lavra]

Hi,

On 01/29/2013 11:25 AM, Andrey Borzenkov wrote:
> В Tue, 22 Jan 2013 17:12:18 +0000
> Colin Watson <cjwatson@ubuntu.com> пишет:
> 
>> On Tue, Jan 22, 2013 at 05:08:51PM +0400, Andrey Borzenkov wrote:
>>> Quit a number of commands are not documented. Is it intentional
>>> (because they are not considered "user level API")? Should
>>> documentation for them go into grub or grub-dev?
>>
>> I spent some time documenting the list of commands a while back, but I
>> never completed the project: what you're seeing is simply how far I got
>> before getting distracted by other things.  IMO all commands should be
>> documented in grub.texi.
>>
> 
> Below is attempt to document most of user-relevant commands (I may have
> missed a couple of them). Please review (formatting, language).
> 
> What is left are
> 
> - new file signature checks. I need some time to understand how to
>   describe them
> 
> - non-Linux loaders. I do not have experience myself, so it will need
>   some help probably
> 
> - the rest of commands which are more or less low-level, not normally
>   expected to be used daily. I have the following suggestion:
> 
> * merge General commands and Command-line and menu entry commands into
>   General commands. Current split seems to be artificial. Let normal
>   user commands go into this section
> 
> * Add Advanced commands section where all the more exotic ones are described.
> 
>   Does it make sense?
> 
> Patch follows
> 
> From: Andrey Borzenkov <arvidjaar@gmail.com>
> Subject: [PATCH] document grub commands
> 
> Add documentation for grub commands
> 
> Signed-off-by: Andrey Borzenkov <arvidjaar@gmail.com>
> 
> ---
>  docs/grub.texi |  262 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 259 insertions(+), 3 deletions(-)
> 
> diff --git a/docs/grub.texi b/docs/grub.texi
> index 9941b47..8329ee1 100644
> --- a/docs/grub.texi
> +++ b/docs/grub.texi
[...]
> +@node background_image
> +@subsection background_image
> +
> +@deffn Command background_image [[@option{--mode} @samp{stretch}|@samp{normal}] file]
> +Load background image for active terminal from @var{file}. Image is stretched
> +to fill up entire screen unless option @option{--mode} @samp{normal} is given.
> +Without agruments remove currently loaded background image.

s/agruments/arguments

[...]
> +@node cryptomount
> +@subsection cryptomount
> +
> +@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
> +Setup access to encrypted device. If neccessary, passphrase

s/neccessary/necessary

[...]
> +@node sleep
> +@subsection sleep
> +
> +@deffn Command sleep [@option{--verbose}] [@option{--interruptible}] count
> +Sleep for @var{count} of seconds. If option @option{--interruptible} is given,

The word "of" should be removed (Sleep for @var{count} seconds.)

> +allow @key{ESC} to interrupt sleep. With @option{--verbose} show countdown
> +of remaining seconds.
> +@end deffn
> +
> +
>  @node source
>  @subsection source
>  
> @@ -4147,6 +4318,74 @@ will not be shown immediately.
>  @end deffn
>  
>  
> +@node test
> +@subsection test
> +
> +@deffn Command test expression
> +Evaluate @var{expression} and return zero exit status if result is true,
> +non zero status otherwise.
> +
> +@var{expression} is one of:
> +
> +@table @asis
> +@item @var{string1} @code{==} @var{string2}
> +the strings are equal
> +@item @var{string1} @code{!=} @var{string2}
> +the strings are not equal
> +@item @var{string1} @code{<} @var{string2}
> +@var{string1} is lexicographically less than @var{string2}
> +@item @var{string1} @code{<=} @var{string2}
> +@var{string1} is lexicographically less or equal than @var{string2}
> +@item @var{string1} @code{>} @var{string2}
> +@var{string1} is lexicographically greater than @var{string2}
> +@item @var{string1} @code{<=} @var{string2}

<= should be >=

> +@var{string1} is lexicographically greater or equal than @var{string2}
[...]
> +@node videoinfo
> +@subsection videoinfo
> +
> +@deffn Command videoinfo [[WxH]xD]
> +List available video modes. If resolution is given, show only mathing modes.

s/mathing/matching

Regards,
Francesco

Re: Command documentation part 1.

[Andrey Borzenkov]

В Sat, 09 Feb 2013 12:48:19 +0100
Francesco Lavra <francescolavra.fl@gmail.com> пишет:

Thank you for review!

> Hi,
> 
> On 01/29/2013 11:25 AM, Andrey Borzenkov wrote:
> > В Tue, 22 Jan 2013 17:12:18 +0000
> > Colin Watson <cjwatson@ubuntu.com> пишет:
> > 
> >> On Tue, Jan 22, 2013 at 05:08:51PM +0400, Andrey Borzenkov wrote:
> >>> Quit a number of commands are not documented. Is it intentional
> >>> (because they are not considered "user level API")? Should
> >>> documentation for them go into grub or grub-dev?
> >>
> >> I spent some time documenting the list of commands a while back, but I
> >> never completed the project: what you're seeing is simply how far I got
> >> before getting distracted by other things.  IMO all commands should be
> >> documented in grub.texi.
> >>
> > 
> > Below is attempt to document most of user-relevant commands (I may have
> > missed a couple of them). Please review (formatting, language).
> > 

Well, after some examination there were more left, so version with some
more commands added and typo fixed.

> > What is left are
> > 
> > - new file signature checks. I need some time to understand how to
> >   describe them
> > 
> > - non-Linux loaders. I do not have experience myself, so it will need
> >   some help probably
> > 

- net commands are missing

- legacy commands are missing

> > - the rest of commands which are more or less low-level, not normally
> >   expected to be used daily. I have the following suggestion:
> > 
> > * merge General commands and Command-line and menu entry commands into
> >   General commands. Current split seems to be artificial. Let normal
> >   user commands go into this section
> > 
> > * Add Advanced commands section where all the more exotic ones are described.
> > 
> >   Does it make sense?
> > 


From: Andrey Borzenkov <arvidjaar@gmail.com>
Subject: [PATCH v2] document grub commands

Add documentation for grub commands

Signed-off-by: Andrey Borzenkov <arvidjaar@gmail.com>

---
 docs/grub.texi |  322 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 316 insertions(+), 6 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index 9941b47..494a59d 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -1553,6 +1553,10 @@ Causes a function to exit with the return value specified by @code{n}.  If
 in the function body.  If used outside a function the return status is
 false.
 
+@item setparams [@code{arg}] @dots{}
+Replace positional parameters starting with @code{$1} with arguments to
+@command{setparams}.
+
 @item shift [@code{n}]
 The positional parameters from @code{n}+1 @dots{} are renamed to
 @code{$1}@dots{}.  Parameters represented by the numbers @code{$#} down to
@@ -1750,8 +1754,8 @@ Colors can be specified in several ways:
 The fonts GRUB uses ``PFF2 font format'' bitmap fonts.  Fonts are specified
 with full font names.  Currently there is no
 provision for a preference list of fonts, or deriving one font from another.
-Fonts are loaded with the ``loadfont'' command in GRUB.  To see the list of
-loaded fonts, execute the ``lsfonts'' command.  If there are too many fonts to
+Fonts are loaded with the ``loadfont'' command in GRUB (@ref{loadfont}).  To see the list of
+loaded fonts, execute the ``lsfonts'' command (@ref{lsfonts}).  If there are too many fonts to
 fit on screen, do ``set pager=1'' before executing ``lsfonts''.
 
 
@@ -3323,16 +3327,24 @@ you forget a command, you can run the command @command{help}
 (@pxref{help}).
 
 @menu
+* [::                           Check file types and compare values
 * acpi::                        Load ACPI tables
+* authenticate::                Check whether user is in user list
+* background_color::            Set background color for active terminal
+* background_image::            Load background image for active terminal
 * badram::                      Filter out bad regions of RAM
 * blocklist::                   Print a block list
 * boot::                        Start up your operating system
 * cat::                         Show the contents of a file
 * chainloader::                 Chain-load another boot loader
+* clear::                       Clear the screen
+* cmosclean::                   Clear bit in CMOS
+* cmostest::                    Test bit in CMOS
 * cmp::                         Compare two files
 * configfile::                  Load a configuration file
 * cpuid::                       Check for CPU features
 * crc::                         Calculate CRC32 checksums
+* cryptomount::                 Mount a crypto device
 * date::                        Display or set current date and time
 * drivemap::                    Map a drive to another
 * echo::                        Display a line of text
@@ -3341,6 +3353,7 @@ you forget a command, you can run the command @command{help}
 * gettext::                     Translate a string
 * gptsync::                     Fill an MBR based on GPT entries
 * halt::                        Shut down your computer
+* hashsum::                     Compute or check hash checksum
 * help::                        Show help messages
 * initrd::                      Load a Linux initrd
 * initrd16::                    Load a Linux initrd (16-bit mode)
@@ -3349,29 +3362,50 @@ you forget a command, you can run the command @command{help}
 * linux::                       Load a Linux kernel
 * linux16::                     Load a Linux kernel (16-bit mode)
 * list_env::                    List variables in environment block
+* loadfont::                    Load font files
 * load_env::                    Load variables from environment block
 * loopback::                    Make a device from a filesystem image
 * ls::                          List devices or files
+* lsfonts::                     List loaded fonts
+* lsmod::                       Show loaded modules
+* md5sum::                      Calculate MD5 hash
 * normal::                      Enter normal mode
 * normal_exit::                 Exit from normal mode
 * parttool::                    Modify partition table entries
 * password::                    Set a clear-text password
 * password_pbkdf2::             Set a hashed password
 * play::                        Play a tune
+* probe::                       Retrieve device info
 * pxe_unload::                  Unload the PXE environment
 * read::                        Read user input
 * reboot::                      Reboot your computer
+* regexp::                      Test if regular expression matches string
+* rmmod::                       Remove a module
 * save_env::                    Save variables to environment block
 * search::                      Search devices by file, label, or UUID
 * sendkey::                     Emulate keystrokes
 * set::                         Set an environment variable
+* sha1sum::                     Calculate SHA1 hash
+* sha256sum::                   Calculate SHA256 hash
+* sha512sum::                   Calculate SHA512 hash
+* sleep::                       Wait for a specified number of seconds
 * source::                      Read a configuration file in same context
+* test::                        Check file types and compare values
 * true::                        Do nothing, successfully
 * unset::                       Unset an environment variable
 * uppermem::                    Set the upper memory size
+* vbeinfo::                     List available video modes
+* videoinfo::                   List available video modes
 @end menu
 
 
+@node [
+@subsection [
+@deffn Command @code{[} expression @code{]}
+Alias for @code{test @var{expression}} (@pxref{test}).
+@end deffn
+
+
 @node acpi
 @subsection acpi
 
@@ -3393,6 +3427,35 @@ Normally, this command will replace the Root System Description Pointer
 GRUB, but may be used by GRUB's EFI emulation.
 @end deffn
 
+
+@node authenticate
+@subsection authenticate
+@deffn Command authenticate [userlist]
+Check whether user is in @var{userlist} or listed in the value of variable
+@samp{superusers}. See @pxref{superusers} for valid user list format.
+If @samp{superusers} is empty, this command returns true. @xref{Security}.
+@end deffn
+
+
+@node background_color
+@subsection background_color
+
+@deffn Command background_color color
+Set background color for active terminal. For valid color specifications see
+@pxref{Theme file format, ,Colors}.
+@end deffn
+
+
+@node background_image
+@subsection background_image
+
+@deffn Command background_image [[@option{--mode} @samp{stretch}|@samp{normal}] file]
+Load background image for active terminal from @var{file}. Image is stretched
+to fill up entire screen unless option @option{--mode} @samp{normal} is given.
+Without arguments remove currently loaded background image.
+@end deffn
+
+
 @node badram
 @subsection badram
 
@@ -3465,6 +3528,33 @@ load a defective boot loader, such as SCO UnixWare 7.1.
 @end deffn
 
 
+@node clear
+@subsection clear
+
+@deffn Command clear
+Clear the screen.
+@end deffn
+
+
+@node cmosclean
+@subsection cmosclean
+
+@deffn Command cmosclean byte:bit
+Clear value of bit in CMOS at location @var{byte}:@var{bit}.  This command
+is available only on PC BIOS platform.
+@end deffn
+
+
+@node cmostest
+@subsection cmostest
+
+@deffn Command cmostest byte:bit
+Test value of bit in CMOS at location @var{byte}:@var{bit}. Exit status
+is zero if bit is set, non zero otherwise. This command is available only
+on PC BIOS platform.
+@end deffn
+
+
 @node cmp
 @subsection cmp
 
@@ -3515,8 +3605,21 @@ invoked with @option{-l}.  This may change in the future.
 @node crc
 @subsection crc
 
-@deffn Command crc file
-Display the CRC32 checksum of @var{file}.
+@deffn Command crc arg @dots{}
+Alias for @code{hashsum --hash crc32 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node cryptomount
+@subsection cryptomount
+
+@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
+Setup access to encrypted device. If necessary, passphrase
+is requested interactively. Option @var{device} configures specific grub device
+(@pxref{Naming convention}); option @option{-u} @var{uuid} configures device
+with specified @var{uuid}; option @option{-a} configures all encrypted devices;
+option @option{-b} configures all partitions that have boot flag set.
 @end deffn
 
 
@@ -3662,6 +3765,27 @@ is shut down using APM.
 @end deffn
 
 
+@node hashsum
+@subsection hashsum
+
+@deffn Command hashsum @option{--hash} hash @option{--keep-going} @option{--uncompress} @option{--check} file [@option{--prefix} dir]|file @dots{}
+Compute or verify file hashes. Hash type is selected with option @option{--hash}.
+Supported hashes are @samp{crc32}, @samp{md5}, @samp{sha1}, @samp{sha256},
+@samp{sha512}. Option @option{--uncompress} uncompresses files before computing
+hash.
+
+When list of files is given, hash of each file is computed and printed,
+followed by file name, each file on a new line.
+
+When option @option{--check} is given, it points to a file that contains
+list of @var{hash name} pairs. File hash and file name are separated by
+single @key{SPACE} or @key{TAB}, one pair on a line. Option @option{--prefix}
+may be used to give directory where files are located. Hash verification
+stops after the first mismatch was found unless option @option{--keep-going}
+was given.
+@end deffn
+
+
 @node help
 @subsection help
 
@@ -3780,6 +3904,16 @@ block.
 @end deffn
 
 
+@node loadfont
+@subsection loadfont
+
+@deffn Command loadfont file @dots{}
+Load specified font files. Unless absolute pathname is given, @var{file}
+is assumed to be in directory @samp{$prefix/fonts} with
+suffix @samp{.pf2} appended. @xref{Theme file format,,Fonts}.
+@end deffn
+
+
 @node loopback
 @subsection loopback
 
@@ -3813,6 +3947,31 @@ name syntax}), then list the contents of that directory.
 @end deffn
 
 
+@node lsfonts
+@subsection lsfonts
+
+@deffn Command lsfonts
+List loaded fonts.
+@end deffn
+
+
+@node lsmod
+@subsection lsmod
+
+@deffn Command lsmod
+Show list of loaded modules.
+@end deffn
+
+
+@node md5sum
+@subsection md5sum
+
+@deffn Command md5sum arg @dots{}
+Alias for @code{hashsum --hash md5 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
 @node normal
 @subsection normal
 
@@ -3898,7 +4057,7 @@ to generate password hashes.  @xref{Security}.
 @node play
 @subsection play
 
-@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] ...
+@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] @dots{}
 Plays a tune
 
 If the argument is a file name (@pxref{File name syntax}), play the tune
@@ -3914,6 +4073,15 @@ a rest.
 @end deffn
 
 
+@node probe
+@subsection probe
+
+@deffn Command probe [@option{--set} var] @option{--driver}|@option{--partmap}|@option{--fs}|@option{--fs-uuid}|@option{--label} device
+Retrieve device information. If option @option{--set} is given, assign result
+to variable @var{var}, otherwise print information on the screen.
+@end deffn
+
+
 @node pxe_unload
 @subsection pxe_unload
 
@@ -3942,6 +4110,26 @@ Reboot the computer.
 @end deffn
 
 
+@node regexp
+@subsection regexp
+
+@deffn Command regexp [@option{--set} [number:]var] regexp string
+Test if regular expression @var{regexp} matches @var{string}. Supported
+regular expressions are POSIX.2 Extended Regular Expressions. If option
+@option{--set} is given, store @var{number}th matched subexpression in
+variable @var{var}. Subexpressions are numbered in order of their opening
+parentheses starting from @samp{1}.  @var{number} defaults to @samp{1}.
+@end deffn
+
+
+@node rmmod
+@subsection rmmod
+
+@deffn Command rmmod module
+Remove a loaded @var{module}.
+@end deffn
+
+
 @node save_env
 @subsection save_env
 
@@ -4134,6 +4322,43 @@ arguments, print all environment variables with their values.
 @end deffn
 
 
+@node sha1sum
+@subsection sha1sum
+
+@deffn Command sha1sum arg @dots{}
+Alias for @code{hashsum --hash sha1 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sha256sum
+@subsection sha256sum
+
+@deffn Command sha256sum arg @dots{}
+Alias for @code{hashsum --hash sha256 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sha512sum
+@subsection sha512sum
+
+@deffn Command sha512sum arg @dots{}
+Alias for @code{hashsum --hash sha512 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sleep
+@subsection sleep
+
+@deffn Command sleep [@option{--verbose}] [@option{--interruptible}] count
+Sleep for @var{count} seconds. If option @option{--interruptible} is given,
+allow @key{ESC} to interrupt sleep. With @option{--verbose} show countdown
+of remaining seconds.
+@end deffn
+
+
 @node source
 @subsection source
 
@@ -4147,6 +4372,74 @@ will not be shown immediately.
 @end deffn
 
 
+@node test
+@subsection test
+
+@deffn Command test expression
+Evaluate @var{expression} and return zero exit status if result is true,
+non zero status otherwise.
+
+@var{expression} is one of:
+
+@table @asis
+@item @var{string1} @code{==} @var{string2}
+the strings are equal
+@item @var{string1} @code{!=} @var{string2}
+the strings are not equal
+@item @var{string1} @code{<} @var{string2}
+@var{string1} is lexicographically less than @var{string2}
+@item @var{string1} @code{<=} @var{string2}
+@var{string1} is lexicographically less or equal than @var{string2}
+@item @var{string1} @code{>} @var{string2}
+@var{string1} is lexicographically greater than @var{string2}
+@item @var{string1} @code{>=} @var{string2}
+@var{string1} is lexicographically greater or equal than @var{string2}
+@item @var{integer1} @code{-eq} @var{integer2}
+@var{integer1} is equal to @var{integer2}
+@item @var{integer1} @code{-ge} @var{integer2}
+@var{integer1} is greater than or equal to @var{integer2}
+@item @var{integer1} @code{-gt} @var{integer2}
+@var{integer1} is greater than @var{integer2}
+@item @var{integer1} @code{-le} @var{integer2}
+@var{integer1} is less than or equal to @var{integer2}
+@item @var{integer1} @code{-lt} @var{integer2}
+@var{integer1} is less than @var{integer2}
+@item @var{integer1} @code{-ne} @var{integer2}
+@var{integer1} is not equal to @var{integer2}
+@item @var{prefix}@var{integer1} @code{-pgt} @var{prefix}@var{integer2}
+@var{integer1} is greater than @var{integer2} after stripping off common non-numeric @var{prefix}.
+@item @var{prefix}@var{integer1} @code{-plt} @var{prefix}@var{integer2}
+@var{integer1} is less than @var{integer2} after stripping off common non-numeric @var{prefix}.
+@item @var{file1} @code{-nt} @var{file2}
+@var{file1} is newer than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-nt} in which case it is added to the first file modification time.
+@item @var{file1} @code{-ot} @var{file2}
+@var{file1} is older than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-ot} in which case it is added to the first file modification time.
+@item @code{-d} @var{file}
+@var{file} exists and is a directory
+@item @code{-e} @var{file}
+@var{file} exists
+@item @code{-f} @var{file}
+@var{file} exists and is not a directory
+@item @code{-s} @var{file}
+@var{file} exists and has a size greater than zero
+@item @code{-n} @var{string}
+the length of @var{string} is nonzero
+@item @var{string}
+@var{string} is equivalent to @code{-n @var{string}}
+@item @code{-z} @var{string}
+the length of @var{string} is zero
+@item @code{(} @var{expression} @code{)}
+@var{expression} is true
+@item @code{!} @var{expression}
+@var{expression} is false
+@item @var{expression1} @code{-a} @var{expression2}
+both @var{expression1} and @var{expression2} are true
+@item @var{expression1} @code{-o} @var{expression2}
+either @var{expression1} or @var{expression2} is true
+@end table
+@end deffn
+
+
 @node true
 @subsection true
 
@@ -4169,6 +4462,23 @@ Unset the environment variable @var{envvar}.
 
 This command is not yet implemented for GRUB 2, although it is planned.
 
+
+@node vbeinfo
+@subsection vbeinfo
+
+@deffn Command vbeinfo [[WxH]xD]
+Alias for command @command{videoinfo} (@pxref{videoinfo}). It is available
+only on PC BIOS platforms.
+@end deffn
+
+
+@node videoinfo
+@subsection videoinfo
+
+@deffn Command videoinfo [[WxH]xD]
+List available video modes. If resolution is given, show only matching modes.
+@end deffn
+
 @node Internationalisation
 @chapter Charset
 GRUB uses UTF-8 internally other than in rendering where some GRUB-specific
@@ -4269,7 +4579,7 @@ Identifiers containing non-ASCII may work but aren't supported.
 Only the ASCII space characters (space U+0020, tab U+000b, CR U+000d and
 LF U+000a) are recognised. Other unicode space characters aren't a valid
 field separator.
-@command{test} tests <, >, <=, >=, -pgt and -plt compare the strings in the
+@command{test} (@pxref{test}) tests <, >, <=, >=, -pgt and -plt compare the strings in the
 lexicographical order of unicode codepoints, replicating the behaviour of
 test from coreutils.
 environment variables and commands are listed in the same order.
-- 
tg: (cc35b49..) u/cmd-doc (depends on: master)

Re: Command documentation part 1.

[Vladimir 'φ-coder/phcoder' Serbinenko]

[-- Attachment #1: Type: text/plain, Size: 5206 bytes --]

On 24.02.2013 08:40, Andrey Borzenkov wrote:

>  
>  @menu
> +* [::                           Check file types and compare values
>  * acpi::                        Load ACPI tables
> +* authenticate::                Check whether user is in user list
> +* background_color::            Set background color for active terminal
> +* background_image::            Load background image for active terminal

These are specific to gfxterm, not generic how your patch would suggest.
> +* md5sum::                      Calculate MD5 hash
It also checks. This is an alias to hashsum

> +* sha1sum::                     Calculate SHA1 hash
> +* sha256sum::                   Calculate SHA256 hash
> +* sha512sum::                   Calculate SHA512 hash

ditto

> +* vbeinfo::                     List available video modes

vbeinfo is a compatibility alias and is reserved for VBE.
Perhaps we should start having commands specifically excluded from help
lists to discourage their use

> +@node background_color
> +@subsection background_color
> +
> +@deffn Command background_color color
> +Set background color for active terminal. For valid color specifications see
> +@pxref{Theme file format, ,Colors}.
> +@end deffn
> +
> +
> +@node background_image
> +@subsection background_image
> +
> +@deffn Command background_image [[@option{--mode} @samp{stretch}|@samp{normal}] file]
> +Load background image for active terminal from @var{file}. Image is stretched
> +to fill up entire screen unless option @option{--mode} @samp{normal} is given.
> +Without arguments remove currently loaded background image.
> +@end deffn

Ditto. gfxterm-specific

> +@node cmosclean
> +@subsection cmosclean
> +
> +@deffn Command cmosclean byte:bit
> +Clear value of bit in CMOS at location @var{byte}:@var{bit}.  This command
> +is available only on PC BIOS platform.
> +@end deffn

It's available on all platforms featuring CMOS which are all x86
(including EFI, coreboot, ieeee1275, and so on), Loongson, Qemu-mips and
some IEEE1275 platforms (determined at runtime).

GROUPS["cmos"] = GROUPS["x86"][:] + ["mips_loongson", "mips_qemu_mips",
                                     "sparc64_ieee1275", "powerpc_ieee1275"]

> +

> +
> +@node cmostest
> +@subsection cmostest
> +
> +@deffn Command cmostest byte:bit
> +Test value of bit in CMOS at location @var{byte}:@var{bit}. Exit status
> +is zero if bit is set, non zero otherwise. This command is available only
> +on PC BIOS platform.
> +@end deffn
> +

Ditto.

> -@deffn Command crc file
> -Display the CRC32 checksum of @var{file}.
> +@deffn Command crc arg @dots{}
> +Alias for @code{hashsum --hash crc32 arg @dots{}}. See command @command{hashsum}
> +(@pxref{hashsum}) for full description.
> +@end deffn
> +
> +
> +@node cryptomount
> +@subsection cryptomount
> +
> +@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
> +Setup access to encrypted device. If necessary, passphrase
> +is requested interactively. Option @var{device} configures specific grub device
> +(@pxref{Naming convention}); option @option{-u} @var{uuid} configures device
> +with specified @var{uuid}; option @option{-a} configures all encrypted devices;

Only the ones GRUB supports

> +option @option{-b} configures all partitions that have boot flag set.

Last part is wrong. It refers to boot flag in geli container, not the
one in partmap.
Also I think it's worth mentioning that luks/geli/... aren't autoloaded.

> +@node hashsum
> +@subsection hashsum
> +
> +@deffn Command hashsum @option{--hash} hash @option{--keep-going} @option{--uncompress} @option{--check} file [@option{--prefix} dir]|file @dots{}
> +Compute or verify file hashes. Hash type is selected with option @option{--hash}.
> +Supported hashes are @samp{crc32}, @samp{md5}, @samp{sha1}, @samp{sha256},
> +@samp{sha512}.

Much more hashes are supported. Currently:

ADLER32: adler32
CRC64: crc64
CRC32: gcry_crc
CRC32RFC1510: gcry_crc
CRC24RFC2440: gcry_crc
MD4: gcry_md4
MD5: gcry_md5
RIPEMD160: gcry_rmd160
SHA1: gcry_sha1
SHA224: gcry_sha256
SHA256: gcry_sha256
SHA512: gcry_sha512
SHA384: gcry_sha512
TIGER192: gcry_tiger
TIGER: gcry_tiger
TIGER2: gcry_tiger
WHIRLPOOL: gcry_whirlpool

> +When option @option{--check} is given, it points to a file that contains
> +list of @var{hash name} pairs. File hash and file name are separated by
> +single @key{SPACE} or @key{TAB}, one pair on a line. Option @option{--prefix}
> +may be used to give directory where files are located. Hash verification
> +stops after the first mismatch was found unless option @option{--keep-going}
> +was given.
> +@end deffn

This is the same format as used by standard UNIX tools.

> @@ -4147,6 +4372,74 @@ will not be shown immediately.
>  @end deffn
>  
>  
> +@node test
> +@subsection test
> +
> +@deffn Command test expression
> +Evaluate @var{expression} and return zero exit status if result is true,
> +non zero status otherwise.
> +
> +@var{expression} is one of:


Did you copy it from somewhere else? Please specify all parts copied
from anywhere else.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]

Re: Command documentation part 1.

[Andrey Borzenkov]

[-- Attachment #1: Type: text/plain, Size: 4397 bytes --]

В Thu, 07 Mar 2013 12:06:56 +0100
Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:

> On 24.02.2013 08:40, Andrey Borzenkov wrote:
> 
> >  
> >  @menu
> > +* [::                           Check file types and compare values
> >  * acpi::                        Load ACPI tables
> > +* authenticate::                Check whether user is in user list
> > +* background_color::            Set background color for active terminal
> > +* background_image::            Load background image for active terminal
> 
> These are specific to gfxterm, not generic how your patch would suggest.

Is it enough to mention that in command description or we need separate
section for gfxterm-specific commands?

> > +* vbeinfo::                     List available video modes
> 
> vbeinfo is a compatibility alias and is reserved for VBE.
> Perhaps we should start having commands specifically excluded from help
> lists to discourage their use
> 

Is it OK to leave them as comments as Colin suggested (so that they
won't be re-added over and over again)?

> 
> > +@node cmosclean
> > +@subsection cmosclean
> > +
> > +@deffn Command cmosclean byte:bit
> > +Clear value of bit in CMOS at location @var{byte}:@var{bit}.  This command
> > +is available only on PC BIOS platform.
> > +@end deffn
> 
> It's available on all platforms featuring CMOS which are all x86
> (including EFI, coreboot, ieeee1275, and so on), Loongson, Qemu-mips and
> some IEEE1275 platforms (determined at runtime).
> 

Is it OK to change it into "This command is available only on platforms
that support CMOS"?

> > -@deffn Command crc file
> > -Display the CRC32 checksum of @var{file}.
> > +@deffn Command crc arg @dots{}
> > +Alias for @code{hashsum --hash crc32 arg @dots{}}. See command @command{hashsum}
> > +(@pxref{hashsum}) for full description.
> > +@end deffn
> > +
> > +
> > +@node cryptomount
> > +@subsection cryptomount
> > +
> > +@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
> > +Setup access to encrypted device. If necessary, passphrase
> > +is requested interactively. Option @var{device} configures specific grub device
> > +(@pxref{Naming convention}); option @option{-u} @var{uuid} configures device
> > +with specified @var{uuid}; option @option{-a} configures all encrypted devices;
> 
> Only the ones GRUB supports
> 
> > +option @option{-b} configures all partitions that have boot flag set.
> 
> Last part is wrong. It refers to boot flag in geli container, not the
> one in partmap.

To be honest, this is taken directly from command help; I do not know
myself what geli is. Could you suggest correct description for this
option?

> Also I think it's worth mentioning that luks/geli/... aren't autoloaded.
> 

OK

> > +@node hashsum
> > +@subsection hashsum
> > +
> > +@deffn Command hashsum @option{--hash} hash @option{--keep-going} @option{--uncompress} @option{--check} file [@option{--prefix} dir]|file @dots{}
> > +Compute or verify file hashes. Hash type is selected with option @option{--hash}.
> > +Supported hashes are @samp{crc32}, @samp{md5}, @samp{sha1}, @samp{sha256},
> > +@samp{sha512}.
> 
> Much more hashes are supported. Currently:
> 

OK, I see.


> > +When option @option{--check} is given, it points to a file that contains
> > +list of @var{hash name} pairs. File hash and file name are separated by
> > +single @key{SPACE} or @key{TAB}, one pair on a line. Option @option{--prefix}
> > +may be used to give directory where files are located. Hash verification
> > +stops after the first mismatch was found unless option @option{--keep-going}
> > +was given.
> > +@end deffn
> 
> This is the same format as used by standard UNIX tools.
> 

Sure; do you mean there is no need to document it?

> > @@ -4147,6 +4372,74 @@ will not be shown immediately.
> >  @end deffn
> >  
> >  
> > +@node test
> > +@subsection test
> > +
> > +@deffn Command test expression
> > +Evaluate @var{expression} and return zero exit status if result is true,
> > +non zero status otherwise.
> > +
> > +@var{expression} is one of:
> 
> 
> Did you copy it from somewhere else? Please specify all parts copied
> from anywhere else.
> 

I used "man test" as template. I think the only part that was directly
copied was this sentence.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Command documentation part 1.

[Andrey Borzenkov]

[-- Attachment #1: Type: text/plain, Size: 23214 bytes --]

В Thu, 07 Mar 2013 12:06:56 +0100
Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:

> > +* background_color::            Set background color for active terminal
> > +* background_image::            Load background image for active terminal
> 
> These are specific to gfxterm, not generic how your patch would suggest.

Fixed

> It also checks. This is an alias to hashsum
> 

Fixed

> > +* vbeinfo::                     List available video modes
> 
> vbeinfo is a compatibility alias and is reserved for VBE.
> Perhaps we should start having commands specifically excluded from help
> lists to discourage their use
>

Commented out using @comment and @ignore.
 
> > +@node cmosclean
> It's available on all platforms featuring CMOS which are all x86
> (including EFI, coreboot, ieeee1275, and so on), Loongson, Qemu-mips and
> some IEEE1275 platforms (determined at runtime).
> 
> GROUPS["cmos"] = GROUPS["x86"][:] + ["mips_loongson", "mips_qemu_mips",
>                                      "sparc64_ieee1275", "powerpc_ieee1275"]
>

I'm not sure whether explicitly listing them here is needed, just added
note that it may be available everywhere. 

> > +@node cmostest
> 
> Ditto.
> 

Too.

> > +@node cryptomount
> > +@subsection cryptomount
> > +
> > +@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
> > +Setup access to encrypted device. If necessary, passphrase
> > +is requested interactively. Option @var{device} configures specific grub device
> > +(@pxref{Naming convention}); option @option{-u} @var{uuid} configures device
> > +with specified @var{uuid}; option @option{-a} configures all encrypted devices;
> 
> Only the ones GRUB supports
>

Rephrased as "all detected encrypted devices"
 
> > +option @option{-b} configures all partitions that have boot flag set.
> 
> Last part is wrong. It refers to boot flag in geli container, not the
> one in partmap.

changed

> Also I think it's worth mentioning that luks/geli/... aren't autoloaded.
> 

Is there any other encryption container that is currently supported? I
see only LUKS and geli.

Also changed installation part that says encrypted devices are not
supported.

> Much more hashes are supported. Currently:
> 
> ADLER32: adler32
> CRC64: crc64
> CRC32: gcry_crc
> CRC32RFC1510: gcry_crc
> CRC24RFC2440: gcry_crc
> MD4: gcry_md4
> MD5: gcry_md5
> RIPEMD160: gcry_rmd160
> SHA1: gcry_sha1
> SHA224: gcry_sha256
> SHA256: gcry_sha256
> SHA512: gcry_sha512
> SHA384: gcry_sha512
> TIGER192: gcry_tiger
> TIGER: gcry_tiger
> TIGER2: gcry_tiger
> WHIRLPOOL: gcry_whirlpool
> 

Added all.

> > +When option @option{--check} is given, it points to a file that contains
> > +list of @var{hash name} pairs. File hash and file name are separated by
> > +single @key{SPACE} or @key{TAB}, one pair on a line. Option @option{--prefix}
> > +may be used to give directory where files are located. Hash verification
> > +stops after the first mismatch was found unless option @option{--keep-going}
> > +was given.
> > +@end deffn
> 
> This is the same format as used by standard UNIX tools.
> 

Not sure what change is needed so left alone :)

> > @@ -4147,6 +4372,74 @@ will not be shown immediately.
> >  @end deffn
> >  
> >  
> > +@node test
> > +@subsection test
> > +
> > +@deffn Command test expression
> > +Evaluate @var{expression} and return zero exit status if result is true,
> > +non zero status otherwise.
> > +
> > +@var{expression} is one of:
> 
> 
> Did you copy it from somewhere else? Please specify all parts copied
> from anywhere else.
> 

As mentioned, used "man test" as template.

---

From: Andrey Borzenkov <arvidjaar@gmail.com>
Subject: [PATCH v3] document grub commands

Add documentation for grub commands

Signed-off-by: Andrey Borzenkov <arvidjaar@gmail.com>

---
 docs/grub.texi |  348 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 339 insertions(+), 9 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index 0b66827..d45b637 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -1554,6 +1554,10 @@ Causes a function to exit with the return value specified by @code{n}.  If
 in the function body.  If used outside a function the return status is
 false.
 
+@item setparams [@code{arg}] @dots{}
+Replace positional parameters starting with @code{$1} with arguments to
+@command{setparams}.
+
 @item shift [@code{n}]
 The positional parameters from @code{n}+1 @dots{} are renamed to
 @code{$1}@dots{}.  Parameters represented by the numbers @code{$#} down to
@@ -1751,8 +1755,8 @@ Colors can be specified in several ways:
 The fonts GRUB uses ``PFF2 font format'' bitmap fonts.  Fonts are specified
 with full font names.  Currently there is no
 provision for a preference list of fonts, or deriving one font from another.
-Fonts are loaded with the ``loadfont'' command in GRUB.  To see the list of
-loaded fonts, execute the ``lsfonts'' command.  If there are too many fonts to
+Fonts are loaded with the ``loadfont'' command in GRUB (@ref{loadfont}).  To see the list of
+loaded fonts, execute the ``lsfonts'' command (@ref{lsfonts}).  If there are too many fonts to
 fit on screen, do ``set pager=1'' before executing ``lsfonts''.
 
 
@@ -3361,16 +3365,25 @@ you forget a command, you can run the command @command{help}
 (@pxref{help}).
 
 @menu
+* [::                           Check file types and compare values
 * acpi::                        Load ACPI tables
+* authenticate::                Check whether user is in user list
+* background_color::            Set background color for active terminal
+* background_image::            Load background image for active terminal
 * badram::                      Filter out bad regions of RAM
 * blocklist::                   Print a block list
 * boot::                        Start up your operating system
 * cat::                         Show the contents of a file
 * chainloader::                 Chain-load another boot loader
+* clear::                       Clear the screen
+* cmosclean::                   Clear bit in CMOS
+* cmosdump::                    Dump CMOS contents
+* cmostest::                    Test bit in CMOS
 * cmp::                         Compare two files
 * configfile::                  Load a configuration file
 * cpuid::                       Check for CPU features
-* crc::                         Calculate CRC32 checksums
+* crc::                         Compute or check CRC32 checksums
+* cryptomount::                 Mount a crypto device
 * date::                        Display or set current date and time
 * drivemap::                    Map a drive to another
 * echo::                        Display a line of text
@@ -3379,6 +3392,7 @@ you forget a command, you can run the command @command{help}
 * gettext::                     Translate a string
 * gptsync::                     Fill an MBR based on GPT entries
 * halt::                        Shut down your computer
+* hashsum::                     Compute or check hash checksum
 * help::                        Show help messages
 * initrd::                      Load a Linux initrd
 * initrd16::                    Load a Linux initrd (16-bit mode)
@@ -3387,29 +3401,50 @@ you forget a command, you can run the command @command{help}
 * linux::                       Load a Linux kernel
 * linux16::                     Load a Linux kernel (16-bit mode)
 * list_env::                    List variables in environment block
+* loadfont::                    Load font files
 * load_env::                    Load variables from environment block
 * loopback::                    Make a device from a filesystem image
 * ls::                          List devices or files
+* lsfonts::                     List loaded fonts
+* lsmod::                       Show loaded modules
+* md5sum::                      Compute or check MD5 hash
 * normal::                      Enter normal mode
 * normal_exit::                 Exit from normal mode
 * parttool::                    Modify partition table entries
 * password::                    Set a clear-text password
 * password_pbkdf2::             Set a hashed password
 * play::                        Play a tune
+* probe::                       Retrieve device info
 * pxe_unload::                  Unload the PXE environment
 * read::                        Read user input
 * reboot::                      Reboot your computer
+* regexp::                      Test if regular expression matches string
+* rmmod::                       Remove a module
 * save_env::                    Save variables to environment block
 * search::                      Search devices by file, label, or UUID
 * sendkey::                     Emulate keystrokes
 * set::                         Set an environment variable
+* sha1sum::                     Compute or check SHA1 hash
+* sha256sum::                   Compute or check SHA256 hash
+* sha512sum::                   Compute or check SHA512 hash
+* sleep::                       Wait for a specified number of seconds
 * source::                      Read a configuration file in same context
+* test::                        Check file types and compare values
 * true::                        Do nothing, successfully
 * unset::                       Unset an environment variable
 * uppermem::                    Set the upper memory size
+@comment * vbeinfo::                     List available video modes
+* videoinfo::                   List available video modes
 @end menu
 
 
+@node [
+@subsection [
+@deffn Command @code{[} expression @code{]}
+Alias for @code{test @var{expression}} (@pxref{test}).
+@end deffn
+
+
 @node acpi
 @subsection acpi
 
@@ -3431,6 +3466,38 @@ Normally, this command will replace the Root System Description Pointer
 GRUB, but may be used by GRUB's EFI emulation.
 @end deffn
 
+
+@node authenticate
+@subsection authenticate
+@deffn Command authenticate [userlist]
+Check whether user is in @var{userlist} or listed in the value of variable
+@samp{superusers}. See @pxref{superusers} for valid user list format.
+If @samp{superusers} is empty, this command returns true. @xref{Security}.
+@end deffn
+
+
+@node background_color
+@subsection background_color
+
+@deffn Command background_color color
+Set background color for active terminal. For valid color specifications see
+@pxref{Theme file format, ,Colors}. Background color can be changed only when
+using @samp{gfxterm} for terminal output.
+@end deffn
+
+
+@node background_image
+@subsection background_image
+
+@deffn Command background_image [[@option{--mode} @samp{stretch}|@samp{normal}] file]
+Load background image for active terminal from @var{file}. Image is stretched
+to fill up entire screen unless option @option{--mode} @samp{normal} is given.
+Without arguments remove currently loaded background image. Background image
+can be changed only when using @samp{gfxterm} for terminal output.
+
+@end deffn
+
+
 @node badram
 @subsection badram
 
@@ -3503,6 +3570,42 @@ load a defective boot loader, such as SCO UnixWare 7.1.
 @end deffn
 
 
+@node clear
+@subsection clear
+
+@deffn Command clear
+Clear the screen.
+@end deffn
+
+
+@node cmosclean
+@subsection cmosclean
+
+@deffn Command cmosclean byte:bit
+Clear value of bit in CMOS at location @var{byte}:@var{bit}. This command
+is available only on platforms that support CMOS.
+@end deffn
+
+
+@node cmosdump
+@subsection cmosdump
+
+@deffn Dump CMOS contents
+Dump full CMOS contents as hexadecimal values. This command is available only
+on platforms that support CMOS.
+@end deffn
+
+
+@node cmostest
+@subsection cmostest
+
+@deffn Command cmostest byte:bit
+Test value of bit in CMOS at location @var{byte}:@var{bit}. Exit status
+is zero if bit is set, non zero otherwise. This command is available only
+on platforms that support CMOS.
+@end deffn
+
+
 @node cmp
 @subsection cmp
 
@@ -3553,8 +3656,24 @@ invoked with @option{-l}.  This may change in the future.
 @node crc
 @subsection crc
 
-@deffn Command crc file
-Display the CRC32 checksum of @var{file}.
+@deffn Command crc arg @dots{}
+Alias for @code{hashsum --hash crc32 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node cryptomount
+@subsection cryptomount
+
+@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
+Setup access to encrypted device. If necessary, passphrase
+is requested interactively. Option @var{device} configures specific grub device
+(@pxref{Naming convention}); option @option{-u} @var{uuid} configures device
+with specified @var{uuid}; option @option{-a} configures all detected encrypted
+devices; option @option{-b} configures all geli containers that have boot flag set.
+
+GRUB suports devices encrypted using LUKS and geli. Note that necessary modules (@var{luks} and @var{geli}) have to be loaded manually before this command can
+be used.
 @end deffn
 
 
@@ -3700,6 +3819,29 @@ is shut down using APM.
 @end deffn
 
 
+@node hashsum
+@subsection hashsum
+
+@deffn Command hashsum @option{--hash} hash @option{--keep-going} @option{--uncompress} @option{--check} file [@option{--prefix} dir]|file @dots{}
+Compute or verify file hashes. Hash type is selected with option @option{--hash}.
+Supported hashes are: @samp{adler32}, @samp{crc64}, @samp{crc32},
+@samp{crc32rfc1510}, @samp{crc24rfc2440}, @samp{md4}, @samp{md5},
+@samp{ripemd160}, @samp{sha1}, @samp{sha224}, @samp{sha256}, @samp{sha512},
+@samp{sha384}, @samp{tiger192}, @samp{tiger}, @samp{tiger2}, @samp{whirlpool}.
+Option @option{--uncompress} uncompresses files before computing hash.
+
+When list of files is given, hash of each file is computed and printed,
+followed by file name, each file on a new line.
+
+When option @option{--check} is given, it points to a file that contains
+list of @var{hash name} pairs. File hash and file name are separated by
+single @key{SPACE} or @key{TAB}, one pair on a line. Option @option{--prefix}
+may be used to give directory where files are located. Hash verification
+stops after the first mismatch was found unless option @option{--keep-going}
+was given.
+@end deffn
+
+
 @node help
 @subsection help
 
@@ -3818,6 +3960,16 @@ block.
 @end deffn
 
 
+@node loadfont
+@subsection loadfont
+
+@deffn Command loadfont file @dots{}
+Load specified font files. Unless absolute pathname is given, @var{file}
+is assumed to be in directory @samp{$prefix/fonts} with
+suffix @samp{.pf2} appended. @xref{Theme file format,,Fonts}.
+@end deffn
+
+
 @node loopback
 @subsection loopback
 
@@ -3851,6 +4003,31 @@ name syntax}), then list the contents of that directory.
 @end deffn
 
 
+@node lsfonts
+@subsection lsfonts
+
+@deffn Command lsfonts
+List loaded fonts.
+@end deffn
+
+
+@node lsmod
+@subsection lsmod
+
+@deffn Command lsmod
+Show list of loaded modules.
+@end deffn
+
+
+@node md5sum
+@subsection md5sum
+
+@deffn Command md5sum arg @dots{}
+Alias for @code{hashsum --hash md5 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
 @node normal
 @subsection normal
 
@@ -3936,7 +4113,7 @@ to generate password hashes.  @xref{Security}.
 @node play
 @subsection play
 
-@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] ...
+@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] @dots{}
 Plays a tune
 
 If the argument is a file name (@pxref{File name syntax}), play the tune
@@ -3952,6 +4129,15 @@ a rest.
 @end deffn
 
 
+@node probe
+@subsection probe
+
+@deffn Command probe [@option{--set} var] @option{--driver}|@option{--partmap}|@option{--fs}|@option{--fs-uuid}|@option{--label} device
+Retrieve device information. If option @option{--set} is given, assign result
+to variable @var{var}, otherwise print information on the screen.
+@end deffn
+
+
 @node pxe_unload
 @subsection pxe_unload
 
@@ -3980,6 +4166,26 @@ Reboot the computer.
 @end deffn
 
 
+@node regexp
+@subsection regexp
+
+@deffn Command regexp [@option{--set} [number:]var] regexp string
+Test if regular expression @var{regexp} matches @var{string}. Supported
+regular expressions are POSIX.2 Extended Regular Expressions. If option
+@option{--set} is given, store @var{number}th matched subexpression in
+variable @var{var}. Subexpressions are numbered in order of their opening
+parentheses starting from @samp{1}.  @var{number} defaults to @samp{1}.
+@end deffn
+
+
+@node rmmod
+@subsection rmmod
+
+@deffn Command rmmod module
+Remove a loaded @var{module}.
+@end deffn
+
+
 @node save_env
 @subsection save_env
 
@@ -4172,6 +4378,43 @@ arguments, print all environment variables with their values.
 @end deffn
 
 
+@node sha1sum
+@subsection sha1sum
+
+@deffn Command sha1sum arg @dots{}
+Alias for @code{hashsum --hash sha1 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sha256sum
+@subsection sha256sum
+
+@deffn Command sha256sum arg @dots{}
+Alias for @code{hashsum --hash sha256 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sha512sum
+@subsection sha512sum
+
+@deffn Command sha512sum arg @dots{}
+Alias for @code{hashsum --hash sha512 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sleep
+@subsection sleep
+
+@deffn Command sleep [@option{--verbose}] [@option{--interruptible}] count
+Sleep for @var{count} seconds. If option @option{--interruptible} is given,
+allow @key{ESC} to interrupt sleep. With @option{--verbose} show countdown
+of remaining seconds.
+@end deffn
+
+
 @node source
 @subsection source
 
@@ -4185,6 +4428,74 @@ will not be shown immediately.
 @end deffn
 
 
+@node test
+@subsection test
+
+@deffn Command test expression
+Evaluate @var{expression} and return zero exit status if result is true,
+non zero status otherwise.
+
+@var{expression} is one of:
+
+@table @asis
+@item @var{string1} @code{==} @var{string2}
+the strings are equal
+@item @var{string1} @code{!=} @var{string2}
+the strings are not equal
+@item @var{string1} @code{<} @var{string2}
+@var{string1} is lexicographically less than @var{string2}
+@item @var{string1} @code{<=} @var{string2}
+@var{string1} is lexicographically less or equal than @var{string2}
+@item @var{string1} @code{>} @var{string2}
+@var{string1} is lexicographically greater than @var{string2}
+@item @var{string1} @code{>=} @var{string2}
+@var{string1} is lexicographically greater or equal than @var{string2}
+@item @var{integer1} @code{-eq} @var{integer2}
+@var{integer1} is equal to @var{integer2}
+@item @var{integer1} @code{-ge} @var{integer2}
+@var{integer1} is greater than or equal to @var{integer2}
+@item @var{integer1} @code{-gt} @var{integer2}
+@var{integer1} is greater than @var{integer2}
+@item @var{integer1} @code{-le} @var{integer2}
+@var{integer1} is less than or equal to @var{integer2}
+@item @var{integer1} @code{-lt} @var{integer2}
+@var{integer1} is less than @var{integer2}
+@item @var{integer1} @code{-ne} @var{integer2}
+@var{integer1} is not equal to @var{integer2}
+@item @var{prefix}@var{integer1} @code{-pgt} @var{prefix}@var{integer2}
+@var{integer1} is greater than @var{integer2} after stripping off common non-numeric @var{prefix}.
+@item @var{prefix}@var{integer1} @code{-plt} @var{prefix}@var{integer2}
+@var{integer1} is less than @var{integer2} after stripping off common non-numeric @var{prefix}.
+@item @var{file1} @code{-nt} @var{file2}
+@var{file1} is newer than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-nt} in which case it is added to the first file modification time.
+@item @var{file1} @code{-ot} @var{file2}
+@var{file1} is older than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-ot} in which case it is added to the first file modification time.
+@item @code{-d} @var{file}
+@var{file} exists and is a directory
+@item @code{-e} @var{file}
+@var{file} exists
+@item @code{-f} @var{file}
+@var{file} exists and is not a directory
+@item @code{-s} @var{file}
+@var{file} exists and has a size greater than zero
+@item @code{-n} @var{string}
+the length of @var{string} is nonzero
+@item @var{string}
+@var{string} is equivalent to @code{-n @var{string}}
+@item @code{-z} @var{string}
+the length of @var{string} is zero
+@item @code{(} @var{expression} @code{)}
+@var{expression} is true
+@item @code{!} @var{expression}
+@var{expression} is false
+@item @var{expression1} @code{-a} @var{expression2}
+both @var{expression1} and @var{expression2} are true
+@item @var{expression1} @code{-o} @var{expression2}
+either @var{expression1} or @var{expression2} is true
+@end table
+@end deffn
+
+
 @node true
 @subsection true
 
@@ -4207,6 +4518,25 @@ Unset the environment variable @var{envvar}.
 
 This command is not yet implemented for GRUB 2, although it is planned.
 
+
+@ignore
+@node vbeinfo
+@subsection vbeinfo
+
+@deffn Command vbeinfo [[WxH]xD]
+Alias for command @command{videoinfo} (@pxref{videoinfo}). It is available
+only on PC BIOS platforms.
+@end deffn
+@endignore
+
+
+@node videoinfo
+@subsection videoinfo
+
+@deffn Command videoinfo [[WxH]xD]
+List available video modes. If resolution is given, show only matching modes.
+@end deffn
+
 @node Internationalisation
 @chapter Charset
 GRUB uses UTF-8 internally other than in rendering where some GRUB-specific
@@ -4307,7 +4637,7 @@ Identifiers containing non-ASCII may work but aren't supported.
 Only the ASCII space characters (space U+0020, tab U+000b, CR U+000d and
 LF U+000a) are recognised. Other unicode space characters aren't a valid
 field separator.
-@command{test} tests <, >, <=, >=, -pgt and -plt compare the strings in the
+@command{test} (@pxref{test}) tests <, >, <=, >=, -pgt and -plt compare the strings in the
 lexicographical order of unicode codepoints, replicating the behaviour of
 test from coreutils.
 environment variables and commands are listed in the same order.
@@ -4765,8 +5095,8 @@ Installing to the whole disk device is normally more robust.
 @item
 Check that GRUB actually knows how to read from the device and file system
 containing @file{/boot/grub}.  It will not be able to read from encrypted
-devices, nor from file systems for which support has not yet been added to
-GRUB.
+devices with unsupported encryption scheme, nor from file systems for which
+support has not yet been added to GRUB.
 @end itemize
 
 
-- 
tg: (475ef5e..) u/cmd-doc (depends on: master)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Command documentation part 1.

[Vladimir 'φ-coder/phcoder' Serbinenko]

[-- Attachment #1: Type: text/plain, Size: 1479 bytes --]

On 10.03.2013 17:45, Andrey Borzenkov wrote:

>> > Also I think it's worth mentioning that luks/geli/... aren't autoloaded.
>> > 
> Is there any other encryption container that is currently supported? I
> see only LUKS and geli.

Currently only luks and geli

>>> > > +When option @option{--check} is given, it points to a file that contains
>>> > > +list of @var{hash name} pairs. File hash and file name are separated by
>>> > > +single @key{SPACE} or @key{TAB}, one pair on a line. Option @option{--prefix}
>>> > > +may be used to give directory where files are located. Hash verification
>>> > > +stops after the first mismatch was found unless option @option{--keep-going}
>>> > > +was given.
>>> > > +@end deffn
>> > 
>> > This is the same format as used by standard UNIX tools.
>> > 
> Not sure what change is needed so left alone :)

Just a mention that it's the same format as UNIX tools

> +@deffn Command background_color color
> +Set background color for active terminal. For valid color specifications see
> +@pxref{Theme file format, ,Colors}. Background color can be changed only when
> +using @samp{gfxterm} for terminal output.
> +@end deffn

There is a confusion between the background behind the letters
(background_color_normal/_highlight variables) and solid color used as
background image (background_color command). This description would
probably suggest former rather than the latter.

Other than this patch is good.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]

Re: Command documentation part 1.

[Andrey Borzenkov]

[-- Attachment #1: Type: text/plain, Size: 793 bytes --]

В Tue, 26 Mar 2013 11:48:37 +0100
Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:

> > +@deffn Command background_color color
> > +Set background color for active terminal. For valid color specifications see
> > +@pxref{Theme file format, ,Colors}. Background color can be changed only when
> > +using @samp{gfxterm} for terminal output.
> > +@end deffn
> 
> There is a confusion between the background behind the letters
> (background_color_normal/_highlight variables) and solid color used as
> background image (background_color command). This description would
> probably suggest former rather than the latter.
> 

I'm afraid this exceeds my language skills. This is called background
color for what I know. Any native English speaker to chime in?

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Command documentation part 1.

[Vladimir 'φ-coder/phcoder' Serbinenko]

[-- Attachment #1: Type: text/plain, Size: 1231 bytes --]

On 30.03.2013 09:46, Andrey Borzenkov wrote:

> В Tue, 26 Mar 2013 11:48:37 +0100
> Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:
> 
>>> +@deffn Command background_color color
>>> +Set background color for active terminal. For valid color specifications see
>>> +@pxref{Theme file format, ,Colors}. Background color can be changed only when
>>> +using @samp{gfxterm} for terminal output.
>>> +@end deffn
>>
>> There is a confusion between the background behind the letters
>> (background_color_normal/_highlight variables) and solid color used as
>> background image (background_color command). This description would
>> probably suggest former rather than the latter.
>>
> 
> I'm afraid this exceeds my language skills. This is called background
> color for what I know. Any native English speaker to chime in?
> 

I don't think it's about skills. It doesn't seem to be a clear term to
distinguish the both usages. I think a sentence explaining which colour
is meant is the best way to deal with the situation.

> 
> 
> _______________________________________________
> Grub-devel mailing list
> Grub-devel@gnu.org
> https://lists.gnu.org/mailman/listinfo/grub-devel




[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]

Re: Command documentation part 1.

[Andrey Borzenkov]

[-- Attachment #1: Type: text/plain, Size: 1817 bytes --]

В Wed, 03 Apr 2013 11:11:44 +0200
Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:

> On 30.03.2013 09:46, Andrey Borzenkov wrote:
> 
> > В Tue, 26 Mar 2013 11:48:37 +0100
> > Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:
> > 
> >>> +@deffn Command background_color color
> >>> +Set background color for active terminal. For valid color specifications see
> >>> +@pxref{Theme file format, ,Colors}. Background color can be changed only when
> >>> +using @samp{gfxterm} for terminal output.
> >>> +@end deffn
> >>
> >> There is a confusion between the background behind the letters
> >> (background_color_normal/_highlight variables) and solid color used as
> >> background image (background_color command). This description would
> >> probably suggest former rather than the latter.
> >>
> > 
> > I'm afraid this exceeds my language skills. This is called background
> > color for what I know. Any native English speaker to chime in?
> > 
> 
> I don't think it's about skills. It doesn't seem to be a clear term to
> distinguish the both usages. I think a sentence explaining which colour
> is meant is the best way to deal with the situation.
> 

Is it OK?

@@ -3483,6 +3483,10 @@ If @samp{superusers} is empty, this command returns true. @xref{Security}.
 Set background color for active terminal. For valid color specifications see
 @pxref{Theme file format, ,Colors}. Background color can be changed only when
 using @samp{gfxterm} for terminal output.
+
+This command sets color of empty areas without text. Text background color
+is controlled by environment variables @var{color_normal}, @var{color_highlight},
+@var{menu_color_normal}, @var{menu_color_highlight}. @xref{Special environment variables}.
 @end deffn
 
 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Command documentation part 1.

[Vladimir 'φ-coder/phcoder' Serbinenko]

[-- Attachment #1: Type: text/plain, Size: 2137 bytes --]

On 05.04.2013 09:41, Andrey Borzenkov wrote:

> В Wed, 03 Apr 2013 11:11:44 +0200
> Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:
> 
>> On 30.03.2013 09:46, Andrey Borzenkov wrote:
>>
>>> В Tue, 26 Mar 2013 11:48:37 +0100
>>> Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:
>>>
>>>>> +@deffn Command background_color color
>>>>> +Set background color for active terminal. For valid color specifications see
>>>>> +@pxref{Theme file format, ,Colors}. Background color can be changed only when
>>>>> +using @samp{gfxterm} for terminal output.
>>>>> +@end deffn
>>>>
>>>> There is a confusion between the background behind the letters
>>>> (background_color_normal/_highlight variables) and solid color used as
>>>> background image (background_color command). This description would
>>>> probably suggest former rather than the latter.
>>>>
>>>
>>> I'm afraid this exceeds my language skills. This is called background
>>> color for what I know. Any native English speaker to chime in?
>>>
>>
>> I don't think it's about skills. It doesn't seem to be a clear term to
>> distinguish the both usages. I think a sentence explaining which colour
>> is meant is the best way to deal with the situation.
>>
> 
> Is it OK?
> 
> @@ -3483,6 +3483,10 @@ If @samp{superusers} is empty, this command returns true. @xref{Security}.
>  Set background color for active terminal. For valid color specifications see
>  @pxref{Theme file format, ,Colors}. Background color can be changed only when
>  using @samp{gfxterm} for terminal output.
> +
> +This command sets color of empty areas without text. Text background color
> +is controlled by environment variables @var{color_normal}, @var{color_highlight},
> +@var{menu_color_normal}, @var{menu_color_highlight}. @xref{Special environment variables}.
>  @end deffn
> 

Yes. Could you send the patch as whole so I can commit it?

 
>  
> 
> 
> 
> _______________________________________________
> Grub-devel mailing list
> Grub-devel@gnu.org
> https://lists.gnu.org/mailman/listinfo/grub-devel




[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]

Re: Command documentation part 1.

[Andrey Borzenkov]

[-- Attachment #1: Type: text/plain, Size: 20237 bytes --]

В Fri, 05 Apr 2013 09:45:38 +0200
Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:

> 
> Yes. Could you send the patch as whole so I can commit it?
> 
>  

From: Andrey Borzenkov <arvidjaar@gmail.com>
Subject: [PATCH v4] document grub commands

Add documentation for more grub commands.

Signed-off-by: Andrey Borzenkov <arvidjaar@gmail.com>

---
 ChangeLog      |   4 +
 docs/grub.texi | 352 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 347 insertions(+), 9 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 400a071..519e251 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2013-04-03  Andrey Borzenkov <arvidjaar@gmail.com>
+
+	* docs/grub.texi: Document more user commands.
+
 2013-04-04  Vladimir Serbinenko  <phcoder@gmail.com>
 2013-04-04  Peter Jones <pjones@redhat.com>
 
diff --git a/docs/grub.texi b/docs/grub.texi
index 0b66827..807d5a1 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -1554,6 +1554,10 @@ Causes a function to exit with the return value specified by @code{n}.  If
 in the function body.  If used outside a function the return status is
 false.
 
+@item setparams [@code{arg}] @dots{}
+Replace positional parameters starting with @code{$1} with arguments to
+@command{setparams}.
+
 @item shift [@code{n}]
 The positional parameters from @code{n}+1 @dots{} are renamed to
 @code{$1}@dots{}.  Parameters represented by the numbers @code{$#} down to
@@ -1751,8 +1755,8 @@ Colors can be specified in several ways:
 The fonts GRUB uses ``PFF2 font format'' bitmap fonts.  Fonts are specified
 with full font names.  Currently there is no
 provision for a preference list of fonts, or deriving one font from another.
-Fonts are loaded with the ``loadfont'' command in GRUB.  To see the list of
-loaded fonts, execute the ``lsfonts'' command.  If there are too many fonts to
+Fonts are loaded with the ``loadfont'' command in GRUB (@ref{loadfont}).  To see the list of
+loaded fonts, execute the ``lsfonts'' command (@ref{lsfonts}).  If there are too many fonts to
 fit on screen, do ``set pager=1'' before executing ``lsfonts''.
 
 
@@ -3361,16 +3365,25 @@ you forget a command, you can run the command @command{help}
 (@pxref{help}).
 
 @menu
+* [::                           Check file types and compare values
 * acpi::                        Load ACPI tables
+* authenticate::                Check whether user is in user list
+* background_color::            Set background color for active terminal
+* background_image::            Load background image for active terminal
 * badram::                      Filter out bad regions of RAM
 * blocklist::                   Print a block list
 * boot::                        Start up your operating system
 * cat::                         Show the contents of a file
 * chainloader::                 Chain-load another boot loader
+* clear::                       Clear the screen
+* cmosclean::                   Clear bit in CMOS
+* cmosdump::                    Dump CMOS contents
+* cmostest::                    Test bit in CMOS
 * cmp::                         Compare two files
 * configfile::                  Load a configuration file
 * cpuid::                       Check for CPU features
-* crc::                         Calculate CRC32 checksums
+* crc::                         Compute or check CRC32 checksums
+* cryptomount::                 Mount a crypto device
 * date::                        Display or set current date and time
 * drivemap::                    Map a drive to another
 * echo::                        Display a line of text
@@ -3379,6 +3392,7 @@ you forget a command, you can run the command @command{help}
 * gettext::                     Translate a string
 * gptsync::                     Fill an MBR based on GPT entries
 * halt::                        Shut down your computer
+* hashsum::                     Compute or check hash checksum
 * help::                        Show help messages
 * initrd::                      Load a Linux initrd
 * initrd16::                    Load a Linux initrd (16-bit mode)
@@ -3387,29 +3401,50 @@ you forget a command, you can run the command @command{help}
 * linux::                       Load a Linux kernel
 * linux16::                     Load a Linux kernel (16-bit mode)
 * list_env::                    List variables in environment block
+* loadfont::                    Load font files
 * load_env::                    Load variables from environment block
 * loopback::                    Make a device from a filesystem image
 * ls::                          List devices or files
+* lsfonts::                     List loaded fonts
+* lsmod::                       Show loaded modules
+* md5sum::                      Compute or check MD5 hash
 * normal::                      Enter normal mode
 * normal_exit::                 Exit from normal mode
 * parttool::                    Modify partition table entries
 * password::                    Set a clear-text password
 * password_pbkdf2::             Set a hashed password
 * play::                        Play a tune
+* probe::                       Retrieve device info
 * pxe_unload::                  Unload the PXE environment
 * read::                        Read user input
 * reboot::                      Reboot your computer
+* regexp::                      Test if regular expression matches string
+* rmmod::                       Remove a module
 * save_env::                    Save variables to environment block
 * search::                      Search devices by file, label, or UUID
 * sendkey::                     Emulate keystrokes
 * set::                         Set an environment variable
+* sha1sum::                     Compute or check SHA1 hash
+* sha256sum::                   Compute or check SHA256 hash
+* sha512sum::                   Compute or check SHA512 hash
+* sleep::                       Wait for a specified number of seconds
 * source::                      Read a configuration file in same context
+* test::                        Check file types and compare values
 * true::                        Do nothing, successfully
 * unset::                       Unset an environment variable
 * uppermem::                    Set the upper memory size
+@comment * vbeinfo::                     List available video modes
+* videoinfo::                   List available video modes
 @end menu
 
 
+@node [
+@subsection [
+@deffn Command @code{[} expression @code{]}
+Alias for @code{test @var{expression}} (@pxref{test}).
+@end deffn
+
+
 @node acpi
 @subsection acpi
 
@@ -3431,6 +3466,42 @@ Normally, this command will replace the Root System Description Pointer
 GRUB, but may be used by GRUB's EFI emulation.
 @end deffn
 
+
+@node authenticate
+@subsection authenticate
+@deffn Command authenticate [userlist]
+Check whether user is in @var{userlist} or listed in the value of variable
+@samp{superusers}. See @pxref{superusers} for valid user list format.
+If @samp{superusers} is empty, this command returns true. @xref{Security}.
+@end deffn
+
+
+@node background_color
+@subsection background_color
+
+@deffn Command background_color color
+Set background color for active terminal. For valid color specifications see
+@pxref{Theme file format, ,Colors}. Background color can be changed only when
+using @samp{gfxterm} for terminal output.
+
+This command sets color of empty areas without text. Text background color
+is controlled by environment variables @var{color_normal}, @var{color_highlight},
+@var{menu_color_normal}, @var{menu_color_highlight}. @xref{Special environment variables}.
+@end deffn
+
+
+@node background_image
+@subsection background_image
+
+@deffn Command background_image [[@option{--mode} @samp{stretch}|@samp{normal}] file]
+Load background image for active terminal from @var{file}. Image is stretched
+to fill up entire screen unless option @option{--mode} @samp{normal} is given.
+Without arguments remove currently loaded background image. Background image
+can be changed only when using @samp{gfxterm} for terminal output.
+
+@end deffn
+
+
 @node badram
 @subsection badram
 
@@ -3503,6 +3574,42 @@ load a defective boot loader, such as SCO UnixWare 7.1.
 @end deffn
 
 
+@node clear
+@subsection clear
+
+@deffn Command clear
+Clear the screen.
+@end deffn
+
+
+@node cmosclean
+@subsection cmosclean
+
+@deffn Command cmosclean byte:bit
+Clear value of bit in CMOS at location @var{byte}:@var{bit}. This command
+is available only on platforms that support CMOS.
+@end deffn
+
+
+@node cmosdump
+@subsection cmosdump
+
+@deffn Dump CMOS contents
+Dump full CMOS contents as hexadecimal values. This command is available only
+on platforms that support CMOS.
+@end deffn
+
+
+@node cmostest
+@subsection cmostest
+
+@deffn Command cmostest byte:bit
+Test value of bit in CMOS at location @var{byte}:@var{bit}. Exit status
+is zero if bit is set, non zero otherwise. This command is available only
+on platforms that support CMOS.
+@end deffn
+
+
 @node cmp
 @subsection cmp
 
@@ -3553,8 +3660,24 @@ invoked with @option{-l}.  This may change in the future.
 @node crc
 @subsection crc
 
-@deffn Command crc file
-Display the CRC32 checksum of @var{file}.
+@deffn Command crc arg @dots{}
+Alias for @code{hashsum --hash crc32 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node cryptomount
+@subsection cryptomount
+
+@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
+Setup access to encrypted device. If necessary, passphrase
+is requested interactively. Option @var{device} configures specific grub device
+(@pxref{Naming convention}); option @option{-u} @var{uuid} configures device
+with specified @var{uuid}; option @option{-a} configures all detected encrypted
+devices; option @option{-b} configures all geli containers that have boot flag set.
+
+GRUB suports devices encrypted using LUKS and geli. Note that necessary modules (@var{luks} and @var{geli}) have to be loaded manually before this command can
+be used.
 @end deffn
 
 
@@ -3700,6 +3823,29 @@ is shut down using APM.
 @end deffn
 
 
+@node hashsum
+@subsection hashsum
+
+@deffn Command hashsum @option{--hash} hash @option{--keep-going} @option{--uncompress} @option{--check} file [@option{--prefix} dir]|file @dots{}
+Compute or verify file hashes. Hash type is selected with option @option{--hash}.
+Supported hashes are: @samp{adler32}, @samp{crc64}, @samp{crc32},
+@samp{crc32rfc1510}, @samp{crc24rfc2440}, @samp{md4}, @samp{md5},
+@samp{ripemd160}, @samp{sha1}, @samp{sha224}, @samp{sha256}, @samp{sha512},
+@samp{sha384}, @samp{tiger192}, @samp{tiger}, @samp{tiger2}, @samp{whirlpool}.
+Option @option{--uncompress} uncompresses files before computing hash.
+
+When list of files is given, hash of each file is computed and printed,
+followed by file name, each file on a new line.
+
+When option @option{--check} is given, it points to a file that contains
+list of @var{hash name} pairs in the same format as used by UNIX
+@command{md5sum} command. Option @option{--prefix}
+may be used to give directory where files are located. Hash verification
+stops after the first mismatch was found unless option @option{--keep-going}
+was given.
+@end deffn
+
+
 @node help
 @subsection help
 
@@ -3818,6 +3964,16 @@ block.
 @end deffn
 
 
+@node loadfont
+@subsection loadfont
+
+@deffn Command loadfont file @dots{}
+Load specified font files. Unless absolute pathname is given, @var{file}
+is assumed to be in directory @samp{$prefix/fonts} with
+suffix @samp{.pf2} appended. @xref{Theme file format,,Fonts}.
+@end deffn
+
+
 @node loopback
 @subsection loopback
 
@@ -3851,6 +4007,31 @@ name syntax}), then list the contents of that directory.
 @end deffn
 
 
+@node lsfonts
+@subsection lsfonts
+
+@deffn Command lsfonts
+List loaded fonts.
+@end deffn
+
+
+@node lsmod
+@subsection lsmod
+
+@deffn Command lsmod
+Show list of loaded modules.
+@end deffn
+
+
+@node md5sum
+@subsection md5sum
+
+@deffn Command md5sum arg @dots{}
+Alias for @code{hashsum --hash md5 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
 @node normal
 @subsection normal
 
@@ -3936,7 +4117,7 @@ to generate password hashes.  @xref{Security}.
 @node play
 @subsection play
 
-@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] ...
+@deffn Command play file | tempo [pitch1 duration1] [pitch2 duration2] @dots{}
 Plays a tune
 
 If the argument is a file name (@pxref{File name syntax}), play the tune
@@ -3952,6 +4133,15 @@ a rest.
 @end deffn
 
 
+@node probe
+@subsection probe
+
+@deffn Command probe [@option{--set} var] @option{--driver}|@option{--partmap}|@option{--fs}|@option{--fs-uuid}|@option{--label} device
+Retrieve device information. If option @option{--set} is given, assign result
+to variable @var{var}, otherwise print information on the screen.
+@end deffn
+
+
 @node pxe_unload
 @subsection pxe_unload
 
@@ -3980,6 +4170,26 @@ Reboot the computer.
 @end deffn
 
 
+@node regexp
+@subsection regexp
+
+@deffn Command regexp [@option{--set} [number:]var] regexp string
+Test if regular expression @var{regexp} matches @var{string}. Supported
+regular expressions are POSIX.2 Extended Regular Expressions. If option
+@option{--set} is given, store @var{number}th matched subexpression in
+variable @var{var}. Subexpressions are numbered in order of their opening
+parentheses starting from @samp{1}.  @var{number} defaults to @samp{1}.
+@end deffn
+
+
+@node rmmod
+@subsection rmmod
+
+@deffn Command rmmod module
+Remove a loaded @var{module}.
+@end deffn
+
+
 @node save_env
 @subsection save_env
 
@@ -4172,6 +4382,43 @@ arguments, print all environment variables with their values.
 @end deffn
 
 
+@node sha1sum
+@subsection sha1sum
+
+@deffn Command sha1sum arg @dots{}
+Alias for @code{hashsum --hash sha1 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sha256sum
+@subsection sha256sum
+
+@deffn Command sha256sum arg @dots{}
+Alias for @code{hashsum --hash sha256 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sha512sum
+@subsection sha512sum
+
+@deffn Command sha512sum arg @dots{}
+Alias for @code{hashsum --hash sha512 arg @dots{}}. See command @command{hashsum}
+(@pxref{hashsum}) for full description.
+@end deffn
+
+
+@node sleep
+@subsection sleep
+
+@deffn Command sleep [@option{--verbose}] [@option{--interruptible}] count
+Sleep for @var{count} seconds. If option @option{--interruptible} is given,
+allow @key{ESC} to interrupt sleep. With @option{--verbose} show countdown
+of remaining seconds.
+@end deffn
+
+
 @node source
 @subsection source
 
@@ -4185,6 +4432,74 @@ will not be shown immediately.
 @end deffn
 
 
+@node test
+@subsection test
+
+@deffn Command test expression
+Evaluate @var{expression} and return zero exit status if result is true,
+non zero status otherwise.
+
+@var{expression} is one of:
+
+@table @asis
+@item @var{string1} @code{==} @var{string2}
+the strings are equal
+@item @var{string1} @code{!=} @var{string2}
+the strings are not equal
+@item @var{string1} @code{<} @var{string2}
+@var{string1} is lexicographically less than @var{string2}
+@item @var{string1} @code{<=} @var{string2}
+@var{string1} is lexicographically less or equal than @var{string2}
+@item @var{string1} @code{>} @var{string2}
+@var{string1} is lexicographically greater than @var{string2}
+@item @var{string1} @code{>=} @var{string2}
+@var{string1} is lexicographically greater or equal than @var{string2}
+@item @var{integer1} @code{-eq} @var{integer2}
+@var{integer1} is equal to @var{integer2}
+@item @var{integer1} @code{-ge} @var{integer2}
+@var{integer1} is greater than or equal to @var{integer2}
+@item @var{integer1} @code{-gt} @var{integer2}
+@var{integer1} is greater than @var{integer2}
+@item @var{integer1} @code{-le} @var{integer2}
+@var{integer1} is less than or equal to @var{integer2}
+@item @var{integer1} @code{-lt} @var{integer2}
+@var{integer1} is less than @var{integer2}
+@item @var{integer1} @code{-ne} @var{integer2}
+@var{integer1} is not equal to @var{integer2}
+@item @var{prefix}@var{integer1} @code{-pgt} @var{prefix}@var{integer2}
+@var{integer1} is greater than @var{integer2} after stripping off common non-numeric @var{prefix}.
+@item @var{prefix}@var{integer1} @code{-plt} @var{prefix}@var{integer2}
+@var{integer1} is less than @var{integer2} after stripping off common non-numeric @var{prefix}.
+@item @var{file1} @code{-nt} @var{file2}
+@var{file1} is newer than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-nt} in which case it is added to the first file modification time.
+@item @var{file1} @code{-ot} @var{file2}
+@var{file1} is older than @var{file2} (modification time). Optionally numeric @var{bias} may be directly appended to @code{-ot} in which case it is added to the first file modification time.
+@item @code{-d} @var{file}
+@var{file} exists and is a directory
+@item @code{-e} @var{file}
+@var{file} exists
+@item @code{-f} @var{file}
+@var{file} exists and is not a directory
+@item @code{-s} @var{file}
+@var{file} exists and has a size greater than zero
+@item @code{-n} @var{string}
+the length of @var{string} is nonzero
+@item @var{string}
+@var{string} is equivalent to @code{-n @var{string}}
+@item @code{-z} @var{string}
+the length of @var{string} is zero
+@item @code{(} @var{expression} @code{)}
+@var{expression} is true
+@item @code{!} @var{expression}
+@var{expression} is false
+@item @var{expression1} @code{-a} @var{expression2}
+both @var{expression1} and @var{expression2} are true
+@item @var{expression1} @code{-o} @var{expression2}
+either @var{expression1} or @var{expression2} is true
+@end table
+@end deffn
+
+
 @node true
 @subsection true
 
@@ -4207,6 +4522,25 @@ Unset the environment variable @var{envvar}.
 
 This command is not yet implemented for GRUB 2, although it is planned.
 
+
+@ignore
+@node vbeinfo
+@subsection vbeinfo
+
+@deffn Command vbeinfo [[WxH]xD]
+Alias for command @command{videoinfo} (@pxref{videoinfo}). It is available
+only on PC BIOS platforms.
+@end deffn
+@end ignore
+
+
+@node videoinfo
+@subsection videoinfo
+
+@deffn Command videoinfo [[WxH]xD]
+List available video modes. If resolution is given, show only matching modes.
+@end deffn
+
 @node Internationalisation
 @chapter Charset
 GRUB uses UTF-8 internally other than in rendering where some GRUB-specific
@@ -4307,7 +4641,7 @@ Identifiers containing non-ASCII may work but aren't supported.
 Only the ASCII space characters (space U+0020, tab U+000b, CR U+000d and
 LF U+000a) are recognised. Other unicode space characters aren't a valid
 field separator.
-@command{test} tests <, >, <=, >=, -pgt and -plt compare the strings in the
+@command{test} (@pxref{test}) tests <, >, <=, >=, -pgt and -plt compare the strings in the
 lexicographical order of unicode codepoints, replicating the behaviour of
 test from coreutils.
 environment variables and commands are listed in the same order.
@@ -4765,8 +5099,8 @@ Installing to the whole disk device is normally more robust.
 @item
 Check that GRUB actually knows how to read from the device and file system
 containing @file{/boot/grub}.  It will not be able to read from encrypted
-devices, nor from file systems for which support has not yet been added to
-GRUB.
+devices with unsupported encryption scheme, nor from file systems for which
+support has not yet been added to GRUB.
 @end itemize
 
 
-- 
tg: (f3399bf..) u/cmd-doc (depends on: master)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]