patch to document boot program

[James A Morrison]

2002-02-11     James A. Morrison  <ja2morri@student.math.uwaterloo.ca>

         * hurd.texi: Document boot program, added Invoking boot section

Index: hurd.texi
===================================================================
RCS file: /cvsroot/hurd/hurd/doc/hurd.texi,v
retrieving revision 1.20
diff -u -r1.20 hurd.texi
--- hurd.texi   12 Mar 2001 00:43:50 -0000      1.20
+++ hurd.texi   9 Feb 2002 22:34:29 -0000
@@ -199,6 +199,7 @@
 * Invoking serverboot::         Starting a set of interdependent servers.
 * Boot Scripts::                Describing server bootstrap relationships.
 * Recursive Bootstrap::         Running a Hurd under another Hurd.
+* Invoking boot::               How to use the boot program.
 
 Foundations

@@ -680,12 +681,16 @@
 @section Server Bootstrap
 @pindex serverboot
 
+The @code{serverboot} program has been deprecated but it is still possible
+to boot the Hurd using @code{serverboot} instead of booting the Hurd directly. 
+
 The @code{serverboot} program is responsible for loading and executing
 the rest of the Hurd servers.  Rather than containing specific
 instructions for starting the Hurd, it follows general steps given in a
 user-supplied boot script.
 
-To boot the Hurd, the microkernel must start @code{serverboot} as its
+To boot the Hurd using @code{serverboot}, the microkernel must start 
+@code{serverboot} as its
 first task, and pass it appropriate arguments.  @code{serverboot} has a
 counterpart, called @code{boot}, which can be invoked while the Hurd is
 already running, and allows users to start their own complete sub-Hurds
@@ -695,6 +700,7 @@
 * Invoking serverboot::         Starting a set of interdependent servers.
 * Boot Scripts::                Describing server bootstrap relationships.
 * Recursive Bootstrap::         Running a Hurd under another Hurd.
+* Invoking boot::               How to use the boot program.
 @end menu
 
 
@@ -744,6 +750,11 @@
 @pindex /boot/servers.boot
 @pindex servers.boot
 
+Boot Scripts are used to boot sub-hurds, and parsed by @code{serverboot} to
+boot the Hurd.  Boot scripts are simply a selection of command lines using
+@code{#}'s to denote comments.  See @file{/boot/servers.boot} for an example
+of a Hurd boot script.
+
 FIXME: finish
 
 
@@ -762,6 +773,9 @@
 far-reaching effects, and so it is nice to be able to test those effects
 without having to reboot the machine.
 
+This feature can also be used to test another Hurd installation.  This 
+situation is illustrated in the second example.
+
 @c FIXME: `boot' synopsis
 
 Here are the steps you can follow to test out a new set of servers:
@@ -810,7 +824,7 @@
 $ @kbd{cd my-root}
 $ @kbd{tar -zxpf /pub/debian/FIXME/gnu-20000929.tar.gz}
 $ @kbd{cd ..}
-$ @kbd{fsysopts ./my-root --read-only}
+$ @kbd{fsysopts ./my-root --readonly}
 $
 @end example
 
@@ -824,6 +838,19 @@
 $ @kbd{boot -D ./my-boot ./my-boot/boot/servers.boot ./my-partition}
 [...]
 @end example
+
+@item
+ Here is an example using a hard drive that already has GNU Hurd installed.
+Assuming that the Hurd is installed on and extended 2 filesystem on /dev/hd2s1.
+
+@example
+$ @kbd{settrans /mnt /hurd/ex2fs --readonly /dev/hd2s1}
+$ @kbd{boot -d -D /mnt -I /mnt/boot/servers.boot /dev/hd2s1}
+@end example
+
+@item
+ See @pxref{boot Options} for help with boot.
+ 
 @end enumerate
 
 Note that it is impossible to share microkernel devices between the two
@@ -844,6 +871,63 @@
 safe place to overwrite your old Hurd with the new one, and reboot back
 to your old configuration (with the new Hurd servers).
 
+@node Invoking boot 
+@section Invoking boot 
+@menu
+* boot Options::                Boot program command line options
+@end menu
+
+@node Boot bptions
+@subsection boot Options
+
+Usage: boot [@var{option}@dots{}] @var{boot-script} @var{device}@dots{}
+
+@table @code
+@item --kernel-command-line=@var{command line}
+@itemx -c
+Simulated multiboot command line to supply
+
+@item --pause
+@itemx -d
+Pause for user confirmation at various times during booting
+
+@item --boot-root=@var{dir}
+@itemx -D
+Root of a directory tree in which to find files specified in @var{boot-script}
+
+@item --interleave=@var{blocks}    
+Interleave in runs of length @var{blocks}
+
+@item --isig
+@itemx -I
+Do not disable terminal signals, so you can suspend and interrupt boot.
+
+@item --layer
+@itemx -L                
+ Layer multiple devices for redundancy
+
+@item --single-user
+@itemx -s          
+ Boot in single user mode
+
+@item --store-type=@var{type}
+@itemx -T
+Each @var{device} names a store of type @var{type}
+
+@item --help
+@itemx -?
+Gives a help list
+
+@item --usage
+Give a short usage message
+@end table
+
+Mandatory or optional arguments to long options are also mandatory or optional
+for any corresponding short options.
+
+If neither @option{--interleave} or @option{--layer} is specified, multiple 
+@var{device}s are concatenated.
+
 
 @node Shutdown
 @section Shutdown