95770 - The help documentation should be formatted in some better way

Status: VERIFIED FIXED

(SeaMonkey :: Help Documentation, defect)

Description

[Cormac F]

Currently, the pages in "help contents" are written as HTML 4.01 Transitional,
even though they have no DOCTYPE declaration and some of them do not validate as
correct(see bug 95769).
This isn't good enough for a browser that tries to support the latest standards.
These files should be rewritten as XHTML 1.0 and styled with a CSS. We should
ensure in future that all the browser's internal html pages validate correctly. 
The advantages of XHTML over HTML are well documented (see the many articles on
alistapart.com and similar sites), improving accessibility (particularly
important for the help pages) and making the code easier to modify in future. 

A 6.0 browser shouldn't be using things like "bgcolor" in its own pages when
most sensible websites have abandoned such hacks ages ago.

(using build 2001081603, winNT)

Comment 1

[Henri Sivonen (:hsivonen)]

I agree on CSS styling and validation.

However, I don't see XHTML 1.0 (*in this case*) providing any benefit over HTML
4.01. OTOH, if you want to switch to XHTML, why wouldn't you switch directly to
XHTML 1.1 (and parsing it with the XML parser, too)?

Comment 2

[Lasse Marøen]

I totally agree, though it should be the latest version, xhtml 1.1, as Henri
says. If this involves just editing the html files I'd be happy to do it.

Comment 3

[Daniel Brooks [:db48x]]

Either this bug, or bug 95769 is a dup, but it is a good project either way.

Comment 4

[RC]

Except that (almost) no one reads the help files.

Reporter (Cormac,) since you feel so strongly about this,
do you want to pitch in and rewrite some of the docs?

Wouldn't be that hard to feed them to an HTML Tidy script ...

Comment 5

[Cormac F]

I wasn't aware there was a new version of xhtml - have to have a look at that.
Mike T - I wouldn't say I felt strongly about it! Just an observation from a 
standards-oriented person - I'll certainly have a look at the help files over 
the weekend and see how much work is involved (laborious repititious work, I 
imagine, but i might take it off your hands.)

Comment 6

[Henri Sivonen (:hsivonen)]

Please note that:
* Parsing XHTML as tag soup using the HTML parser is uncool and isn't a good 
  example for others. (XHTML 1.1 shouldn't be sent as text/html on the Web, 
  either.)
* Parsing local files as XML requires the suffix .xml.

Probably not worth the trouble.

(Removing self from CC.)

Comment 7

[Alexey Chernyak]

Local XHTML pages will be parsed with XML parser if they have .xhtml extension.
Converting these to XHTML and parsing it as XML would also require much more
caution when they are modified in the future, because of strict nature of XML.

Whole work would require modification of about 25 files totalling in about
450KiB of HTML code.

Also the pages seem to contain screenshots of Netscape, not Mozilla. I'm not
sure if there's a bug for that. And screenshots are done in GIF, might as well
convert them to PNG to be extra cool.

Comment 8

[James Green]

Um, looking at the some of the help docs, the HTML is pretty awful. As an
example, certs_help.html contains lots of <p>&nbsp;</p> stuff which as we all
know Mozilla should never need and indeed causes problems on many "old style" sites.

Hell, I can have a go at this, and provide a zip at the end containing the new
.xml files. Anyone wanna join me?

Comment 9

[Alexey Chernyak]

Please note that if extension is converted to .xml or (more feasible) .xhtml the
pages will be affected by bug 44458.

So take caution when deciding to change the file extension, it might be a good
idea to leave it as .html after conversion until XHTML is fully supported.
Officially Mozilla does not have XHTML support as far as I know.

Comment 10

[Ian Oeschger (gone)]

Updating summary and ACCEPTING (was:"'Help' pages should be rewritten as XHTML
1.1"). There seems to be some disagreement about what format is best, but
certainly the docs could be improved and made better exemplars of our standard
support.

Let's track the NS v. Mozilla doc issues in 46917 (whose summary might also want
updating) and track format stuff like XML/XHTML/HTML here. 

Comment 11

[Ian Oeschger (gone)]

*** Bug 95769 has been marked as a duplicate of this bug. ***

Comment 12

[Heikki Toivonen (remove -bugzilla when emailing directly)]

I am getting ready to fix bug 44458. However, I would like you to consider if
you REALLY want to use XML-based help. The reason I am saying this is that it is
possible our HTML handling might be faster. Also we have incremental layout for
HTML (which matters if the file is large). And finally, we have more bugs in
XHTML than plain HTML. If you have considered all these and XML still wins, I am
fine with it.

Comment 13

[Ian Oeschger (gone)]

Yeah, don't sweat that on our account, Heikki. After looking at this stuff a
little more, I am convinced that HTML is going to be the best here.

Comment 14

[René Rhéaume]

I started to sanitize those HTML files right after I checked then out (that was
on July 25th 2002) from the tree. They will stay HTML files, but they will obey
to XHTML 1.1 rules.

Question: Do I really need to prefix hyperlinks destination, images source and
style-sheet link by "chrome://help/locale/"?

Comment 15

[Tim Gerundt]

Yesterday i see the invalid HTML in the german de-AT help and create the bug 184398.
Then i found this bug, with the same problem in the english help.
How far is the sanitize? If i can, i would help!

But i think XHTML 1.0 is the better way, because the most browser can show them.
Ok, normally Mozilla show his own help, but is this a reason to exclude other
browser? ;)

A other way would be XML and a transformer to XHTML, like the Apache
documentation use:
Documentation Project <http://httpd.apache.org/docs-project/>
Module Format and Transformation
<http://httpd.apache.org/docs-project/docsformat.html>

But clean XHTML 1.0 and CSS should be the easiest way.

Comment 16

[Robert Kaiser]

I think that HTML documents are the best way to go because of the several
comments mentined here (speed, parser etc.) - but make those HTML documents
apply to the XHTML 1.1 rules, like comment #14 taks about.
Please make it with XHTML 1.1 in mind (and not just 1.0), and please add a HTML
4.01 Strict doctype to the files (for now).

