274325 - Add rules for documentation changes (contribute/writing/cvs)

Status: RESOLVED WONTFIX

(www.mozilla.org :: General, defect)

Description

[Daniel Wang]

We need to add a rule on whitespace changes in either
www.mozilla.org/contribute/writing/guidelines or
www.mozilla.org/contribute/writing/cvs . CVS is a better place, but fewer people
read it :-/

Maybe create a section on "how to make a patch" and people will read.

We also need to add a note on Unix vs DOS text file format.

Also, we desparately needs something on "commual pages" (pages with common
interests/multiple maintainers, e.g. support/index.html, products/*/), but
that's another bug.

Comment 1

[Daniel Wang]

One more thing: add a rule on proper CVS check-in comment

-- starting point? --

Creating Patch and Making Changes to Web Site

When you edit/change a Web page, you must make it easy for people to see exactly
what you are changing. If you don't, your changes will be reverted. In particular:
* Avoid changing line wrapping and whitespacing (indentation). If you do this,
CVS diff won't properly show the changes.
* If a file isn't properly formatted (for example, it is in DOS text format or
the lines are not wrapped), you may change the line wrapping. You may not,
however, mix content and format changes. If you need to change the content or
markups, do so in another revision.
* Your check-in comment must be descriptive and cite the relevent bug and patch
author. If you apply changes different from the approved patch, you need to
mention your modification.
Doctor does not support multi-line comment. After you get your CVS account, we
encourage you to learn to use CVS.

Comment 2

[Gérard Talbot]

> * Avoid changing line wrapping and whitespacing (indentation). 
(...)
> * If a file isn't properly formatted (for example, it is in DOS text format or
> the lines are not wrapped), you may change the line wrapping.

Regarding line-wrapping, whitespacing, code indentation, etc.., why not make use of a software already available and well able to do this sort of things. So that all documents use/share the same line-wrapping, whitespacing, code indentation, etc. HTML Tidy can do that and it could be used on all patches submitted at html documents as a last edition done on patches. In other words, ideally, all documents on mozilla.org could be using the same code indentation, line-wrapping, whitespacing if all patches were being input into (and processed by) HTML Tidy with precisely-defined settings.

My perspective is that the more rules, guidelines, requirements, norms, etc.. you have/give/edit/define for .html webpages at mozilla.org, the less people are able to cope with them, accept+understand them, comply with them, the more people will be annoyed by them. Being software-assisted for these kinds of issues is welcomed. HTML Tidy is very powerful for these kinds of issues.

Comment 3

[Gérard Talbot]

I used the latest HTML Tidy (feb. 2006) (HandCoder 0.3.4 installed within KompoZer 0.77) to update the document 
http://www.mozilla.org/docs/dom/grids/html_tab.html
In about 10 min., I was able to remove 385 validation markup errors, reformat the markup code according to 22 defined settings among which there were:

--indent auto 
--indent-attributes no 
--indent-spaces 4 
--drop-proprietary-attributes yes 
--wrap 90 
--tidy-mark yes 
--vertical-space yes 
--tidy-mark yes 
--clean yes

In other words: line-wrap was occuring after 90 characters, attributes were not line-wrapped, markup code was vertically spaced out, ventilated. Again, code formating configurability within HTML Tidy is immense, great.

Anyone can download+install HandCoder 0.3.4 and KompoZer 0.77 and verify by himself all this.

Comment 4

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

If you enforce line wrap at all, it should be somewhere in the range 72-78 characters.

Comment 5

[Gérard Talbot]

I had 90 for line-wrapping because I experimented with this setting and others.

By default, Tidy has wrap set to 68
http://tidy.sourceforge.net/docs/quickref.html#wrap

HandCoder has wrap set to 120 mainly because, I presume, it is embeddable within Nvu and KompoZer.

72-78 is perfect for patches and fine with me :)

Comment 6

[Gordon P. Hemsley [:GPHemsley]]

The CVS file you refer to has been archived, and I've filed bug 670589 to archive the rest of that directory.

The use of CVS itself has been largely discontinued in favor of SVN or Hg, and the guidelines for that are likely on the wiki or MDN.

As such, resolving this as WONTFIX.