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

[John Baldwin]

On Wednesday 27 September 2006 04:45, Ceri Davies wrote:
> 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 at 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 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.
> > 
> > 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).

And it's not the same as enabling the driver.  You can kldload ipmi but still 
disable it via a hw.ipmi.on sysctl and then re-enable it later w/o unloading 
it by toggling the sysctl back on.  Enable is a poor word choice and very 
vague.  Since you are mentioning the specific details of adding lines to a 
kernel config file, you should be as specific in stating what that does (adds 
driver to kernel).

-- 
John Baldwin