It's really a bad example if our own internal HTML files don't apply to the high
standards we say we'd like to see from others...

Comment 17

[Tim Gerundt]

Attachment: revamp and valid version from 'content_style.css'

I revamp the file 'content_style.css' and made it valid CSS.
It was a little bit to complex. :)

I take the most from the old css-file.
Only few changes, for example:

* Rewrite the syntax for better read!
  I hope! ;)

* Remove the 'line-height' from class '.inthissection'
  and '.inthissections'.
  I looks unaesthetic at long lines with a line break.

* 'text-align:left' and 'font-style:normal' has
  no effect at headers.

* Add 'px' to the most numerical values.

I hope you can use it!

Comment 18

[Daniel Wang]

marking dependent on bug 46917. Whoever re-writing the Help files
can reformat the HTML code along the way.

Comment 19

[Daniel Wang]

*** Bug 123023 has been marked as a duplicate of this bug. ***

Comment 20

[Hixie (not reading bugmail)]

If our XML parser is slower than our HTML parser, it needs fixing.

If we have bugs in our XHTML code, _that_ needs fixing.

If we can use our help system as a way to push both of the issues, all the better.

I think we should go with XHTML. It would also allow us to use entities to brand
the help files easily.

Comment 21

[Heikki Toivonen (remove -bugzilla when emailing directly)]

I would actually bet that our XML/XHTML parsing is faster than HTML. There are
some bugs (but not sure if they affect help files). Also there are some
differencies between HTML and XHTML that might need to be addressed in help
content (like usemap referring to ID values instead of name) but I am not sure
if we have those in help content.

The biggest issue as far as I see it is incremental layout. HTML has it,
XML/XHTML doesn't, and I believe it would be a lot of work to implement it.

Regarding branding, someone pointed out on IRC that it could be done in HTML as
well by using CSS-generated content.

But still, personally I'd like us to use XHTML for help and fix all the bugs
that prevent that from happening. I just don't see it as a high priority.

Comment 22

[Mike Kaply [:mkaply]]

That's because you're not trying to create a Mozilla based browser. OR have 
current help in Mozilla.

The help situation in Mozilla is REALLY bad.

People should be able to create a derivative browser and use Mozilla help by 
changing branding info in one place.

They can't do this today, and Netscape doesn't bother contributing the help 
because it says "Netscape" everywhere.

If we could solve this, Netscape help could be contributed to Mozilla and life 
would be very good.

Comment 23

[Brant Gurganus]

I was going to try updating the mozilla.org help docs a few days ago, but some
of my contacts told me the Netscape was about to drop a load into the tree. 
Just though I would let the folk following this bug know after seeing the recent
comments.

Comment 24

[Brant Gurganus]

Now that updated help is in, I am going through all the Documentation > User
bugs that are not verified and updating them as appropriate.  I will probably
then work on rewriting/fixing stuff.

Comment 25

[Daniel Wang]

*** Bug 201735 has been marked as a duplicate of this bug. ***

Comment 26

[Michael Stadlbauer]

Attachment: cert_dialog_help.html in HTML4.01 strict

I've updated the cert_dialog_help.html to HTML4.01 Strict

Comment 27

[Michael Stadlbauer]

Attachment: cert_dialog_help.html in XHTML1.0

The same attachment as in comment #26 only this time it's a validated XHTML1.0
File with a HTML4.01 Strict doctype. Which direction are we now going?

Comment 28

[Ian Oeschger (gone)]

moving stuff over to an outside-the-firewall email for the time being, looking
for people to pick these Help and doc bugs up for me.

Comment 29

[R.J. Keller]

--> me

This will be fixed for 1.6a

Comment 30

[Mike Kaply [:mkaply]]

For the record, we (IBM) have nice XHTML versions of the Netscape 7.1 helps that
have been cleaned up. We have replaced Mozilla with &brandShortName; so it can
be easily replaced, as well as putting Netscape content in CSS tags so it can be
easily eliminated.

Comment 31

[R.J. Keller]

mkaply: Currently, me and Brant Gurga are rewriting the help docs for 1.6 alpha
(when firebird and thunderbird go on the branch) that use new XHTML 1.1 and CSS
layout.

Comment 32

[R.J. Keller]

--> Browser: Help

Comment 33

[R.J. Keller]

mkaply: do you have any form Firebird/Thunderbird help documentation? Seamonkey
Help is basically done. Unless mozilla.org decides to not use Firebird as the
default during 1.6a, Seamonkey Help is done.

If you have any documentation related to the birds, feel free to attach them so
I can take a look. The new XHTML 1.1/CSS help docs are on the MozDev CVS server
at :pserver:[e-mail]:/cvs under firebirdhelp.

Comment 34

[R.J. Keller]

mkaply: Could you attach those help docs with the cleaned up XHTML you have? We
may see them checked in during 1.6a.

Comment 35

[R.J. Keller]

mkaply: Are your XHTML files XHTML 1.1 or 1.0?

Comment 36

[R.J. Keller]

mkaply: Make sure that any help docs you have are the latest. There's been a lot
of typo and general content changes for help docs.

Comment 37

[Daniel Wang]

Keller, if moving to XHTML allows us to use external entities, then we should
fix this first. I don't think we have any patch blocking this. Change severity
to BLOCKER?

Comment 38

[R.J. Keller]

sure. Blocking all doc dev (since I control it ;)). I got this up on the MozDev
CVS server so I and others can edit it freely.

export CVSROOT=:pserver:[e-mail]:/cvs
cvs -z3 -q co -P firebirdhelp/mozdoc_fbl_l

I'm hoping to implement the same CSS layout in Mozilla Help as in Firebird Help.

Comment 39

[R.J. Keller]

changed my mind. Let's wait until help gets its own module (and maybe if we're
lucky, checkin rules) for this.

Comment 40

[R.J. Keller]

Attachment: New CSS

This is the CSS I'd like to use in the new XHTML 1.1 layout. This CSS file
would go in chrome://help/locale/helpFileLayout.css (or
mozilla/extensions/help/resources/locale/en-US/helpFileLayout.css).

