docs/54789: [PATCH] brush up the "New Users" article

[Marc Fonvieille]

The following reply was made to PR docs/54789; it has been noted by GNATS.

From: Marc Fonvieille <blackend at FreeBSD.org>
To: Lukas Ertl <l.ertl at univie.ac.at>
Cc: FreeBSD-gnats-submit at FreeBSD.org
Subject: Re: docs/54789: [PATCH] brush up the "New Users" article
Date: Thu, 24 Jul 2003 12:22:18 +0200

 On Thu, Jul 24, 2003 at 10:57:57AM +0200, Lukas Ertl wrote:
 > On Thu, 24 Jul 2003, Marc Fonvieille wrote:
 > 
 > > Arghh :((  You're doing a lot of whitespaces/wrapline changes with
 > > content changes which is very difficult for us to read and is not FDP
 > > compliant (I think I already pointed the whitespace thing in an audit
 > > trail of one of your PRs).
 > 
 > Sorry, but I didn't intend to do whitespaces/wrapline changes.
 > "<username>root</username>" simply takes up more space than just "root",
 > and I didn't want to leave long lines. Does the FDP have a rule for this?
 >
 
 http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html#AEN3267
 
 (In fact you should only submit content changes, we will handle
 whitespaces/wrapline by ourselves (only if it worth...).)
 
 For an example, let me paste a part of keramida@ mail:
 
 ---
 You should definitely avoid making changes that have this style:
 
 	- xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 	+ xxxxxxxxxxxxxxxxxxxxx
 	+ xxxxxxxxxxxxxxxxx
 	- xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 	- xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 	+ xxxxxxxxxxxxxxxxxxxxxxx
 	+ xxxxxxxxxxxxxxxxxxxxx
 	+ xxxxxxxxxxxxxxxxxxxxxx
 	+ xxxxxxxxxxxxxxxxxxxxxxxx
 
 This is where wrapping is evil, and it clutters up the diff.  But it's
 OK to wrap when changes like this are made:
 
 	- xxxxxxxxxxxxxxxxxxxxxxx
 	+ xxxxxxxxxxxxxxxxxxxxxxxyyy
 	+ yyyyyyyyyyyyyyyyyyyyyyyy
 	+ yyyyyyyy
 
 Since it's only a little part of 'yyy' that affects the 'xxx' line.
 Of course, the same is true for changes like:
 
 	+ yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
 	+ yyyyyyyyyyyyyyyyyyyyyyyyyyyy
 	+ yyyyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 	- xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
 To make a long story short, where only one of the old lines is listed,
 regardless of wrapping or not, you are more than free to wrap the
 resulting text.
 ---
 
 Another thing to avoid to change/add in a content submission is the
 "trailingspaces".  Each editor allows you to check for these nasty
 little spaces, you should not add them, and even if you find one you
 should not remove it in a content change.
 So you could tell me "Why not remove the ones currently present in our
 files?", well cause it will spend a lot of CVS repo spaces and it will
 be a good thing only if no new trailingspace is added in next commits.
 
 When you write new things, you really have to respect indentation rules:
 http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style.html#AEN3233
 you will have to configure your editor to respect indentation levels,
 and to replace the 1st 8 spaces at the beginning of a line with a tab.
 
 About some changes like s/FreeBSD/&os;, in my opinion &os; should be
 used in new content, replacing old FreeBSD with &os; does not bring
 something new to the reader.
 
 Please do not take these for you, I'm talking in general.  I just hope
 this will help people to send us the greatest contributions, and once
 again http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/
 should be the reference.
 
 Marc