Date: Wed, 27 Sep 2006 10:37:33 +0200 From: Christian Brueffer <brueffer@FreeBSD.org> To: Tom Rhodes <trhodes@FreeBSD.org> Cc: src-committers@FreeBSD.org, cvs-src@FreeBSD.org, cvs-all@FreeBSD.org, danger@FreeBSD.org, brueffer@FreeBSD.org, Ceri Davies <ceri@submonkey.net> Subject: Re: cvs commit: src/share/examples/mdoc example.4 Message-ID: <20060927083733.GA1941@haakonia.hitnet.RWTH-Aachen.DE> 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
--/04w6evG8XlLl3ft Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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: >=20 > > 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: > >=20 > > > > > | @@ -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: > > > >=20 > > > > The formulation used before was much more accurate WRT the distinct= ion > > > > 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 f= or > > > > it". > > >=20 > > > What about in cases where other hoops must be jumped before the > > > driver/feature/whatever is really supported? > >=20 > > 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. >=20 > That is of course that "something" has a module. ;) >=20 > Seriously though, why handle one case any differently than > another? We should be fair here, and the above version will > work for anything ... although, to be exact, we should probably > use: >=20 I don't understand your reasoning for using "to enable support". Using this would actually be wrong if there's more to do than recompiling the kernel, as that alone would not really enable support for $SOMETHING. OTOH if you have to e.g. set a sysctl value to enable this support, this would likely have to be done for the module case as well, so the old formulation would be better. Care to elaborate? > "place the following line(s) in the kernel configuration file:" >=20 >=20 > >=20 > > > > > | .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=3D"YES" > > > > > | .Ed > > > > >=20 > > > >=20 > > > > Removing "driver" here is wrong. "...to load the .Nm..." what, the= .Nm > > > > driver? The .Nm utility? It's just incorrect to rely on context h= ere > > > > and it makes the sentence sound really awkward. > > >=20 > > > Leaving driver here is wrong. > >=20 > > Not if you also leave the word "the" before .Nm. >=20 > 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." >=20 You're twisting my argument here ;-) Of course this is an example, so I can't be said whether it's a driver or a subsystem. But anyone who is using this template _probably_ knows what he's modifying the example for and will just replace that word with whatever is correct. However leaving the word out will just result in an incorrect sentence (we still have several of those in our manpages, e.g. "utility" and "command" are among the favourite words that are left out). So in this case, put in driver/subsystem/whatever, but put in _something_. > In any sense, it's still just an "example." We are arguing over > an "example" people. >=20 I know :-) But having good examples means less editing to do when a new page based on this example hits the tree. That's exactly the reason for my last couple of commits to this manpage. - Christian --=20 Christian Brueffer chris@unixpages.org brueffer@FreeBSD.org GPG Key: http://people.freebsd.org/~brueffer/brueffer.key.asc GPG Fingerprint: A5C8 2099 19FF AACA F41B B29B 6C76 178C A0ED 982D --/04w6evG8XlLl3ft Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.5 (FreeBSD) iD8DBQFFGjhNbHYXjKDtmC0RArBhAKDY/9o5U4maorn8N/Kym85Mx5Mg7ACdEwND OVpUs3pi4pnr3QfI8ABUq8I= =0o9h -----END PGP SIGNATURE----- --/04w6evG8XlLl3ft--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060927083733.GA1941>