This CSS is a modified version of the CSS in Firebird Help
(http://firebirdhelp.mozdev.org). Hopefully we can start moving the help files
over to this new CSS layout one at a time.

Comment 41

[R.J. Keller]

Attachment: cert_dialog_help.xhtml

The new cert_dialog_help in XHTML 1.1 using &brandShortName; instead of the
word Mozilla so that people distributing Mozilla won't have to redo the help
HTML.

Comment 42

[[e-mail]]

Comment on attachment 132770 [details]
cert_dialog_help.xhtml

><DIV class="contentsBox">In this section:
>  <DIV class="makeLeftMargin">
>    <A href="#">Certificate Viewer</A>
>    <A href="#">Choose Security Device</A>
>    <A href="#">Certificate Backup</A>
>    <A href="#">User Identification Request</A>
>    <A href="#">New Certificate Authority</A>
>    <A href="#">Web Site Certificates</A>
>  </DIV>
></DIV>
Are these hrefs supposed not to point anywhere?

Comment 43

[R.J. Keller]

Comment on attachment 132770 [details]
cert_dialog_help.xhtml

oh sorry! Forgot to hook up the links! I'll get that done.

Comment 44

[[e-mail]]

Also if this is a list then it should use <ul> and <li> tags rather than <div> -
CSS should then be used to fix up unwanted styles e.g. bullets, indents, but the
document is still reviewable without the CSS :-)

Comment 45

[R.J. Keller]

Where does it use <div> instead of <ul>s? If it does, then that's an error.

it looks reviewable without the CSS. The review would be the content basically.
I will make a new version of the file with the hyperlinks soon.

I'll try and diff the new files instead of posting them like this. Now that I
have CVS access, it should be easier.

Comment 46

[R.J. Keller]

Attachment: Patch for cert_dialog_help

Full patch. Includes new CSS, new XHTML, along with help-toc and help-index
changes where appropriate.

Comment 47

[R.J. Keller]

Comment on attachment 133042 [details] [diff] [review]
Patch for cert_dialog_help

Neil, can you review this? This patch has the bullet stuff you wanted with the
section listings.

I did a lot of debugging with this patch, so it should be good.

Comment 48

[[e-mail]]

Comment on attachment 133042 [details] [diff] [review]
Patch for cert_dialog_help

No jar.mn changes :-/

>+    <!ENTITY % brandDTD SYSTEM "chrome://global/locale/brand.dtd" >
>+    %brandDTD;
But you don't use it...

>+        a certificate authority—that is, a service that issues certificates for
Something very strange is going on here; I'm not seeing your em dash when the
page is loaded from the chrome url, although it works fine opening the original
file from the source tree. Unless you can get that sorted you'll need to switch
to xhtml entities I'm afraid.

>+    <br/><br/>
These blank lines look odd.

>\ No newline at end of file
Fix this.

>+.contentsBox :link {
>+	display: block;
>+}
Personally I think this looks odd - it makes the link invisibly stretch to the
right.

>-	 nc:link="cert_dialog_help.html#server_certificate_problemsIDX"/>
>+	 nc:link="cert_dialog_help.html#web_site_certified_by_an_unknown_authority"/>
You forgot to change this one to .xhtml

Comment 49

[R.J. Keller]

Attachment: Patch -> 1.2

> No jar.mn changes :-/

Sorry about this! I have 6 bug fixes in one directory and forgot to tell diff
to diff that file. It's done in this patch.

> But you don't use it...

Sorry, forgot to hook that up.

> Something very strange is going on here;

Fixed

> These blank lines look odd.

That's in the help files now. I added more <br/> tags to make it looks better
(IMO), but not sure what you have in mind for here.

> Personally I think this looks odd

This is obsolete CSS, so it's removed in this patch.

> You forgot to change this one to .xhtml

Fixed


I also fixed a ton of dead links I found.

Comment 50

[[e-mail]]

Comment on attachment 133074 [details] [diff] [review]
Patch -> 1.2

>         locale/en-US/help/certs_prefs_help.html         (locale/en-US/certs_prefs_help.html)        locale_dialogs.html) 
Something went wrong with the patch here.

>+	  any of your encrypted email—including both encrypted messages that you have sent and
Another one that wouldn't load :-(

>+  server in the form of the site's domain name. For example, the domain name for the &brandShortName;
>+  web site is <tt>www.mozilla.org</tt>. If the domain name in a server's certificate
Oops... that's not going to work :-/

Comment 51

[R.J. Keller]

Attachment: Patch -> 1.3

> Something went wrong with the patch here.

No, this is actually a problem in the build. I noticed it this morning. I'm
puzzled as to how it didn't break the trunk.

Comment 52

[Daniel Wang]

looks fine except for

-       <rdf:Description ID="Composer:keyboard_shortcuts"                        
  :                                         
+       <rdf:Description ID="Composer:keyboard_shortcuts"
  :
+</rdf:Description>
+
+<rdf:Description about="#Composer">
+   <nc:subheadings>
+     <rdf:Seq><rdf:li>

should be fine as long as you commit file in unix text format.

+<rdf:Description about="#Composer">
+   <nc:subheadings>
+     <rdf:Seq><rdf:li>

is probably not needed.

Comment 53

[[e-mail]]

Comment on attachment 133109 [details] [diff] [review]
Patch -> 1.3

I've no idea what Danial was going on about, patch looks fine, just don't
forget to check in the new .css file too :-)

Comment 54

[R.J. Keller]

OK, Patch 1.3 is checked in! I'll try and get more of the help files attached
for review today.

Comment 55

[Mike Kaply [:mkaply]]

Attachment: XHTML help files

Sorry this has taken so long.

If anyone is interested, these are 1.4 versions of all the help files we did in
XHTML for IBM Web Browser.

entities are used everywhere, and we used CSS to hide netscape content (see the
end of content_style.css)

Comment 56

[Daniel Wang]

Keller, can we change extensions/help/resources/jar.mn to change filenames in
the .jar instead of creating new files and deleting old ones in the CVS?

