docs/130482: misleading loader documentation in handbook

[Ben Kaduk]

>Number:         130482
>Category:       docs
>Synopsis:       misleading loader documentation in handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Jan 13 02:30:03 UTC 2009
>Closed-Date:
>Last-Modified:
>Originator:     Ben Kaduk
>Release:        7.1-PRERELEASE
>Organization:
MIT SIPB
>Environment:
FreeBSD periphrasis.mit.edu 7.1-PRERELEASE FreeBSD 7.1-PRERELEASE #5: Sat Jan 3 17:44:27 EST 2009     kadku at periphrasis.mit.edu:/usr/obj/usr/src/sys/PERIPHRASIS amd64
>Description:
The handbook chapter on the Boot Manager and boot stages includes section 12.3.3.2 describing the loader built-in commands.  The description for the 'boot' command describes the optional kernelname parameter, but does not mention that this parameter is overrided if there is already a kernel image loaded.
(The correct procedure to boot a different kernel is mentioned later in the page, though.)
>How-To-Repeat:
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/boot-blocks.html
>Fix:
The patch available here is also inlined below:
http://stuff.mit.edu/afs/sipb.mit.edu/user/kaduk/freebsd/patches/chapter.boot.diff.20090112


--------------- begin patch here --------------
--- chapter.sgml.orig   Mon Jan 12 21:13:56 2009
+++ chapter.sgml        Mon Jan 12 21:18:37 2009
@@ -343,7 +343,10 @@
          <listitem>
            <para>Immediately proceeds to boot the kernel, with the
              given options, if any, and with the kernel name given,
-             if it is.</para>
+             if it is.  Providing a kernel name on the command-line
+             is only applicable after an <term>unlad</term> command
+             has been issued, otherwise the previously-loaded kernel
+             will be used.</para>
          </listitem>
        </varlistentry>


>Release-Note:
>Audit-Trail:
>Unformatted: