From nobody@FreeBSD.org  Tue Nov 15 20:10:03 2011
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id C6F621065672
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 15 Nov 2011 20:10:03 +0000 (UTC)
	(envelope-from nobody@FreeBSD.org)
Received: from red.freebsd.org (red.freebsd.org [IPv6:2001:4f8:fff6::22])
	by mx1.freebsd.org (Postfix) with ESMTP id 961B38FC0C
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 15 Nov 2011 20:10:03 +0000 (UTC)
Received: from red.freebsd.org (localhost [127.0.0.1])
	by red.freebsd.org (8.14.4/8.14.4) with ESMTP id pAFKA3la049771
	for <freebsd-gnats-submit@FreeBSD.org>; Tue, 15 Nov 2011 20:10:03 GMT
	(envelope-from nobody@red.freebsd.org)
Received: (from nobody@localhost)
	by red.freebsd.org (8.14.4/8.14.4/Submit) id pAFKA3D6049769;
	Tue, 15 Nov 2011 20:10:03 GMT
	(envelope-from nobody)
Message-Id: <201111152010.pAFKA3D6049769@red.freebsd.org>
Date: Tue, 15 Nov 2011 20:10:03 GMT
From: "r. clayton" <rvclayton@acm.org>
To: freebsd-gnats-submit@FreeBSD.org
Subject: Handbook section 12.14.3 example unclear.
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         162597
>Category:       docs
>Synopsis:       [handbook] Handbook section 12.14.3 example unclear.
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    manolis
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Nov 15 20:20:03 UTC 2011
>Closed-Date:    Wed Nov 16 07:07:06 UTC 2011
>Last-Modified:  Wed Nov 16 07:07:06 UTC 2011
>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:

From: Manolis Kiagias <sonic2000gr@gmail.com>
To: bug-followup@FreeBSD.org, rvclayton@acm.org
Cc:  
Subject: Re: docs/162597: Handbook section 12.14.3 example unclear.
Date: Tue, 15 Nov 2011 22:36:06 +0200

 We shouldn't really direct the user to check anything in GENERIC, since 
 the device is  there by default. I suppose we could rephrase this to 
 something like the following:
 
 "The GENERIC kernel already includes support for the md(4) device needed 
 for this operation. When building a custom kernel, make sure to include 
 the following line in your kernel configuration file:
 
 device   md   # Memory "disks"
 
 For information on building your own kernel please refer to 
 <chapter/section ref here>."
 
 Would this be appropriate?
Responsible-Changed-From-To: freebsd-doc->manolis 
Responsible-Changed-By: manolis 
Responsible-Changed-When: Tue Nov 15 21:11:25 UTC 2011 
Responsible-Changed-Why:  
I'll handle this one 

http://www.freebsd.org/cgi/query-pr.cgi?pr=162597 

From: Manolis Kiagias <sonic2000gr@gmail.com>
To: "R. Clayton" <rvclayton@verizon.net>
Cc: bug-followup@FreeBSD.org, FreeBSD doc list <freebsd-doc@FreeBSD.org>
Subject: Re: docs/162597: Handbook section 12.14.3 example unclear.
Date: Tue, 15 Nov 2011 23:56:10 +0200

 On 15/11/2011 11:45 , R. Clayton wrote:
 >    I suppose we could rephrase this to something like the following:
 >
 >    "The GENERIC kernel already includes support for the md(4) device needed
 >    for this operation. When building a custom kernel, make sure to include
 >    the following line in your kernel configuration file:
 >
 >    device   md   # Memory "disks"
 >
 >    For information on building your own kernel please refer to
 >    <chapter/section ref here>."
 >
 >    Would this be appropriate?
 >
 > I like it (except maybe change the first sentence to "The GENERIC kernel
 > includes the md(4) device needed for this operation.")  Thank you for your
 > response to this.
 >
 
 Here is a quick patch then:
 
 http://www.freebsdgr.org/all/en_US.ISO8859-1/books/handbook/config/config.txt
 
 (note: no need to include the comment part on the device line)
 
 and test build here:
 
 http://www.freebsdgr.org/all/en_US.ISO8859-1/books/handbook/adding-swap-space.html
 
 Unless there are any objections, I'll commit this tomorrow morning.
 Thanks for reporting this!
 

From: rvclayton@verizon.net (R. Clayton)
To: Manolis Kiagias <sonic2000gr@gmail.com>
Cc: bug-followup@FreeBSD.org, rvclayton@acm.org
Subject: Re: docs/162597: Handbook section 12.14.3 example unclear.
Date: Tue, 15 Nov 2011 16:41:47 -0500 (EST)

 -- 

From: rvclayton@verizon.net (R. Clayton)
To: Manolis Kiagias <sonic2000gr@gmail.com>
Cc: bug-followup@FreeBSD.org, rvclayton@acm.org
Subject: Re: docs/162597: Handbook section 12.14.3 example unclear.
Date: Tue, 15 Nov 2011 16:45:18 -0500 (EST)

   I suppose we could rephrase this to something like the following:
 
   "The GENERIC kernel already includes support for the md(4) device needed 
   for this operation. When building a custom kernel, make sure to include 
   the following line in your kernel configuration file:
 
   device   md   # Memory "disks"
 
   For information on building your own kernel please refer to 
   <chapter/section ref here>."
 
   Would this be appropriate?
 
 I like it (except maybe change the first sentence to "The GENERIC kernel
 includes the md(4) device needed for this operation.")  Thank you for your
 response to this.
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/162597: commit references a PR
Date: Wed, 16 Nov 2011 06:55:37 +0000 (UTC)

 manolis     2011-11-16 06:55:28 UTC
 
   FreeBSD doc repository
 
   Modified files:
     en_US.ISO8859-1/books/handbook/config chapter.sgml 
   Log:
   Clear up the Handbook example on adding a swap file
   
   PR:             docs/162597
   Submitted by:   R. Clayton <rvclayton at acm dot org>
   Reviewed by:    gjb
   
   Revision  Changes    Path
   1.248     +8 -4      doc/en_US.ISO8859-1/books/handbook/config/chapter.sgml
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: manolis 
State-Changed-When: Wed Nov 16 07:06:21 UTC 2011 
State-Changed-Why:  
Changes were committed and will appear on the website soon. 
Thanks for reporting this! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=162597 
>Unformatted:
