236942 - Clean up code and add style with helpFileLayout.css in help files

Status: VERIFIED FIXED

(Documentation Graveyard :: Help Viewer, defect)

Description

[Stefan [:stefanh]]

Spun-off from bug 235989. 

Need to (where applicable):
* clean up the code in the html files
* add style with helpFileLayout.css instead of content_style.css in the html files
* clean up structure a bit

Comment 1

[Stefan [:stefanh]]

Per discussion on irc with rj_kellr: I will convert the html help files to
xhtml. Hope it's possible to make them all valid xhtml. target="blank" might be
a problem...

Some work have alredy been done in bug 95770. I wonder if this bug should be
dependent of bug 95770?

Comment 2

[[e-mail]]

There's already a bug on making external links open in a new window without
using target="_blank" somewhere...

Comment 3

[Mark Tyndall]

Following on from bug 238267 comment 6 (setting bgcolor and bordercolor 
attributes in xhtml files), I'd like to add a pointer to the changes I 
made for the en-GB language pack, which you may want to adopt.

<http://www.users.madasafish.com/~tyndall/unready/help.zip> (9kB)
(Unfortunately I don't have access to a server which knows about .xhtml 
or allows modification by .htaccess, or I'd give a pointer to a live demo.)

What happens:

I rewrote the pages so that the tables are given class="stripe"; then a 
short piece of Javascript walks through the DOM, finds such tables and 
assigns a class of "even" to every other tr.

.stripe and .even are then appropriately defined in css.  Oh, I also 
changed the table headings into <th>s and styled those appropriately (if 
you're American, I also misspelt Center).

Please feel free to use, modify or criticise as appropriate.

Comment 4

[Stefan [:stefanh]]

Attachment: Patch for shortcuts files, cs_priv_prefs_popup, glossary, forieusers and css file

This patch fixes the following things:

cs_priv_prefs_popup.html --> cs_priv_prefs_popup.xhtml

glossary.html --> glossary.xhtml. The glossary is now in a <dl> and all the
anchors are in lower-case. Also found some "--" which I changed to "&mdash;"

forieusers.html --> forieusers.xhtml

Some new styles added in helpFileLayout.css. Did add some padding to the <h2>:s
too, so the top border doesn't touch the headings.

This patch also fixes the invalid bgcolor (etc) stuff in the shortcuts files
and applies a new style to all the tables in the help files with css.

The patch will also fix bug 225108 -"Typo in the keyboard shortcuts help
section" and parts of bug 235989.

The xhtml files are either valid xhtml 1.1 or xhtml Transitional (since the
target module isn't included in xhtml 1.1 files with target = "blank" in the
code will be in xhtml Transitional)

Patches that fix all changed/removed links and anchors will follow

Comment 5

[Stefan [:stefanh]]

Attachment: New patch for shortcuts files, cs_priv_prefs_popup, glossary, forieusers and css file

New patch - looks like I'll have to use Unix linebreaks in my files to make it
work 100%

Comment 6

[Stefan [:stefanh]]

Attachment: Changes in help-glossary.rdf, help-index1.rdf, help-toc.rdf and jar.mn

Comment 7

[Stefan [:stefanh]]

Attachment: Updated links in other help files

Updated links in the other help files. Also made some other corrections: There
where some links to glossary.html with wrong anchors:
certificate_authority_(CA) doesn't exist and "p3p" should point to
"platform_for_privacy_preferences. Found some old links to mail_help.html as
well - now changed to mail_help.xhtml

Comment 8

[Stefan [:stefanh]]

Attachment: New version of "Updated links in other help files".

Fixed a few errors in the last patch

Comment 9

[Stefan [:stefanh]]

Attachment: New version of patch for shortcuts files, cs_priv_prefs_popup, glossary, forieusers and css file

Sigh, I knew i missed something. This version has the correct path to the
stylesheet.

Comment 10

[R.J. Keller]

Stefan: your patch for forieusers.xhtml doesn't apply. Can you repost only that
file diff'ed please?

The rest of the patches are fine.

Thanks!

Comment 11

[R.J. Keller]

Comment on attachment 145903 [details] [diff] [review]
New version of patch for shortcuts files, cs_priv_prefs_popup, glossary, forieusers and css file

> +table { border-collapse: collapse; border: 1px solid grey; width: 100%; }
> +
> +td { border: 1px solid grey; padding: 4px; }

This (in helpFileLayout.css) breaks the welcome page. You need to modify the
welcome page or else a border will appear around the table on that page making
it look very bad.

Comment 12

[R.J. Keller]

(In reply to comment #11)
> (From update of attachment 145903 [details] [diff] [review])
> > +table { border-collapse: collapse; border: 1px solid grey; width: 100%; }
> > +
> > +td { border: 1px solid grey; padding: 4px; }
> 
> This (in helpFileLayout.css) breaks the welcome page. You need to modify the
> welcome page or else a border will appear around the table on that page making
> it look very bad.
> 

Actually, this messes up a lot of the help pages. I recommend making a class for
this and using that class to style tables you want to have borders.

This adds borders to way to many tables that shouldn't have any.

Comment 13

[Stefan [:stefanh]]

Attachment: New version of patch for shortcuts files, cs_priv_prefs_popup, glossary, forieusers and css file

This patch adresses the messed up tables - sorry about that - for some reason I
assumed that there wasn't any more tables. This patch is the same as the
previous one except for the necessary style changes in the css file/help files.
I made a new diff of all the files in the patch, so hopefully forieusers.xhtml
will work now.

Comment 14

[R.J. Keller]

Comment on attachment 145888 [details] [diff] [review]
Changes in help-glossary.rdf, help-index1.rdf, help-toc.rdf and jar.mn

r=[e-mail], looks good but can't give review for the last patch because
for ie users won't apply. Not sure what the problem is. Make sure you're not
using an old cvs commit. Most of these files were modified so the line numbers
of the patch were off, but For IE Users's canges were too large for the patch
to apply.

Comment 15

[Stefan [:stefanh]]

Thanks for the review! Hmm, not sure what happened with forieusers either. I did
the last changes (2 april)... I'll try to attach a new diff for just that file.
Not sure what to do if that wont help, though.

Comment 16

[Stefan [:stefanh]]

Attachment: forieusers diff

OK, here's a diff for just forieusers.xhtml. Haven't really done anything more
than just created another diff so this might not work.

Comment 17

[R.J. Keller]

stefan_h: Can you email me this file? The patch still won't apply.

Thanks

Comment 18

[Stefan [:stefanh]]

Attachment: Patch 2: privacy_help.html --> privacy_help.xhtml

This patch converts privacy_help.html to xhtml. Changes in help-index1.rdf,
help-toc.rdf, jar.mn and updated links/anchors in using_priv_help (only one
file!) are included.

Fixed some "--" and dead anchors (now removed) in privacy_help as well. Some 
anchors near the end of the file where obviously in the wrong place:

"#browsing_anonymouslyIDX" is now <h2 id="how_can_i_make_sure_unauthorized_..."


"#privacy:IP_addressIDX" is now "<h3 id="internet_address">

Comment 19

[Stefan [:stefanh]]

Keller: if you have the time - can you do the check-in of the patch?

Comment 20

[R.J. Keller]

Fixed checked in, but the log message says the wrong bug :P, so don't think it
isn't checked in by looking at the cvs logs.

Comment 21

[Stefan [:stefanh]]

> Fixed checked in, but the log message says the wrong bug :P, so don't think it
> isn't checked in by looking at the cvs logs.

Thx! BTW: you can remove the old privacy_help.html from the directory.

Comment 22

[Stefan [:stefanh]]

Attachment: Patch 3: mail_sec_help.html --> mail_sec_help.xhtml

This patch converts mail_sec_help.html to xhtml. Changes in jar.mn,
help-index.rdf, help-toc.rdf and help files that had links to mail_sec_help are
included.

This patch also cleans up mail_help.xhtml a bit:
- added the default style to the disclaimer
- removed the whitespaces around "Return to beginning of section"
- removed <hr>:s
- removed the date at the bottom of the document and changed the years in the
copyright to the correct interval

Comment 23

[R.J. Keller]

Comment on attachment 147001 [details] [diff] [review]
Patch 3: mail_sec_help.html --> mail_sec_help.xhtml

stefan_h: Do you have a perl script or something like that that you do these
with? It used to take me FOREVER to get these done, but you're spitting them
out in hours!

Comment 24

[Stefan [:stefanh]]

> stefan_h: Do you have a perl script or something like that that you do these
> with? It used to take me FOREVER to get these done, but you're spitting them
> out in hours!

Heh, they're mostly hand-coded :) BTW, found some <span id="ui"> in
mail_help.xhtml that i think we can remove right away - it's just a section of
the file. Looks a bit odd. I'll attach a new diff for just mail_help.xhtml so
you can take a look.

Comment 25

[Stefan [:stefanh]]

After talking to Keller on irc - the spans should be there.

Comment 26

[R.J. Keller]

Patch 3 checked in! Sorry for the wait. I was having CVS problems.

Comment 27

[Stefan [:stefanh]]

Attachment: Patch 4: certs_help.html --> certs_help.xhtml

Complete patch for the conversion of certs_help.html to xhtml. Notice that the
file now has a <h1> as a "top" heading. If you look at the TOC:s and sub-TOC:s
in the Help viewer that <h1> should be a <h3>... The file shouldn't really have
a "In this section" either... But I think it's better to leave that until we
have all the files in the xhtml format.

Comment 28

[Stefan [:stefanh]]

If you look at the TOC:s and sub-TOC:s
> in the Help viewer that <h1> should be a <h3>... The file shouldn't really have
> a "In this section" either... But I think it's better to leave that until we
> have all the files in the xhtml format.

Keller: If you have any suggestions on how to deal with this in a better way
(than just leaving the sub-TOC:s and changing headings so there always will be
at least one <h1> per file) - please add a comment.

Comment 29

[Stefan [:stefanh]]

Attachment: Correct version of Patch 4

Sigh... forget to change Mozilla to &brandShortName. Sorry for all the bugspam.

Comment 30

[R.J. Keller]

Comment on attachment 147384 [details] [diff] [review]
Correct version of Patch 4

looks good! Fix checked in.

Comment 31

[Stefan [:stefanh]]

Attachment: Patch 5: help_help.html --> help_help.xhtml

Thx for the check-in! Here's a complete patch for the conversion of
help_help.html. Did some small changes to the text about printing since I
wanted the print button image to line up vertically with the image of the
navigation buttons. Looks also more consistent with the image before the list.
Removed all the whitespaces, added some — etc etc. Oh, added the Search
Tips to the "In this section".

Also added the copyright line to welcome_help.xhtml and changed the Doctype to
xhtml Transitional - that's not a valid xhtml 1.1 file.

Comment 32

[Stefan [:stefanh]]

Comment on attachment 147409 [details] [diff] [review]
Patch 5: help_help.html --> help_help.xhtml

BTW, my indentation isn't really consistent. Just started to indent the lists
in a more correct way.

Comment 33

[R.J. Keller]

Comment on attachment 147409 [details] [diff] [review]
Patch 5: help_help.html --> help_help.xhtml

I thought I told you, but maybe I forgot, but I got my own special plans for
help on help documentation.

Sorry :(. I should've remembered to tell you!

Comment 34

[Stefan [:stefanh]]

Attachment: Patch 5b: ssl_help.html --> ssl_help.xhtml

Patch for the conversion of ssl_help.html to xhtml. Interestingly, this link in
help-index1.rdf didn't exist in ssl_help:"ssl_help.html#SSLIDX". That is now
changed to "ssl_help.xhtml". Fixed a typo (Important note re TLS --> Important
note regarding TLS) and removed the sub-level "In this section".

Comment 35

[R.J. Keller]

Comment on attachment 147511 [details] [diff] [review]
Patch 5b: ssl_help.html --> ssl_help.xhtml

Looks good! r=me, and your fix is checked in!

Comment 36

[Stefan [:stefanh]]

Attachment: Patch 6: page_info_help.html --> page_info_help.xhtml

Patch that converts page_info_help.html to xhtml.

Found two dead anchors in help-index1.rdf:

line 1714 -- nc:link="page_info_help.html#privacy:P3P_standard_andIDX"/>
line 1734 -- nc:link="page_info_help.html#privacy:viewing_site_policyIDX"/>

They were simply changed to "page_info_help.xhtml"

Comment 37

[Stefan [:stefanh]]

Attachment: New version of Patch 6 including fix for profiles_help and privsec_help

Updated Patch 6 with some more files: profiles_help and privsec_help. So, this
new version of the patch also converts these files to xhtml.

Comment 38

[R.J. Keller]

Comment on attachment 148232 [details] [diff] [review]
New version of Patch 6 including fix for profiles_help and privsec_help

Neil, can you take this review?

Thanks!

Comment 39

[[e-mail]]

Comment on attachment 148232 [details] [diff] [review]
New version of Patch 6 including fix for profiles_help and privsec_help

You need to fix the index entry for P -> profile -> deleting a profile to
display the right section, and the link from Privacy and Security to
Validation.

Comment 40

[Stefan [:stefanh]]

(In reply to comment #39)
> (From update of attachment 148232 [details] [diff] [review])
> You need to fix the index entry for P -> profile -> deleting a profile to
> display the right section

Hmm, I'm not sure I follow you on this one. Deleting a profile is in the same
section as renaming a profile. If you want the index entry for "deleting a
profile" to display just the section that starts with "To delete a profile..."
we'll miss the intro on how to open the profile manager.

Comment 41

[[e-mail]]

Doesn't the link from Contents already do that?

Comment 42

[Stefan [:stefanh]]

Shouldn't P --> Profile --> deleting a profile display "Deleting or renaming a
profile" (it is now)? Or is the problem that "Deleting or renaming a profile"
doesn't displays at all?

Comment 43

[[e-mail]]

(In reply to comment #42)
>Shouldn't P --> Profile --> deleting a profile display "Deleting or renaming a
>profile" (it is now)? Or is the problem that "Deleting or renaming a profile"
>doesn't displays at all?
After the patch it doesn't display what it displayed before the patch.

Comment 44

[Stefan [:stefanh]]

Ah, I got it - a typo...

Comment 45

[Stefan [:stefanh]]

Attachment: Patch with fixed typo in index entry and correct link to validation_help.html (instead of xhtml)

This is the same diff as the previous, except for the above changes (two lines
edited).

Comment 46

[Stefan [:stefanh]]

Attachment: New diff for page_info_help

This diff includes the changes made in bug 90894.

Comment 47

[Frédéric Chateaux]

Stefan, you've forgotten to change the <i> tag to <em> in those two files :
cert_help.xhtml, glossary.xhtml.

ssl_help, privacy_help, mail_sec_help, forieusers and cs_priv_prefs_popup aren't
affected.

I don't know for other xhtml files.

Comment 48

[[e-mail]]

I checked in attachment 150754 [details] [diff] [review] except for page_info_help.xhtml for which I used
attachment 150761 [details] [diff] [review].

Comment 49

[Stefan [:stefanh]]

Keller, can you remove the obsolete html files?

Comment 50

[Stefan [:stefanh]]

(In reply to comment #47)
> Stefan, you've forgotten to change the <i> tag to <em> in those two files :
> cert_help.xhtml, glossary.xhtml.
> 
> ssl_help, privacy_help, mail_sec_help, forieusers and cs_priv_prefs_popup aren't
> affected.
> 
> I don't know for other xhtml files.

Ah, thx Frédéric! If you find more errors please post them in here. I'll be
attaching my xhtml conversion patches in bug 95770 from now on.

Comment 51

[Stefan [:stefanh]]

> Stefan, you've forgotten to change the <i> tag to <em> in those two files :
> cert_help.xhtml, glossary.xhtml.

The <em> tags in these two files are fixed in attachment #151759 [details] [diff] [review] in bug 95770.
	

Comment 52

[Giacomo Magnini]

Can this bug be resolved/fixed now that all the help files are moved to xhtml
format?

Comment 53

[Stefan [:stefanh]]

(In reply to comment #52)
> Can this bug be resolved/fixed now that all the help files are moved to xhtml
> format?

Yes :) The remaining issues in the xhtml files will be fixed a separate bug.

Comment 54

[Giacomo Magnini]

Would you please add me to the CC list of that bug please? TIA, Giacomo. :)