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

[Ceri Davies]

On Wed, Sep 27, 2006 at 03:41:24AM -0400, Tom Rhodes wrote:
> On Tue, 26 Sep 2006 22:23:39 +0200
> Christian Brueffer <brueffer at FreeBSD.org> wrote:

> > > | @@ -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?

They can be special cased in the real manual.  In the wider sense,
kldload is the easiest way to enable support for something, and I know
that I'm personally well past encouraging users to recompile the kernel
just to get, for example, sound working when a simple kldload does the
job just as well in most cases.

> > > |  .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.

Not if you also leave the word "the" before .Nm.

Ceri
-- 
That must be wonderful!  I don't understand it at all.
                                                  -- Moliere
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/cvs-all/attachments/20060927/5073ee97/attachment.pgp