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

[Christian Brueffer]

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

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

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.

- Christian

-- 
Christian Brueffer	chris at unixpages.org	brueffer at FreeBSD.org
GPG Key:	 http://people.freebsd.org/~brueffer/brueffer.key.asc
GPG Fingerprint: A5C8 2099 19FF AACA F41B  B29B 6C76 178C A0ED 982D
-------------- 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/5e4bc3a9/attachment.pgp