Comment 57

[[e-mail]]

If the content of the help files is going to be substantially different then I
don't see any point in keeping the history of the old files.

Comment 58

[Daniel Wang]

Michael Kaply, please review
http://bugzilla.mozilla.org/showdependencytree.cgi?id=46917 and work on files
that don't have patches holding. Currently, nav_help.html, mail_help.html,
glossary.html, and cs_*.html are heavily worked on.

I'm pretty sure you can do the following:
  composer_help.html
  welcome_help.html
  shortcuts.html
  profiles.html
  page_info_help.html
  help_help.html
  forieusers.html

I'll review your xhtml versions of these files when I've time.

Comment 59

[R.J. Keller]

Attachment: certs_prefs_help.html moved to XHTML.

certs_prefs_help.html moved to the new XHTML/CSS Layout.

Comment 60

[Christopher Aillon (sabbatical, not receiving bugmail)]

Comment on attachment 133524 [details] [diff] [review]
certs_prefs_help.html moved to XHTML.

>Index: locale/en-US/certs_prefs_help.xhtml

>+
>+<h1 id="privacy_and_security_preferences_certificates">Privacy &amp; Security Preferences -
>+  Certificates</h1>
>+
>+<p>This section describes use the Certificates preferences panel. To view Certificates
>+  preferences, follow these steps:</p>
>+
>+<ol>
>+   <li>Open the Edit menu and choose Preferences.</li>
>+   <li>Under the Privacy &amp; Security category, click Certificates. (If no subcategories
>+     are visible, double-click Privacy &amp; Security to expand the list.)</li>
>+</ol>
>+
>+<h3 id="client_certificate_selection">Client Certificate Selection</h3>


What happened to <h2>?

Comment 61

[R.J. Keller]

Yes, caillon, this is an issue. What I was going to do was to port all the help
docs over for 1.6a, then for 1.6b or 1.6 I'll go through and change some of the
<h1>'s to <h2>'s where it's appropriate (since there's a lot of areas where
that's more appropriate). I'm trying to 

I don't have a whole lot of time to go through it right now, so I'm going to
wait until all the docs are moved over to the new CSS layout.

Comment 62

[Christopher Aillon (sabbatical, not receiving bugmail)]

Ah ok.  Well if this is just a case of a file being moved, please make sure the
RCS file gets copied.  Leaf?  Could you do the honors?

Comment 63

[R.J. Keller]

caillon, I got a more appropriate answer to your question.

If you notice in mail_help.html, h1 tags are used as a section heading, then h2
tags are used as a sub-section heading, then h3 tags are used to show each topic
of each section.

If you notice, certs_prefs_help doesn't have sub-sections, so h2 tags would
never be used. mail_help.html does have sub-sections, so h2 tags would be used.


This may be changed in the future. I'm not too happy with it, but it'll do for now.

Comment 64

[Christopher Aillon (sabbatical, not receiving bugmail)]

Comment on attachment 133524 [details] [diff] [review]
certs_prefs_help.html moved to XHTML.

Since this is just moving files around, r=caillon for the changes to jar.mn,
help-index1.rdf, help-toc.rdf, and privsec_help.html.  Please wait to hear back
from leaf about moving the .rcs files though before landing this.

Comment 65

[R.J. Keller]

-> 1.6 beta

This will leak into beta a bit.

Comment 66

[R.J. Keller]

Comment on attachment 133524 [details] [diff] [review]
certs_prefs_help.html moved to XHTML.

Can we get this for 1.6a? I kinda missed the cut.

Comment 67

[Asa Dotzler [:asa]]

Comment on attachment 133524 [details] [diff] [review]
certs_prefs_help.html moved to XHTML.

a=asa (on behalf of drivers) for checkin to 1.6alpha

Comment 68

[Michael Stadlbauer]

RJ, feel free to email me if you need some help with the XHTML1.1 conversions.

Comment 69

[Dave Miller [:justdave]]

RCS file moves have been completed.

all *.html files in 
mozilla/extensions/help/resources/locale/en-US
have been *copied* to *.xhtml with the existing revision history intact.

The new .xhtml files have had all existing tags and branches removed so that
they only exist on HEAD and won't be pulled when people pull old tags.  (people
pulling by date will get them, but oh well)

The existing *.html files are still there.  I'm told those can't be removed
until all of the places that refer to them are fixed.  Those will need to be cvs
deleted at the time those references are fixed.

There is one .xhtml file that was already created via cvs add.  Your best bet at
preserving history on that one is adding a comment at the top of the file noting
that the previous history is in the .html version.  Since it's already existed
for 3 weeks, we can't copy the old .html overtop of it without causing cvs
conflicts for the people who already have it checked out.

Comment 70

[Michael Stadlbauer]

Attachment: composer_help.xhtml

Here is the patch for composer_help.xhtml. As you (RJ) suggested, the old <a
name=""> tags are only commented out. The patch is quite long and complex,
because I did some re-formatting for a better source reading. That's why each
out-commented <a name="">-tag (or group of tags) has "anchorX:" in front, so
you can easily search for the TOC-changes.

I've also made a change in the helpFileLayout.css, because the <tt>-tag is to
small (at the end of the patch)

Comment 71

[Alexey Chernyak]

Why did you commented out <a name> tags instead of replacing them with <a id> ?

Comment 72

[Michael Stadlbauer]

Why should I use any <a's> when I can put it in <h1>, <p>, and so on?

Comment 73

[R.J. Keller]

Alexy: I told him to comment out the <a> tags. We are moving to using element
IDs instead of name tags because using <a name=""> causes sometimes in rare
situations causes layout problems. The real reason is because it's easier to
read and is cleaner.

Comment 74

[Alexey Chernyak]

Ah, sorry, I didn't understand your comment, since I were't present during your
conversation. Thumbs up.


+<p>&nbsp;</p>

+<p><br /></p>

are these really nessesary?

Comment 75

[Michael Stadlbauer]

No, not really Alex but I didn't want to change to many things in the CSS-file.
Let's hear RJ about hese.

