Date: Wed, 27 Sep 2006 09:45:14 +0100 From: Ceri Davies <ceri@submonkey.net> To: Tom Rhodes <trhodes@FreeBSD.org> Cc: cvs-src@FreeBSD.org, danger@FreeBSD.org, src-committers@FreeBSD.org, cvs-all@FreeBSD.org, brueffer@FreeBSD.org Subject: Re: cvs commit: src/share/examples/mdoc example.4 Message-ID: <20060927084514.GR54669@submonkey.net> In-Reply-To: <20060927041526.6b33a348.trhodes@FreeBSD.org> References: <200609261959.k8QJxqkh068350@repoman.freebsd.org> <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> <20060927034124.2c57b517.trhodes@FreeBSD.org> <20060927075314.GQ54669@submonkey.net> <20060927041526.6b33a348.trhodes@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
[-- Attachment #1 --]
On Wed, Sep 27, 2006 at 04:15:26AM -0400, Tom Rhodes wrote:
> On Wed, 27 Sep 2006 08:53:14 +0100
> Ceri Davies <ceri@submonkey.net> wrote:
>
> > 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@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.
>
> That is of course that "something" has a module. ;)
Well yes, which is why the previous text explicitly said "to compile .Nm
into the kernel", because that's what the example does.
> Seriously though, why handle one case any differently than
> another?
Compiling something into the kernel and loading a module are different,
that's why, and we should be clear about the distinction (because, as
you state, some modules don't exist).
> > > > > | .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.
>
> Then we should bloat it to handle "the XXX driver," "the XXX
> subsystem," "the XXX system," etc. To be honest, the sentence
> sounds better to me this way. And putting "driver" back in
> just does what Christian says it's there to prevent. We should
> not really "rely on the context" here, so I agree with Christian.
> We shouldn't believe that it will always be a "driver."
>
> In any sense, it's still just an "example." We are arguing over
> an "example" people.
No, we're arguing over grammar. The sentence currently renders as
something like:
Alternatively, to load the fxp(4) as a module at boot time...
That's wrong. Getting rid of "the" works.
Ceri
--
That must be wonderful! I don't understand it at all.
-- Moliere
[-- Attachment #2 --]
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (FreeBSD)
iD8DBQFFGjoZocfcwTS3JF8RAnIjAJ41CgoEa+IX1KmZYzyqLOfWQyXYTgCfQIjd
vT4JV/QHMe24WKNEKEtbmnQ=
=84rg
-----END PGP SIGNATURE-----
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060927084514.GR54669>