Date: Tue, 15 Nov 2011 20:10:03 GMT From: "r. clayton" <rvclayton@acm.org> To: freebsd-gnats-submit@FreeBSD.org Subject: docs/162597: Handbook section 12.14.3 example unclear. Message-ID: <201111152010.pAFKA3D6049769@red.freebsd.org> Resent-Message-ID: <201111152020.pAFKK4s8064939@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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@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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201111152010.pAFKA3D6049769>