Comment 76

[Alexey Chernyak]

If we're doing things properly, those should be removed.
And I see nothing prescious about CSS files.
Hack em mercylessly (while minding all the pages they apply to).

Comment 77

[Michael Stadlbauer]

Ok, that's correct. I'm waiting for RJs review if there is anything else to correct.

Comment 78

[R.J. Keller]

> If we're doing things properly, those should be removed.

yeah, they should, but that's not really what this bug covers. This bug is about
getting the old HTML Help documentation to XHTML and moving to the new CSS
layout (which is viewed best when using stuff like IDs). This is not a cleanup
bug, but cleanup can be a plus ;).

I'll be reviewing the composer files once I attach the mail XHTML docs, which
will be very soon.

Comment 79

[R.J. Keller]

Comment on attachment 135084 [details] [diff] [review]
composer_help.xhtml

Wow! This is good stuff! A couple of comment I have:

I would follow comment #74 because the composer docs seem to have a much bigger
problem with this than the other help docs do.

I'd also remove <hr> tags where you see them. Any kind of borders should be
done by the CSS.

Comment 80

[Daniel Wang]

+  <p><a href="#file_not_found"><tt><em>Filename</em> not found</tt></a></p
should be
+  <p><a href="#file_not_found"><tt><var>Filename</var> not found</tt></a></p

Comment 81

[Alexey Chernyak]

Yes, "moving to the new CSS layout" includes getting rid of those and has
nothing to do with cleanup.

I see nothing wrong with <hr>. They are not borders, they are separators.
However <hr> indeed could be removed or renamed in the future:
http://www.w3.org/TR/xhtml2/mod-block-text.html#sec_8.6.

Comment 82

[R.J. Keller]

> Yes, "moving to the new CSS layout" includes getting rid of those and has
> nothing to do with cleanup.

Usually no, but this help doc seems to have a huge issue with them.

> I see nothing wrong with <hr>. They are not borders, they are separators.
> However <hr> indeed could be removed or renamed in the future:
> http://www.w3.org/TR/xhtml2/mod-block-text.html#sec_8.6.

