patch for the commands chapter

[Alessandro Rubini]

The patch cleans up and completes the "Commands" chapter. The clean up
is in explaining more clearly what the three groups of commands are (I
didn't understand at a first reading), and some minor rewording were I
was sure the text was worse than it could be -- I'm not a native
speaker, either.

The commands that were missing are: debug halt hiddenmenu partnew
parttype reboot savedefault serial terminal.

I also marked all the commands that are only available in certain
conditions.

There is a serious problem with "serial" in my opinion. Why does it
wait for user input? This is definitely policy, and a bad one, in my
opinion. A serial console should not be treated differently from a
"keyboard-and-monitor" one. I didn't document this misfeature, hoping
it will go away before release.

The documentation of "setup" isn't up to date. And I didn't check all
the commands. Now I resign and go to bed.

There are a few glitches in the formatting. But now I am by modem with no
fast access to a place where I can compile and preview the docs.

Please commit to both branches, as I lost my gnu password and can't commit
myself even if this is approved.

/alessnadro


Index: docs/user-ref.texi
===================================================================
RCS file: /cvs/grub/docs/user-ref.texi,v
retrieving revision 1.29.2.2
diff -u -r1.29.2.2 user-ref.texi
--- docs/docs/user-ref.texi     2000/10/05 17:10:17     1.29.2.2
+++ docs/docs/user-ref.texi     2000/10/05 23:58:17
@@ -430,20 +430,24 @@
 @node Commands
 @chapter The list of available commands
 
-In this chapter, we list the available commands, both in the
-configuration file and in the command line.
+In this chapter, we list all commands that are available in GRUB.
 
+Commands belong to different groups. A few can only be used in
+the global section of the configuration file (or ``menu''); most
+of them can be entered on the command line and can be either used
+in the menu or in the menu entries.
+
 @menu
 * Menu-specific commands::
-* General commands::
-* Command-line-specific commands::
+* Command-line and menu commands::
+* Command-line and menu entry commands::
 @end menu
 
 
 @node Menu-specific commands
 @section The list of commands for the menu only
 
-The semantics are as follows:
+The semantics used in parsing the configuration file are the following:
 
 @itemize @bullet
 @item
@@ -464,29 +468,37 @@
 must be preceded by @samp{0x}, and is case-insensitive.
 
 @item
-Extra options or text at the end of the line is ignored unless otherwise
+Extra options or words at the end of the line are ignored unless otherwise
 specified.
 
 @item
-Bad commands are added to the current entry, except before entries
+Unrecognized commands are added to the current entry, except before entries
 start, where they are ignored.
 @end itemize
 
-Commands usable in the menu only.
+These are the commands that can only be used in the menu:
 
 @deffn Command default num
-Set the default entry to the entry number @var{num} (if not specified,
-it is 0, the first entry).
+Set the default entry to the entry number @var{num}. Numbering starts
+from 0, and entry number 0 is the default if the command is not used.
 @end deffn
 
 @deffn Command fallback num
 Go into unattended boot mode: if the default boot entry has any errors,
-instead of waiting for the user to do anything, it immediately starts
+instead of waiting for the user to do anything, immediately start
 over using the @var{num} entry (same numbering as the @code{default}
 command). This obviously won't help if the machine was rebooted by a
 kernel that GRUB loaded.
 @end deffn
 
address@hidden Command hiddenmenu
+Don't display the menu. If the command is used, no menu will be
+displayed on the control terminal, and the default entry will be
+booted after the timeout expired. The user can still request the
+menu to be displayed by pressing @key{ESC} before the timeout
+expires.
address@hidden deffn
+
 @deffn Command password passwd [new-config-file]
 Disable all interactive editing control (menu entry editor and
 command line) and entries protected by the command @command{lock}. If
@@ -507,13 +519,14 @@
 @end deffn
 
 
address@hidden General commands
address@hidden The list of general commands
address@hidden Command-line and menu commands::
address@hidden The list of command-line and menu commands
 
 Commands usable both in the menu and in the command line.
 
 @deffn Command bootp
-Initialize a network device via the @dfn{BOOTP} protocol.
+Initialize a network device via the @dfn{BOOTP} protocol. The command
+is only available if GRUB is compiled with netboot support.
 @end deffn
 
 @deffn Command color normal [highlight]
@@ -611,20 +624,56 @@
 @end deffn
 
 @deffn Command dhcp
-Initialize a network device via the @dfn{DHCP} protocol. At the moment,
-this command is just an alias for @command{bootp}.
+Initialize a network device via the @dfn{DHCP} protocol. Currently,
+this command is just an alias for @command{bootp},  since the two
+protocols are very similar. The command
+is only available if GRUB is compiled with netboot support.
 @end deffn
 
 @deffn Command hide partition
 Hide @var{partition} by setting the @dfn{hidden} bit in its partition
-type code. This is useful only for DOS or Windows when multiple primary
-partitions exist in one disk.
+type code. This is useful only when booting DOS or Windows
+and multiple primary FAT partitions exist in one disk.
address@hidden deffn
+
address@hidden Command part_new part type from to
+Create a new primary partition. @var{part} is a partition specification
+in GRUB syntax (@pxref{Naming convention}); @var{type} is the partition
+type and must be a number in the range 0-0xff; @var{from} and @var{to}
+are the starting and ending sectors, expresses as an absolute sector
+number.
address@hidden deffn
+
address@hidden Command part_type part type
+Change the type of an existing partition.  @var{part} is a partition
+specification in GRUB syntax (@pxref{Naming convention}); @var{type}
+is the new partition type and must be a number in the range 0-0xff.
 @end deffn
 
 @deffn Command rarp
-Initialize a network device via the @dfn{RARP} protocol.
+Initialize a network device via the @dfn{RARP} protocol.  The command
+is only available if GRUB is compiled with netboot support.
 @end deffn
 
address@hidden Command serial address@hidden address@hidden address@hidden 
address@hidden address@hidden address@hidden address@hidden
+Initialize a serial device. @var{unit} is a number in the range 0-3
+specifying which serial port to use; default is 0, that corresponds
+the port often called COM1. @var{port} is the I/O port where the UART
+is to be found; if specified it takes precedence over @var{unit}.
address@hidden is the transmission speed; default is 9600. @var{word} and
address@hidden are the number of data bits and stop bits. Data bits must
+be in the range 5-8 and stop bits are 1 or 2. Default is 8 data bits
+and one stop bit. @var{parity} is one of @option{no}, @option{odd},
address@hidden and defaults to @option{no}. The option @option{--device}
+can only be used in the grub shell and is used to specify the 
+tty device to be used in the host Operating System.
+
+The serial port is not used as a communication channel unless the
address@hidden command is used.
+
+The command is only available if GRUB is compiled with serial support.
address@hidden deffn
+
 @deffn Command setkey to_key from_key
 Change the keyboard map. The key @var{from_key} is mapped to the key
 @var{to_key}. Note that this command @emph{does not} exchange the
@@ -752,24 +801,35 @@
 @end table
 @end deffn
 
address@hidden Command terminal address@hidden address@hidden [console] 
[serial]"
+Select a terminal for user interaction. The terminal is assumed to be
+vt100 compatible unless @option{--dump} is specified. If both
address@hidden and @option{serial} are specified, then GRUB will use
+the one where a key is entered first. If neither are specified, the
+current setting is reported. Default is @option{console}.
+The command is only available if GRUB is compiled with serial support.
address@hidden deffn
+
+
 @deffn Command tftpserver ipaddr
 Override a TFTP server address returned by a BOOTP/DHCP/RARP server. The
 argument @var{ipaddr} must be in dotted decimal format, like
address@hidden
address@hidden The command
+is only available if GRUB is compiled with netboot support.
 @end deffn
 
 @deffn Command unhide partition
 Unhide @var{partition} by clearing the @dfn{hidden} bit in its partition
-type code. This is useful only for DOS or Windows when multiple primary
+type code. This is useful only when booting DOS or Windows and multiple primary
 partitions exist in one disk.
 @end deffn
 
 
address@hidden Command-line-specific commands
address@hidden The list of commands in the command line
address@hidden Command-line and menu entry commands
address@hidden The list of command-line and menu entry commands.
 
-These commands are usable only in the command line and in menu entries.
-If you forget some command, run the command @command{help}.
+These commands are usable in the command line and in menu entries.
+If you forget some command, you can run the command @command{help}.
 
 @deffn Command blocklist file
 Print the blocklist notation of the file @var{file} (@pxref{Blocklist
@@ -777,9 +837,9 @@
 @end deffn
 
 @deffn Command boot
-This boots the OS/chain-loader which has been loaded. Only necessary if
+Boot the OS/chain-loader which has been loaded. Only needed if
 running the fully interactive command line (it is implicit at the end of
-a config-file entry).
+a menu entry).
 @end deffn
 
 @deffn Command cat file
@@ -822,6 +882,12 @@
 Load @var{file} as a configuration file.
 @end deffn
 
address@hidden Command debug
+Toggle debug mode. By default it is off. When debug mode is active,
+some extra messages are printed to show disk activity. The global
+debug flag is mainly useful for GRUB developers when testing new code.
address@hidden deffn
+
 @deffn Command embed stage1_5 device
 Embed the Stage 1.5 @var{stage1_5} in the sectors after the MBR if
 @var{device} is a drive, or in the @dfn{boot loader} area if @var{device}
@@ -869,11 +935,18 @@
 based on the C/H/S values automatically.
 @end deffn
 
address@hidden Command halt @option{--no-apm}
+The commands halts the computer. If the @option{--no-apm} option
+is specified, no APM BIOS call is performed. Otherwise, the computer
+is shut down using APM.
address@hidden deffn
+
 @deffn Command help [pattern @dots{}]
 Display helpful information about builtin commands. If you do not
-specify @var{pattern}, this command lists the short documents of all
+specify @var{pattern}, this command lists short information about all
 available commands, and, if you specify one or more @var{pattern}s, it
-displays long documents of the commands which match @var{pattern}(s).
+displays longer information about each of the commands
+that match @var{pattern}(s).
 @end deffn
 
 @deffn Command impsprobe
@@ -960,7 +1033,7 @@
 the command @command{password} if you really want this command to be
 useful.
 
-This command will be used like this example:
+This command will be used in a menu as shown in this example:
 
 @example
 title This is a too dangerous entry to be executed by normal users
@@ -1015,6 +1088,10 @@
 shell}). This command can be used only in the grub shell.
 @end deffn
 
address@hidden Command reboot
+Reboot the computer.
address@hidden deffn
+
 @deffn Command read addr
 Read a 32-bit value from memory at address @var{addr} and display it in
 hex format.
@@ -1039,6 +1116,10 @@
 disk that GRUB can read, but setting the correct root device is still
 desired. Note that the items mentioned in @command{root} above which
 derived from attempting the mount will @emph{not} work correctly.
address@hidden deffn
+
address@hidden Command savedefault
+Save the current menu entry as default entry.
 @end deffn
 
 @deffn Command setup address@hidden install_device [image_device]
Index: ChangeLog
===================================================================
RCS file: /cvs/grub/ChangeLog,v
retrieving revision 1.326.2.7
diff -u -r1.326.2.7 ChangeLog
--- ChangeLog   2000/10/05 17:12:39     1.326.2.7
+++ ChangeLog   2000/10/06 00:00:30
@@ -1,3 +1,8 @@
+2000-10-06  Alessandro Rubini  <address@hidden>
+
+       * docs/user-ref.texi (Commands): Added missing commands and
+       reworded part of the text.
+
 2000-10-05  Gordon Matzigkeit  <address@hidden>
 
        * stage2/disk_io.c (real_open_partition): Make sure that buf_geom