docs/52547: [patch] Cleanup of laptop article

Tom Rhodes trhodes at FreeBSD.org
Fri May 23 18:17:50 UTC 2003


On Fri, 23 May 2003 20:06:28 +0200
"Simon L. Nielsen" <simon at nitro.dk> wrote:

> On 2003.05.23 10:20:07 -0700, Marc Fonvieille wrote:
> > The following reply was made to PR docs/52547; it has been noted by GNATS.
> > 
> >  On Thu, May 22, 2003 at 01:45:04AM +0200, Simon L.Nielsen wrote:
> >  > General cleanup of the laptop article :
> >  > 
> >  > * Add id attributes to all sect1 tags
> >  
> >  This is far to be mandatory on a so little article.
> 
> Hmm, from following the this mailling list I got the impression that the
> section id tags was a good idea on all books/articles, since it makes
> sensible filenames when doing html-split output ?

I'm going to agree with ceri (and keramida?) about this.  Personally,
I think using id attributes in articles is a Good Thing™.

> 
> This change was inspired by the 'Avoid redundant phrases' part of the
> "Writing style" section of FDP... Is I reading that section wrong, or is
> the FDP Primer just not updated with current pratice ?

The FDP needs a few touch ups here and there.  Yet, busy as we are, we
simply cannot do it all.  Even though we try, and a good handful of
us are zealots when it comes to FreeBSD and its documentation; we
are very likely to get behind.

> 
> Thanks, for taking the time to comment so detailed on the patch! It
> helps me a lot in getting to know all the do's and don'ts about the
> documentation.
> 

Education comes with time.  While working through the PR base, you will
learn (as I did, and many before me) the traditions and standard practices
of the documentation project.  Its a long road to walk, and true that
the FDP can teach you how to use docbook; mdoc(7) can teach you mdoc(7);
but they cannot just hand you experiance.  Thats what the PR base gives
you.

Anyways, I've got a ton of work todo; both for FreeBSD && ${REALJOB}.

Take care,

--
Tom Rhodes



More information about the freebsd-doc mailing list