The problem is that headings have a border-top attribute set on them (that
simulate <hr>'s) or special formatting that doesn't look very good with an <hr>
above them.

Comment 83

[Michael Stadlbauer]

Attachment: composer_help.xhtml

Revised patch.
All <p>&nbsp</p> (and similar) are gone and in the CSS-file changed.
I killed all the <hr> and made the gaps between the sections a little bigger
(also in the CSS), RJ feel free to change this into another layout if you think
so.
Daniel thanks for comment #80 - I didn't thought about that.

Comment 84

[R.J. Keller]

Attachment: mail_help.html -> xhtml

These are the mail docs. The TOC and the Index were updated, along with any
links linking to mail_help.html.

Comment 85

[R.J. Keller]

Comment on attachment 135115 [details] [diff] [review]
composer_help.xhtml

very close! The word "Mozilla" should be replaced with &brandShortName;
(because if we didn't, then the DTD  wouldn't be necessary). so the title would
be "Creating Web Pages with &brandShortName; Composer" instead of "Creating Web
Pages with Mozilla Composer" and everywhere else the word Mozilla is in the
document.

Also, if you want to do a little extra, you can take those comments out now. I
just wanted one copy with the comments so I can change the TOC. If you don't
have time, I'll do it.

Comment 86

[Daniel Wang]

Comment on attachment 135115 [details] [diff] [review]
composer_help.xhtml

xxxxSDX can be safely removed, we no longer have a search database

there are some unnecessary formatting. Can you revisit your working page and
remove these?

-<li>Click the New button in Composer's toolbar.</li>
+  <li>Click the New button in Composer's toolbar.</li>
create_document -> creating_web_pages_with_mozilla_composer
comp_start

links from TOC and index will be broken with this patch. Michael, can you fix
this too? If you don't want to do it, I can follow up w/ a toc patch

Comment 87

[R.J. Keller]

Comment on attachment 135115 [details] [diff] [review]
composer_help.xhtml

I'm not sure why you review+ this, daniel.

>links from TOC and index will be broken with this patch.

I told michael I was going to do this. I don't want it done until the mail help
xhtml is in because it'll cause a collision.

Comment 88

[Michael Stadlbauer]

Attachment: next composer_help.xhtml patch

@RJ: &brandShortName; is inserted (except in links & urls) and all old <a>'s
were removed.

@Daniel: I don't think that was unnecessary formatting. There were some nesting
errors and for proper fixing, I made the source more readable. I hope that
makes not to much trouble.

btw: Can someone tell me how I can post a patch AND ask for a review at the
same time?

Comment 89

[R.J. Keller]

Comment on attachment 135197 [details] [diff] [review]
next composer_help.xhtml patch

Looks good to me. I haven't done too in-depth of a look at the anchors since
I'll be looking at them when I do the TOC, index, and link update changes. If I
see anything then, I'll tell you.

Nobody check this in, BTW. This is far from ready for checkin. Still need my
link updating patch.

Comment 90

[Michael Stadlbauer]

All links have been checked (with a link checker tool) and the w3-validator says
that it has only one error (a target="_blank" at an extern link). The hole
webpage looks nice in mozilla 1.5, so there should no real problem. If you need
something else, feel free ...

Comment 91

[R.J. Keller]

Attachment: mail_help with some enhancements

cleaned up a little and fixed some dead links I found with HomeSite.

Comment 92

[[e-mail]]

Comment on attachment 135622 [details] [diff] [review]
mail_help with some enhancements

>Index: locale/en-US/forieusers.html
Usual .xhtml sync issues.

>Index: locale/en-US/helpFileLayout.css
>===================================================================
>RCS file: /cvsroot/mozilla/extensions/help/resources/locale/en-US/helpFileLayout.css,v
>retrieving revision 1.2
>diff -u -r1.2 helpFileLayout.css
>--- locale/en-US/helpFileLayout.css	21 Oct 2003 23:24:10 -0000	1.2
>+++ locale/en-US/helpFileLayout.css	16 Nov 2003 03:09:49 -0000
>@@ -64,11 +64,11 @@
> 	margin-left: 25px;
> }
> 
>-table {
>+.colorTable {
> 	background-color: #eeeeee;    /* really light grey */
> }
> 
>-td {
>+.colorCell {
> 	border: 1px solid #999999;    /* grey */
> 	vertical-align: top;
> }
You'd better decide whether you're using this version or the version in the
other patch.

Comment 93

[Asa Dotzler [:asa]]

Comment on attachment 135622 [details] [diff] [review]
mail_help with some enhancements

a=asa (on behalf of drivers) for checkin to 1.6beta

Comment 94

[R.J. Keller]

patch "mail_help with some enhancements" has been checked in! I'll get to work
on updating the help TOC and docs for the new composer XHTML docs.

Comment 95

[Frédéric Chateaux]

Wrong link in welcome_help:

User Feedback: http://www.mozilla.org/qualify/qfa.html

Should be: http://www.mozilla.org/quality/qfa.html

Comment 96

[[e-mail]]

Attachment: Trivial URL fix

Comment 97

[R.J. Keller]

Comment on attachment 137296 [details] [diff] [review]
Trivial URL fix

r=rlk

Let's get this fix in quick. Didn't catch this.

Comment 98

[Mike Kaply [:mkaply]]

Comment on attachment 137296 [details] [diff] [review]
Trivial URL fix

VERY quick. Technically we are not supposed to be changing translation stuff at
this point in time. please note in your checking comment that this is a change
to an L10N file but doesn't impact actual translation.

Comment 99

[[e-mail]]

Comment on attachment 137296 [details] [diff] [review]
Trivial URL fix

Checked in.

Comment 100

[Frédéric Chateaux]

 Some suggestions for futures releases :

Working on small files is easier.  For example, mail_help is awful to maintain
and to translate, same for using_priv_help and composer_help.

- using_priv_help
    - This file could be split in 2 parts, using_priv_help and forms_help.
    - Informations about password manager could be merge into password_help
(lots of informations are redundant).
    - May be create a cookies_help file.

-composer_help
   - Split in 3 files : composer_help, web_publishing_help and cs_comp_prefs_help

- mail_help
   - Split in 3 or 4 files : mail_help, newsgroup_help, working_offline_help and
cs_mail_prefs_help
   - May be a fifth file : mail_settings_help

-nav_help
   - Split in 2 files

Some important help parts are still missing : specially junk mail control, which
is a very important feature of Mozilla.

Comment 101

[jhp (no longer active)]

The file "mail_help.xhtml" still uses "Mozilla" in the title.  It should either
be changed to "Using &brandShortName; Mail & Newsgroups" or just "Using Mail
& Newsgroups".  I'm more partial to the latter.

Comment 102

[Christian Eyrich]

See Bug 221925 for work on mail_help.xhtml. I'll change the Mozilla in the title.

Comment 103

[Daniel Wang]

> The file "mail_help.xhtml" still uses "Mozilla" in the title. 
actually, this is fixed w/ bug 196236

Comment 104

[:aceman]

Is this still a blocker and target milestone set to 1.6b, when 1.6 final is out?

I (as a help translator) fully support comment #100.

Comment 105

[:aceman]

I have a question about these rules in the css:
ul {
  margin-left: -1em; /* made problems with other browser */
}
ol {
  margin-left: -1em; /* made problems with other browser */
}

What are they for?

In the old files (1.5), these caused movement of the list to the left (and out
of screen) when zooming text.

I don't know whether this is still a problem, though.

Comment 106

[Frédéric Chateaux]

It could be useful for some image, like online.png or offline.png, to use the
theme image.

For example : 
<img src="chrome://messenger/skin/icons/offline.gif">
instead of
<img src="images/offline.gif">

Comment 107

[Frédéric Chateaux]

Attachment: Validation of validation_help.xhtml

HTML1.1 validation of validation_help.xhtml

I also replace unordered lists by definition lists when needed.

Comment 108

[Stefan [:stefanh]]

I'm actually converting the help files to xhtml in bug 236942 (been doing a few
so far). The summary isn't that obvious, since my ambition from the beginning
was just to clean up the code in the html files and use helpFileLayout.css for
the style.

Frédéric, if you plan to do some more files we should get in contact - so we're
not doing the same files :)

Comment 109

[R.J. Keller]

Attachment: Help on Help -> XHTML

Comment 110

[Stefan [:stefanh]]

Attachment: validation_help.html --> validation_help.xhtml

Since my work in bug 236942 actually involves converting the help files to
xhtml I've decided to attach the patches in here instead. This patch involves
some code cleanup and some changes for the consistency as well (like a new
copyright line etc).

Comment 111

[Stefan [:stefanh]]

Comment on attachment 150818 [details] [diff] [review]
validation_help.html --> validation_help.xhtml

Keller, can you take a look at this?

Comment 112

[Stefan [:stefanh]]

Attachment: New version of patch

Just saw some intendation errors, here's a new version.

Comment 113

[R.J. Keller]

Comment on attachment 150884 [details] [diff] [review]
New version of patch

r=[e-mail]. This patch looks good. I didn't check the links but once all
of these XHTML files are done and checked in, I'll run a link checker and run
through the TOC and index entries to make sure all the links work.

Comment 114

[Stefan [:stefanh]]

(In reply to comment #113)
> (From update of attachment 150884 [details] [diff] [review])
> r=[e-mail]. This patch looks good. I didn't check the links but once all
> of these XHTML files are done and checked in, I'll run a link checker and run
> through the TOC and index entries to make sure all the links work.
> 

Thx, can you check it in as well? I'll have some more files on the way tomorrow ;)

Comment 115

[R.J. Keller]

Stefan_h: Can you please post the HTML file of the latest patch? Your patch
won't apply. It could be possible you're using an older version of the file. The
rest of the patch applied, and I can check this in if I have the HTML file.

If you can attach that, I can get this checked in!

Comment 116

[Stefan [:stefanh]]

Attachment: HTML file

Comment 117

[R.J. Keller]

Comment on attachment 150915 [details]
HTML file

Did I say HTML? Sorry, I meant the new XHTML file. Sorry about that!

Comment 118

[Stefan [:stefanh]]

Attachment: XHTML file

:)

