docs/162597: Handbook section 12.14.3 example unclear.

[r. clayton]

>Number:         162597
>Category:       docs
>Synopsis:       Handbook section 12.14.3 example unclear.
>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 Nov 15 20:20:03 UTC 2011
>Closed-Date:
>Last-Modified:
>Originator:     r. clayton
>Release:        8.2
>Organization:
>Environment:
FreeBSD AddisAbaba.hhadmin 8.2-RELEASE-p3 FreeBSD 8.2-RELEASE-p3 #0: Tue Sep 27 18:07:27 UTC 2011 root at i386-builder.daemonology.net:/usr/obj/usr/src/sys/GENERIC  i386

>Description:
Example 12-1, Creating a Swapfile on FreeBSD, in section 12.14.3, Swapfiles, starts off with

  1. Be certain that your kernel configuration includes the memory disk driver 
     (md(4)). It is default in GENERIC kernel.

       device   md   # Memory "disks"

I found this unclear for at least two reasons:

  It doesn't say how to be certain your kernal configuration includes the memory 
  disk driver.  The call-out box indicates what to look for, but it doesn't 
  indicate where to look (note I had to guess at what the call-out box text   
  meant; the example doesn't explain).  After futzing around with "kernel
  configuration" I eventually ended up at /usr/src/sys/i386/conf/GENERIC .

  The example describes (more or less) what you should do, but it doesn't say
  what you should do if your attempt to do (in this case, verify the memory disk
  driver) fails.

If you want to argue that none of this matters because md is included by default in GENERIC, then the text is still unclear:  why bring it up at all?  Just delete step 1 and start at step 2.
>How-To-Repeat:
See http://www.freebsd.org/doc/handbook/adding-swap-space.html
>Fix:
Replace the call-out box text with something like:

  $ grep md.*Memory /usr/src/sys/i386/conf/GENERIC
  device          md              # Memory "disks"

  $

Now all is revealed: what to do, where to do it, and what to look for.  There are a few problems - the example's architecture specific, the grep pattern may match other entries, and this may not be the recommended way to check for kernel features - but these problems are easily fixed.

I don't have any suggestions for handling the case when the example fails because I don't know what to do in that case.

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