docs/52547: [patch] Cleanup of laptop article

[Simon L. Nielsen]

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 ?

>  > * s/FreeBSD/&os;/g
>  
>  This tag should be used on new submission, but a full commit does not
>  worth since it brings nothing new to the reader.

Ok.

>  > * Add application tags around XFree86 references
>  > * Minor markup cleanups... Hope they right
>  > * Refer to more files/programs using manual page references
>  > * Remove some redundant words/sentences (inspired by FDP Writing style section)
>  > 
>  > Note: This article is in need of a whitespace cleanup.
>  > >How-To-Repeat:
>  > >Fix:
>  > --- doc-article-laptop-cleanup.patch begins here ---
>  [...]
>  >  
>  > -    <programlisting>
>  > -      Option "Emulate3Buttons"
>  > -    </programlisting>
>  > +    <programlisting>Option "Emulate3Buttons"</programlisting>
>  
>  It's not good: no whitespace/wrapline change with content change.
>  And this one is quite useless.

Doh, yes. I should have remembered that.

>  
>  [...]
>  > -      cards is in the file <filename>/etc/defaults/pccard.conf</filename>.  
>  > +      cards is in &man.pccard.conf.5;.
>  
>  /etc/defaults/pccard.conf is always up to date, it's not the case of the
>  manual page.

I have often seen manual pages refered to instead of the files they
document (at least in other manual pages).  This was the main reason for
this change, and a few other similar changes in the patch.

>  
>  >        Look through it, and preferably buy cards listed there.  Cards not
>  >        listed may also work as <quote>generic</quote> devices: in 
>  >        particular most modems (16-bit) should work fine, provided they 
>  > @@ -128,39 +126,38 @@
>  >        card, remove irq 5 (otherwise you may experience hangs when you 
>  >        insert a card).  Check also the available memory slots; if your 
>  >        card is not being detected, try changing it to one of the other 
>  > -      allowed values (listed in the manual page &man.pccardc.8;).
>  > +      allowed values (listed in &man.pccardc.8;).
>  
>  manual page was good there.

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 ?

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.

-- 
Simon L. Nielsen
-------------- 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/freebsd-doc/attachments/20030523/dde77c05/attachment.sig>