cvs commit: src/share/examples/mdoc example.4

[Tom Rhodes]

On Tue, 26 Sep 2006 22:23:39 +0200
Christian Brueffer <brueffer at FreeBSD.org> wrote:

> On Tue, Sep 26, 2006 at 07:59:52PM +0000, Daniel Gerzo wrote:
> > danger      2006-09-26 19:59:52 UTC
> > 
> >   FreeBSD src repository (doc committer)
> > 
> >   Modified files:
> >     share/examples/mdoc  example.4 
> >   Log:
> >   Remove second person from the sentece and rephrase a bit.
> >   
> >   Approved by: trhodes (mentor), keramida (mentor)
> >   
> >   Revision  Changes    Path
> >   1.26      +6 -8      src/share/examples/mdoc/example.4
> 
> I don't agree to these changes, see below for details (also I don't see where
> exactly you removed second person usage, it's still being used in the new
> version).
> 
> > | ===================================================================
> > | RCS file: /usr/local/www/cvsroot/FreeBSD/src/share/examples/mdoc/example.4,v
> > | retrieving revision 1.25
> > | retrieving revision 1.26
> > | diff -u -p -r1.25 -r1.26
> > | --- src/share/examples/mdoc/example.4	2006/09/18 15:18:54	1.25
> > | +++ src/share/examples/mdoc/example.4	2006/09/26 19:59:52	1.26
> > | @@ -22,7 +22,7 @@
> > |  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
> > |  .\" SUCH DAMAGE.
> > |  .\"
> > | -.\" $FreeBSD: /usr/local/www/cvsroot/FreeBSD/src/share/examples/mdoc/example.4,v 1.25 2006/09/18 15:18:54 ru Exp $
> > | +.\" $FreeBSD: /usr/local/www/cvsroot/FreeBSD/src/share/examples/mdoc/example.4,v 1.26 2006/09/26 19:59:52 danger Exp $
> > |  .\"
> > |  .\" Note: The date here should be updated whenever a non-trivial
> > |  .\" change is made to the manual page.
> > | @@ -33,11 +33,9 @@
> > |  .Nm example
> > |  .Nd "example device driver manual page"
> > |  .Sh SYNOPSIS
> > | -To compile the
> > | -.Ns Nm
> > | -driver into the kernel,
> > | -place the following lines in the
> > | -kernel configuration file:
> > | +To enable support for
> > | +.Ns Nm ,
> > | +place the following lines in the kernel configuration file:
> 
> The formulation used before was much more accurate WRT the distinction
> we make between compiling something into the kernel and loading it as a
> module.  If we load something as a module we also "enable support for
> it".

What about in cases where other hoops must be jumped before the
driver/feature/whatever is really supported?

> 
> > |  .Bd -ragged -offset indent
> > |  .Cd "device example"
> > |  .Cd "options EXAMPLE_DEBUG"
> > | @@ -45,9 +43,9 @@ kernel configuration file:
> > |  .Pp
> > |  Alternatively, to load the
> > |  .Ns Nm
> > | -driver as a
> > | -module at boot time, place the following line in
> > | -.Xr loader.conf 5 :
> > | +as a module at boot time, add the following line into the
> > | +.Xr loader.conf 5
> > | +file:
> > |  .Bd -literal -offset indent
> > |  example_load="YES"
> > |  .Ed
> > 
> 
> Removing "driver" here is wrong.  "...to load the .Nm..." what, the .Nm
> driver?  The .Nm utility?  It's just incorrect to rely on context here
> and it makes the sentence sound really awkward.

Leaving driver here is wrong.

> 
> IMHO the SYNOPSIS section in section 4 manpages is kind of a standard
> now, as it's being used in the majority of section 4 manpages.
> Changes to it should not be made without _good_ reason and with a sweep
> through all manpages that use it.  Among other things, the purpose of
> this section is to achieve consistency across section 4 manpages.

The purpose of this file is to provide an example for people who are
going to write section four manual pages; however, no one really
"has" to follow this "lead."

-- 
Tom Rhodes