262080 - Cruft removal/additional fixes for mozilla help files

Status: VERIFIED FIXED

(Documentation Graveyard :: Help Viewer, defect)

Description

[Giacomo Magnini]

User-Agent:       Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.3) Gecko/20040922
Build Identifier: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.3) Gecko/20040922

I went trough some clean up of a few mozilla help files to remove unused <br>
and to use a more uniform style across all files.
This is also a mark holder for additional errors inside mozilla suite help files.


Reproducible: Always
Steps to Reproduce:

Comment 1

[Giacomo Magnini]

Assigning to me and adding interested parties! :)

Comment 2

[Giacomo Magnini]

Attachment: here are some of the first findings

Some cruft removal across the board. I've left some <br> in where it was
appropriate, since I didn't find a better way to preserve the original output
using other common methods. Feel free to comment and improve.

Comment 3

[Gérard Talbot]

Giacomo, I'll support your efforts here in this bug. Help files (content,
formating, styling, navigation, accessibility of these helpfiles) are the last
thing which ever gets updated, tuned, tweaked. I hope it will be for more than
just trailing <br> though :).
Giacomo,
1- Do you have CVS access to submit, apply patches?
2- Right now, which patches are waiting to be applied? attachment 160471 [details] [diff] [review] from 
bug 258257? Any other from bug 257507?
3- Do you validate the helpfile documents with the W3C html validator? or WDG
markup validator?
4- In my experience, heavily nested elements are usually a reliable sign of
improvable web page design:
              <li><strong>&amp;T</strong>: Page Title</li>
            </ul>
          </li>
        </ul>
      </li>
    </ul>
  </li>
</ul>
can be seen in the patch (attachment 160474 [details] [diff] [review]) in nav_help.xhtml around line 1030.
4 levels deep of nested list might be possibly suitable for a law book or
encyclopedia of some sort but here, in a help documentation, it does not strike
as an optimal design decision.
5- You missed
      <li><strong>Enable Pipelining</strong>: <strong></strong>Select this to
at around line 300 of cs_nav_prefs_advanced.xhtml

Comment 4

[Giacomo Magnini]

(In reply to comment #3)
> 1- Do you have CVS access to submit, apply patches?
No, I just hope that Neil has some spare cycles to spend on such small and
unique fixes and that he can forgive my attempts. He has been quite nice in this
department for a long time. Thx Neil! :)
> 2- Right now, which patches are waiting to be applied? attachment 160471 [details] [diff] [review] from 
> bug 258257?
Right.
> Any other from bug 257507?
No, and I've closed the bug, since it was getting too long to be readable and
all of the fixes there are in. There is another set of changes waiting in bug
111484 regarding hiding of platform specific functions.
> 3- Do you validate the helpfile documents with the W3C html validator? or WDG
> markup validator?
Actually no. I just make sure that it loads in Mozilla, avoiding xhtml errors
(so they WILL show up correctly in the Help window).
I'm not even sure they can/do validate (they should, except for brand.dtd)...
> 4- In my experience, heavily nested elements are usually a reliable sign of
> improvable web page design:
While I agree with you, I'm not going to rewrite the documentation by myself,
firstly because the Suite is not going to last for much long as it is, and
secondly because I'm not so fluent in English to provide clear docs! :)
That's also why I provived only an initial patch in bug 258257, avoiding the
rewrite of some outdated sections, waiting for someone else to pick up the
burden, but from a better position...
> 5- You missed
>       <li><strong>Enable Pipelining</strong>: <strong></strong>Select this to
> at around line 300 of cs_nav_prefs_advanced.xhtml
Good catch! Will fix locally, and wait for more reports of similar stuff.

Comment 5

[Stefan [:stefanh]]

While you're at it, can you fix <link ...></link> --> <link .../> (same for
image tags)?

Comment 6

[Gérard Talbot]