Comment 119

[Stefan [:stefanh]]

BTW, Keller: The file is old, but I changed it so the changes made after i
altered it are included.

Comment 120

[Stefan [:stefanh]]

Just thought I give you some info on the current status of the XHTML conversion:

The following files are up next - the only thing that's left is to patch them
(with jar.mn and rdf files updates etc):

customize_help
cs_nav_prefs_advanced
passwords_help

There are two more files patched in this bug, help_help and composer_help
(composer_help would probably need an update), which leaves us to the following
files remaining:

cs_nav_prefs_appearance
cs_nav_prefs_navigator
nav_help
using_priv_help

I'll do these ones as well, if everything works out as I have planned all the
files will be converted pretty soon.

Comment 121

[Stefan [:stefanh]]

Keller, was there any problem with the XHTML file in attachment id=150936?

Comment 122

[Daniel Wang]

Stefan, while you are on it, how about utilizing <span class="ui"></span> ?

Comment 123

[Stefan [:stefanh]]

(In reply to comment #122)
> Stefan, while you are on it, how about utilizing <span class="ui"></span> ?

Hmm. I rather see that filed in a separate bug.

Comment 124

[Stefan [:stefanh]]

Attachment: Patch, 4 more help files to XHTML

This patch converts the following help files to XHTML:

cs_nav_prefs_advanced
cs_nav_prefs_appearance
customize_help
passwords_help


In a few places there where references to "My Sidebar", that is changed to
"Sidebar"

As usual, the new copyright line at the bottom has been added to the converted
files (date line has been removed). 

In passwords_help, one sub-toc has been removed.

Oh, btw: forget one file in comment #120: using_certs_html. Just 4 files left
anyway ;)

Comment 125

[R.J. Keller]

Comment on attachment 151110 [details] [diff] [review]
Patch, 4 more help files to XHTML

Looks good. As I said before, I'm running my link checker through the files and
TOC once all the files are moved to XHTML, so if there is an error I'll catch
it soon and fix it. It'll be much easier doing it then than looking through
this patch for error now.

Comment 126

[[e-mail]]

Attachment: Remove unnecessary chrome://help/locale/ prefixes

While checking in attachment 151110 [details] [diff] [review] I noticed that there were many absolute
links in the indexes so I made them all relative. This saves about 9Kb :-)

Comment 127

[R.J. Keller]

> Index: mozillahelp.rdf
> ===================================================================
> RCS file:
/cvsroot/mozilla/extensions/help/resources/locale/en-US/mozillahelp.rdf,v
> retrieving revision 1.6
> diff -p -u -d -r1.6 mozillahelp.rdf
> --- mozillahelp.rdf	4 Oct 2003 16:44:21 -0000	1.6
> +++ mozillahelp.rdf	24 Jun 2004 23:12:36 -0000
> @@ -5,8 +5,7 @@
>  <!-- MOZILLA MASTER HELP DOCUMENT -->
>    <rdf:Description about="urn:root"
>            nc:title="Mozilla Help"
> -          nc:defaulttopic="welcome"
> -          nc:base="chrome://help/locale/">
> +          nc:defaulttopic="welcome">
>      <nc:panellist>
>        <rdf:Seq>
>          <rdf:li> <rdf:Description nc:panelid="glossary"
nc:datasources="help-glossary.rdf"/> </rdf:li>

Neil, are you sure that this works? If this works, then it's a bug :). nc:base
is supposed to set the base URL where all the content files are located. If it
does not, then it's a bug.

Comment 128

[[e-mail]]

Attachment: Make -chrome chrome://help/content work with previous patch

Help already chooses a reasonable default nc:base URI except in this one case.

Comment 129

[[e-mail]]

