Date: Thu, 24 Jul 2003 03:30:15 -0700 (PDT) From: Marc Fonvieille <blackend@FreeBSD.org> To: freebsd-doc@FreeBSD.org Subject: Re: docs/54789: [PATCH] brush up the "New Users" article Message-ID: <200307241030.h6OAUFB1095228@freefall.freebsd.org>
index | next in thread | raw e-mail
The following reply was made to PR docs/54789; it has been noted by GNATS. From: Marc Fonvieille <blackend@FreeBSD.org> To: Lukas Ertl <l.ertl@univie.ac.at> Cc: FreeBSD-gnats-submit@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. Marchelp
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200307241030.h6OAUFB1095228>