(In reply to comment #4)
> (In reply to comment #3)
> > 1- Do you have CVS access to submit, apply patches?
> No

Why not apply to have CVS access? It seems desirable and logical that the
assignee also has CVS access.

> > 3- Do you validate the helpfile documents with the W3C html validator? or WDG
> > markup validator?
> Actually no. I just make sure that it loads in Mozilla, avoiding xhtml errors
> (so they WILL show up correctly in the Help window).
> I'm not even sure they can/do validate (they should, except for brand.dtd)...

When I work on bug 74952, I "select all" the whole document, Ctrl+C and then
paste into this page
http://www.htmlhelp.com/tools/validator/direct.html
and get the validation errors: all this takes less than 15 sec... and I get to
see instantly where are improper nesting, missing closing tags, not closed tags,
etc.. markup/validation errors.

> > 4- In my experience, heavily nested elements are usually a reliable sign of
> > improvable web page design:
> While I agree with you, I'm not going to rewrite the documentation by myself,
> firstly because the Suite is not going to last for much long as it is,

Nevertheless, one can expect large chunks of the helpfiles to be re-used or
copied in the future..

 and
> secondly because I'm not so fluent in English to provide clear docs! :)

I was not specifically referring to vocabulary, grammar here but rather to
document structure, web page design and DOM.
Also, the fluency in English might be a positive asset in fact: text in
documentation should be as simple, clear and understandable as possible. It is
known that a large minority of users of Mozilla, Firefox and Mozilla components
do not have English as their natural/mother tongue.

> That's also why I provived only an initial patch in bug 258257, avoiding the
> rewrite of some outdated sections, waiting for someone else to pick up the
> burden, but from a better position...

I understand you set limited and specific goals for this bug. I personally value
the importance of this bug (and bug 257507).
The english helpfiles (here and in other bugs) really need to be updated from
all angles, perspectives because, among many reasons, they are re-used on the
mozilla.org site, they are translated in localized versions of Mozilla, it can
safely be expected to be re-used (or large chunks of it) in other components or
products (Firefox, Thunderbird, Nvu, etc.).

Comment 7

[Stefan [:stefanh]]

The help files should be valid xhtml, that is - either xhtml transitional
(documents with external links opened in a new window) or xhtml 1.1 (all other
documents).

Comment 8

[Giacomo Magnini]

(In reply to comment #5)
> While you're at it, can you fix <link ...></link> --> <link .../> (same for
> image tags)?

Good catch. Done.

(In reply to comment #6)
> Why not apply to have CVS access? It seems desirable and logical that the
> assignee also has CVS access.

I don't want to mess around too much; I just learned how to create and submit
patches. Using cvs on the tree would be painfull, especially for others! :)
And btw, I had some strong "exchange of views", and I was actually going to
cease my mozilla contribution: but I think that those files are in such a shape,
that a refresh is needed anyway. I would like to close also a few other bugs
about all of these, notably the renaming of files and the splitting of
mail_help, which matters me most, as I translated the whole monster alone and I
can still feel the pain...

> When I work on bug 74952, I "select all" the whole document, Ctrl+C and then
> paste into this page
> http://www.htmlhelp.com/tools/validator/direct.html
> and get the validation errors: all this takes less than 15 sec... and I get to
> see instantly where are improper nesting, missing closing tags, not closed 
> tags, etc.. markup/validation errors.

Open file... will give you the same insight! :) And Stefan has already done a
good job at creating compliant pages. Some of them are XHTML 1.0, some are 1.1,
but that would be another bug... ;)

> Nevertheless, one can expect large chunks of the helpfiles to be re-used or
> copied in the future..

The docs for FX are almost completely new, and most are being rewritten these
days. TB is/will be following the same route, I guess, and it will matter one in
one file (mail_help) which is being addressed elsewhere.

> I was not specifically referring to vocabulary, grammar here but rather to
> document structure, web page design and DOM.

Well, Stefan is working on some aspects. I may consider working on what you are
referring to, but since I'm not a web designer and I can barely deal with
(X)HTML/CSS, I can do just the "stupid work" of applying others' ideas where
needed...

> It is known that a large minority of users of Mozilla, Firefox and Mozilla 
> components do not have English as their natural/mother tongue.

A good English text is needed both for English users and for intl translators:
as I'm not really fluent with English, I'll let others do the homeworks (and
translate them afterwards!:-) ).

> I understand you set limited and specific goals for this bug. I personally 
> value the importance of this bug (and bug 257507).

Well, at least we're 3, maybe 4... :(

