Date: Wed, 27 Sep 2006 08:40:54 +0100 From: Ceri Davies <ceri@submonkey.net> To: Christian Brueffer <brueffer@FreeBSD.org> Cc: cvs-src@FreeBSD.org, Daniel Gerzo <danger@FreeBSD.org>, src-committers@FreeBSD.org, cvs-all@FreeBSD.org Subject: Re: cvs commit: src/share/examples/mdoc example.4 Message-ID: <20060927074054.GO54669@submonkey.net> In-Reply-To: <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE> References: <200609261959.k8QJxqkh068350@repoman.freebsd.org> <20060926202339.GA2039@haakonia.hitnet.RWTH-Aachen.DE>
next in thread | previous in thread | raw e-mail | index | archive | help
--Q59ABw34pTSIagmi
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
On Tue, Sep 26, 2006 at 10:23:39PM +0200, Christian Brueffer wrote:
> On Tue, Sep 26, 2006 at 07:59:52PM +0000, Daniel Gerzo wrote:
> > danger 2006-09-26 19:59:52 UTC
> >=20
> > FreeBSD src repository (doc committer)
> >=20
> > Modified files:
> > share/examples/mdoc example.4=20
> > Log:
> > Remove second person from the sentece and rephrase a bit.
> > =20
> > Approved by: trhodes (mentor), keramida (mentor)
> > =20
> > Revision Changes Path
> > 1.26 +6 -8 src/share/examples/mdoc/example.4
>=20
> I don't agree to these changes, see below for details (also I don't see w=
here
> exactly you removed second person usage, it's still being used in the new
> version).
>=20
> > | =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> > | RCS file: /usr/local/www/cvsroot/FreeBSD/src/share/examples/mdoc/exam=
ple.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 POSSIBIL=
ITY 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:
>=20
> 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".
>=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 here
> and it makes the sentence sound really awkward.
>=20
> 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.
I agree.
Ceri
--=20
That must be wonderful! I don't understand it at all.
-- Moliere
--Q59ABw34pTSIagmi
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (FreeBSD)
iD8DBQFFGisGocfcwTS3JF8RAp6OAJ0WuxupMi61WEDWFAfGVwN74/K8KwCcDZLW
0zCnhko3Bylgp97/f+tT/CI=
=Ku/r
-----END PGP SIGNATURE-----
--Q59ABw34pTSIagmi--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060927074054.GO54669>