Attachment: Correct patch for above :-[

Whoops, somehow some cruft got joined to the end of the patch...

Comment 130

[Giacomo Magnini]

There is a leftover in cs_nav_prefs_advanced.xhtml, line 139:
"1. " should be removed, since it is now a <li>.

Comment 131

[Stefan [:stefanh]]

(In reply to comment #130)
> There is a leftover in cs_nav_prefs_advanced.xhtml, line 139:
> "1. " should be removed, since it is now a <li>.

The next patch (up sometime tomorrow), that covers using_priv_help,
using_certs_help and cs_nav_prefs_navigator will also include some corrections
(like the "1" leftover and some dead links etc). I think I saw some garbage
stuff in the glossary as well.

Comment 132

[Giacomo Magnini]

In cs_nav_prefs_navigator.xhtml, around line 193, missing line:
<h2 id="themes">Appearance Preferences - Themes"</h2>

Comment 133

[Giacomo Magnini]

sorry: cs_nav_prefs_appearance.xhtml !

Comment 134

[Stefan [:stefanh]]

Attachment: 3 more help files converted to xhtml

This patch converts the following help files to xhtml:

cs_nav_prefs_navigator
using_certs_help
using_priv_help

As usual, the code has been cleaned up a bit and the copyright line etc has
been fixed. using_priv_help:s table now uses the default table style.

The two issues reported by Giacomo (a remaining "1." in cs_nav_prefs_advanced
and a missing line in cs_nav_prefs_appearance) is now fixed. I've also fixed
the <em> tags in certs_help.xhtml and glossary.xhtml, previously reported by
Frédéric in bug 236942, comment #47.

Apart from that and the correction of a few minor typos/missing words etc, the
following has been fixed in the files:

using_priv_help:

*fixed the link to foreign cookies to point to "what are third-party cookies"
in  privacy_help

*Changed the heading "Managing Stored Passwords" to "Viewing and Managing
Stored Passwords" so it corresponds with the title in "In this section".

privsec_help:

Changed the link "Forms" in privsec_help to point to "Privacy & Security -
Forms" (these links needs to be looked over, but this is better than linking to
the Form Manager).

certs_prefs_help:

Added the copyright line

Comment 135

[Stefan [:stefanh]]

Comment on attachment 151759 [details] [diff] [review]
3 more help files converted to xhtml

Can you please take a look, R.J?

Comment 136

[R.J. Keller]

Comment on attachment 151759 [details] [diff] [review]
3 more help files converted to xhtml

Wow! these are hard patches to review!

r=[e-mail], I'll checkin in a sec.

Comment 137

[u60234]

Some things to consider for the next patch:

help-index1.rdf:
Line 1328, "shortcuts.html#navigator" -> "shortcuts-navigator.xhtml".
Line 1557, "cs_nav_prefs_appearance.xhtml#preferences:colors" ->
cs_nav_prefs_appearance.xhtml#colors.

help-toc.rdf:
Line 815 is a duplicate of line 814.

Comment 138

[Stefan [:stefanh]]

> help-toc.rdf:
> Line 815 is a duplicate of line 814.

Hmm, odd - the line has been there since bug 188159 was fixed.

Comment 139

[Michael Opitz]

(In reply to comment #138)
> > help-toc.rdf:
> > Line 815 is a duplicate of line 814.
> 
> Hmm, odd - the line has been there since bug 188159 was fixed.

I already have this in my patch for Bug 245035
The current patch there doesn't apply clean but i'm working on a new one.

Comment 140

[Stefan [:stefanh]]

Attachment: Some clean-up

This patch adresses the remaining issues reported in comment #138. Adds a
missing " in a link and removes an "y" in front of one alt text as well.

Comment 141

[Stefan [:stefanh]]

Comment on attachment 152791 [details] [diff] [review]
Some clean-up

Actually, I meant comment #137 ;)

Comment 142

[Stefan [:stefanh]]

R.J.: Can we update the composer_help patch?

Comment 143

[Stefan [:stefanh]]

rlk: can you check in attachment #152791 [details] [diff] [review] to the trunk please?

Comment 144

[Stefan [:stefanh]]

Attachment: nav_help.html --> nav_help.xhtml

This patch converts nav_help.html to xhtml. It also includes the clean-up in
attachment #152791 [details] [diff] [review]. As usual, the copyright line has been altered. Apart from
some very small corrections (like changing one alt text and removing "Return"
from the content in <ul class="noMac">), nothing else have been changed in the
file (although the file really needs to be updated...).

Since I couldn't find the corresponding anchor/content in the xhtml file I
removed the following from help-index1.rdf:


       <rdf:Description ID="web_pages:finding_related"
	 nc:name="finding related web pages"
	 nc:link="nav_help.html#web_pages:finding_relatedIDX"/>
     </rdf:li>

Comment 145

[R.J. Keller]

Comment on attachment 153512 [details] [diff] [review]
nav_help.html --> nav_help.xhtml

lets get this in. This will be checked in in a sec.

Comment 146

[Stefan [:stefanh]]

Attachment: Update of Michael Stadlbauer's patch (attachment #135197)

Here's an updated version of  Michael Stadlbauer's patch (composer_help and
helpFileLayout.css) - credits should go to him. I have just made some small
corrections like a new copyrightline without &brandShortName; "in Mozilla
Foundation", a few changed/removed id:s etc. The heading "Changing the Default
Publishing Site" is now "Choosing the Default Publishing Site".

In helpFileLayout.css I just did another indentation and left out the comment
"Otherwise it's too small".

A patch with changes in help-index1.rdf, help-toc.rdf, jar.mn and the other
help files will be up in a few minutes.

Comment 147

[Stefan [:stefanh]]

Attachment: patch for the links and anchors etc

Includes clean-up of obsolete files in jar.mn. Removed some unnecessary anchors
in the beginning of help-toc.rdf as well.

Comment 148

[Stefan [:stefanh]]

Comment on attachment 154321 [details] [diff] [review]
patch for the links and anchors etc

I guess we could resolve this bug when these last patches are in? The remaining
issues (like applying one of Michaels css-styles in the other files  and taking
care of some <b> tags etc will be fixed in another bug.

Comment 149

[R.J. Keller]

Fix checked in!!!!!!!!!

Wow! I thought this would never get done! Thanks for everyone who made it
possible! I'm going to run a link checker on the XHTML files and check the TOC
and index for dead links to make sure we don't have any regressions from this.

marking FIXED.

Comment 150

[Giacomo Magnini]

Why was this bug closed? buttons.png and print.png (referenced by
help_help.xhtml and welcome_help.xhtml) are nowhere to be found according to LXR.

Comment 151

[Stefan [:stefanh]]

R.J.: You forgot to check in attachment #154329 [details] [diff] [review] - that was the updated 
composer.xhtml patch ;). The patch you checked in was just the toc and link 
updates. And shouldn't Neils patches go in as well ( attachment #151650 [details] [diff] [review] and 
attachment #151674 [details] [diff] [review])?

Comment 152

[Stefan [:stefanh]]

Hmm, looks like the file has been checked in - but the log shows another file.

Comment 153

[R.J. Keller]

(In reply to comment #150)
> Why was this bug closed? buttons.png and print.png (referenced by
> help_help.xhtml and welcome_help.xhtml) are nowhere to be found according to LXR.

That has nothing to do with this bug. This bug is about moving HTML -> XHTML.

(In reply to comment #151)
> R.J.: You forgot to check in attachment #154329 [details] [diff] [review] - that was the updated 
> composer.xhtml patch ;). The patch you checked in was just the toc and link 
> updates. And shouldn't Neils patches go in as well ( attachment #151650 [details] [diff] [review] and 
> attachment #151674 [details] [diff] [review])?

yeah, I got some attachments mixed up. I'll make another landing.

Comment 154

[Giacomo Magnini]

(In reply to comment #153)
>That has nothing to do with this bug. This bug is about moving HTML -> XHTML.

The problem is that your check in converting html to xhtml did replace the old
linked images in the .xhtml files, without replacing them with the new
referenced ones. Probably it was better catching this during review, but
nevermind, I'll open a new bug for this if you think it's better.