> The english helpfiles (here and in other bugs) really need to be updated from
> all angles, perspectives because, among many reasons, they are re-used on the
> mozilla.org site, they are translated in localized versions of Mozilla, it can
> safely be expected to be re-used (or large chunks of it) in other components 
> or products (Firefox, Thunderbird, Nvu, etc.).

As I said, most of the docs are being rewritten/updated without considering the
Suite (which is understandable).
Anyway, back to some real work, patch is coming up! :)

Comment 9

[Giacomo Magnini]

Attachment: Updated patch, addressing the new reports

This is getting big enough to actually being ready to ask review...

Comment 10

[Stefan [:stefanh]]

composer_help still has some <i>:s ;)

Comment 11

[Stefan [:stefanh]]

hmm.. and I think there's some <b>:s left...

Comment 12

[Giacomo Magnini]

(In reply to comment #10)
> composer_help still has some <i>:s ;)
(In reply to comment #11)
> hmm.. and I think there's some <b>:s left...

Hehehe some! 10 occurences of <i></i> and 268 for <b></b>! :)
Ok, will add these to the bunch and ask for approval. The patch will get too big
for any further work.
While thinking of this, it would be nice to remove &quot; and put in <q></q>,
which is shorter and styleable...

Comment 13

[Giacomo Magnini]

Attachment: Ok, lots of cruft removed.

Now it's time to check this in and start working on the next issues raised.
I hope this patch doesn't interfere with Stefan one for platorm hiding (did not
test).

Comment 14

[Giacomo Magnini]

Comment on attachment 160540 [details] [diff] [review]
Ok, lots of cruft removed.

First round up to clean up lots of cruft

Comment 15

[Tsahi Asher]

well, i'm not that interested :)

if i find any more errors while translating, i'll report them to bugzilla.

Comment 16

[Giacomo Magnini]

Attachment: Found some more cruft in composer and added a small fix for bug 251548

Comment 17

[Gérard Talbot]

1- In the right pane:
Browsing the Web/Copying, Saving, and Printing Pages/Printing a Page
at the end
"Tip: To see a preview of changes made to Page Setup, use Print Preview."
The link "Print Preview" is inactive, goes nowhere when it should probably bring
back into that same sub-section at the top of the sub-sub-section "Using Print
Preview"

2- In the left pane:
Clicking Customizing Mozilla/Sidebar/Customizing Individual Sidebar Tabs
does not bring the content in the right pane.

3- In the right pane:
Customizing Mozilla/Changing Fonts, Colors, and Themes/Changing the Default Fonts
Clicking the [Return to beginning of section] does not bring back to top of section.

4- In the right pane:
Clicking
Customizing Mozilla/Changing Fonts, Colors, and Themes
and then in the gray section
"In this section:
    * Changing the Theme"
clicking the link Changing the Theme does not bring the page to the content.

5- In the right pane:
At the end of
Customizing Mozilla/Changing Fonts, Colors, and Themes/Changing the Theme
section, the link
"[Return to beginning of section]" does not bring back to top of section

6- In the right pane, at the end of
Customizing Mozilla/Toolbars/Personal Toolbar/Rearranging the Personal Toolbar,
it is written:
"Note: Standard buttons on the Personal Toolbar such as Search and Home Page
cannot be rearranged"
but it should be written
"Note: Standard buttons on the Personal Toolbar such as Home and Bookmarks
cannot be rearranged"

7- In the left pane:
Using Privacy Features, the whole section "Privacy on the Internet" is a
distinct top topic while on the right pane, it is a sub-topic of the topic
"Using Privacy Features". I believe Privacy on the Internet should be a
sub-topic of "Using Privacy Features".

Mozilla 1.8a5 build 2004100105 here

Comment 18

[Gérard Talbot]

(continued)

8- In the right pane:
Creating Web Pages/Formatting Your Web Pages/Choosing the Right Editing Mode
Show All Tags: Choose this mode to show all HTML tag icons.
should be written:
HTML Tags: Choose this mode to show all HTML tag icons.

9- In the right pane:
Creating Web Pages/Formatting Your Web Pages/Changing Text Color, Style, and Font
Text Color: Use this to choose a color from the color picker. If you are
familiar with HTML hexadecimal color codes, you can type a specific code or you
can just type a color name (for example, "blue"). You'll find a handy color code
converter here.
Clicking that "here" link brings up
builder.com.com
which is a front page with no color code converter. Until we can propose a good
link, reliable page, I think we should remove that, maybe just comment out that
part. There is
http://www.1stsitefree.com/rgb_hex.htm
which has a color code converter but it involves an applet. There must be a
resource somewhere with a color code converter without an applet.

Giving a link also kinda suggests that the current color picker is not as
versatile, complete as it should.

10- In the right pane:
Creating Web Pages/Adding Tables to Your Web Page/Moving, Copying, and Deleting
Tables
section should have a "[Return to beginning of section]" link

11- In Tools and Development or (right pane) Web Development Tools
These links should be provided:

Javascript Debugger Venkman Homepage
http://www.mozilla.org/projects/venkman/

Using Breakpoints in Venkman.
http://devedge.netscape.com/viewsource/2003/venkman/01/

12 & 13- In the right pane:
Using Mail/Signing & Encrypting Messages/About Digital Signatures &  Encryption
"2. Configure the security settings for your email account. For details, see
Configuring Your Security Settings."
The link "Configuring Your Security Settings" is inactive, goes nowhere.
and
"Once you have completed these steps, you can complete the instructions in
Signing & Encrypting a New Message."
the link "Signing & Encrypting a New Message" goes nowhere, is inactive. Should
go to Signing & Encrypting a New Message section.

Comment 19

[Giacomo Magnini]

Attachment: updated patch, with all reported nits addressed.

Comment 20

[Giacomo Magnini]

Attachment: update for developers_tools.xhtml, which I left out before

Comment 21

[Gérard Talbot]

In attachment 161146 [details] [diff] [review]:

 <p><strong>Note: </strong>Standard buttons on the Personal Toolbar such as
-  Search and Home Page cannot be rearranged, but they can be
+  Search and Bookmarks cannot be rearranged, but they can be
   <a href="#turning_buttons_on_and_off">turned off and on</a>.</p>

It should be
+  Home and Bookmarks cannot be rearranged, but they can be

See 6- at comment #17

Comment 22

[Gérard Talbot]

I don't see the corrections, changes regarding 8-, 9- and 10- items of comment
#18 in attachment 161146 [details] [diff] [review]. Anyway, we can fix these later too, with the next patch.

Comment 23

[Giacomo Magnini]

Attachment: Humf. Fixed.

Comment 24

[Giacomo Magnini]

(In reply to comment #22)
> I don't see the corrections, changes regarding 8-, 9- and 10- items of comment
> #18 in attachment 161146 [details] [diff] [review]. Anyway, we can fix these later too, with the next patch.

They are in a different patch, in bug 251548, which contains also more cleanups
for composer_help.xhtml. You are underestimating me! :-P

Comment 25

[[e-mail]]

Comment on attachment 161150 [details] [diff] [review]
update for developers_tools.xhtml, which I left out before

>+      <li><a href="http://www.mozilla.org/projects/venkman/"
>+        target="_blank">Javascript Debugger Venkman Homepage</a></li>
Should be Venkman JavaScript Debugger Homepage

>+      <li><a href="http://devedge.netscape.com/viewsource/2003/venkman/01/"
>+        target="_blank">Using Breakpoints in Venkman</a>
>+        (Netscape&apos;s DevEdge article)</li>
Sadly this is no longer online.

You might want to link to http://www.hacksrus.com/~ginda/venkman/

Comment 26

[Giacomo Magnini]

Attachment: Updated per comments

Comment 27

[Giacomo Magnini]

Attachment: Ok, I'm stupid

Comment 28

[Giacomo Magnini]

As I said, I'm stupid: there's a missing </li> at the end of the last changed
line. Please fix the patch before checkin! Thx!

Comment 29

[Giacomo Magnini]

Attachment: devtools_help fixed patch

This is the correct version ready to be checked in.

Comment 30

[Ian Neal]

Comment on attachment 161174 [details] [diff] [review]
Humf. Fixed.

r=[e-mail]

Comment 31

[Ian Neal]

Checking in devtools patch:
Checking in developer_tools.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/developer_tools.xhtml,v
 <--  developer_tools.xhtml
new revision: 1.4; previous revision: 1.3
done

Comment 32

[Ian Neal]

Checking in cruftremovalnew4 fixes:
Too many to list :-)

Comment 33

[Stefan [:stefanh]]

Giacomo, please mark it fixed if it is ;)

Comment 34

[Giacomo Magnini]

Thanks all! :)

Comment 35

[Gérard Talbot]

I checked the corrections/modification regarding the previous patch and they
were made.

I checked once more the helpfiles with Mozilla 1.8a5 build 2004102505 and I got
still a few:

1 and 2-
Creating Web Pages/Formatting Your Web Pages/Inserting Horizontal Lines/Setting
Horizontal Line Properties

"Tip: You can select *Show All Tags* from the View menu to show all the HTML
elements in yellow boxes."
should be instead/rather
"Tip: You can select HTML Tags from the View menu to show all the HTML elements
in yellow boxes."

Also:
Creating Web Pages/Formatting Your Web Pages/Inserting HTML Elements and
Attributes/Using the Advanced Property Editor:
"1 From the View menu (or the Edit Mode toolbar), choose *Show All Tags*."

3- Creating Web Pages/Composer Preferences/Composer
Use CSS styles instead of HTML elements and attributes:
should be bulleted

4- Customizing Mozilla/Toolbars/Status Bar
"Cookie notification icon cookie notification icon: Appears when a website has
(...)"
Cookie notification icon is repeated twice

5- Customizing Mozilla/Toolbars/component bar
Image of component bar appears to be missing; maybe a broken link.

6- All 3 sub-sections of Customizing Mozilla/Navigator Settings/
should have a "[Return to beginning of section]" link at the end of each of its
respective sub-items.

7- Using Certificates/Getting Your Own Certificate
For a list of certificate authorities, see the online document Client Certificates.
There is no outside/external link image/icon "=>O" for the Client Certificates link.

Comment 36

[Stefan [:stefanh]]

> 
> 4- Customizing Mozilla/Toolbars/Status Bar
> "Cookie notification icon cookie notification icon: Appears when a website has
> (...)"
> Cookie notification icon is repeated twice
>

That is bug 249744.

Comment 37

[Gérard Talbot]

8- Using Certificates/Controlling Validation

"As discussed above under Get Your Own Certificate, a certificate (...)"
Clicking the "Get Your Own Certificate" link should bring up the 
Using Certificates/Getting Your Own Certificate section

Comment 38

[Giacomo Magnini]

(In reply to comment #35)
> 7- Using Certificates/Getting Your Own Certificate
> For a list of certificate authorities, see the online document Client
Certificates.
> There is no outside/external link image/icon "=>O" for the Client Certificates
link.

That's helpFileLayout.css fault, because this rule (a[href^="http://"]:after {
content: url("chrome://help/locale/images/web-links.png"); }) doesn't apply to
such a link (https://). Any idea on how to change it?
Apart from that and 4., I've fixed locally everything else reported.

Comment 39

[Gérard Talbot]

> That's helpFileLayout.css fault, because this rule (a[href^="http://"]:after {
> content: url("chrome://help/locale/images/web-links.png"); }) doesn't apply to
> such a link (https://). Any idea on how to change it?

Yes. Try this:

a[href^="http://"]:after, a[href^="https://"]:after 
{ content: url("chrome://help/locale/images/web-links.png"); }

> Apart from that and 4., I've fixed locally everything else reported.

Good :)

Comment 40

[Giacomo Magnini]

Attachment: Fix all reported problems but 7. (will be addressed elsewhere, covering many more cases)

Comment 41

[Giacomo Magnini]

(In reply to comment #40)
> Created an attachment (id=163529)
> Fix all reported problems but 7. (will be addressed elsewhere, covering many
> more cases)
> 

I meant 4. Sorry for bugspam.

Comment 42

[Ian Neal]

Comment on attachment 163529 [details] [diff] [review]
Fix all reported problems but 7. (will be addressed elsewhere, covering many more cases)

r=[e-mail]

Comment 43

[Ian Neal]

Comment on attachment 163529 [details] [diff] [review]
Fix all reported problems but 7. (will be addressed elsewhere, covering many more cases)

Above patched checked in

Comment 44

[Stefan [:stefanh]]

v