258257 - various errors in mail help (mail_help.xhtml)

Status: VERIFIED FIXED

(Documentation Graveyard :: Help Viewer, defect)

Description

[Tsahi Asher]

User-Agent:       Mozilla/5.0 (Windows; U; Windows NT 5.1; he-IL; rv:1.7.2) Gecko/20040803
Build Identifier: Mozilla/5.0 (Windows; U; Windows NT 5.1; he-IL; rv:1.7.2) Gecko/20040803

while translating the mail_help.xhtml file to hebrew, i found numerous errors of
all kinds, wether incorrect documentation or broken links, and others. i
summarized them in the following table:

line|original                    |should be               |
----+----------------------------+------------------------+
158 |You must..server (SMTP) here|[wrong. need rewrite]   |
366 |mail_newmail_alert.png      |task_mail.png           |
366 |colspan="4"                 |colspan="2"             |
498 |<li>Open the View ...Sidebar|[removed]               |
889 |rewrap                      |[belongs to Edit, not   |
    |                            |Options]                |
1355|In the Name tab             |In the Contact tab      |
1598|#deleting_pop_or_imap_mes...|#deleting_messages      |
1631|#deleting_pop_or_imap_mes...|#deleting_messages      |
1865|has four tabs:              |has three tabs:         |
1869|Name                        |Contact                 |
1927|href=""                     |href="#using_address_books"|
1993|Open Window menu            |Open the Window menu    |
2238|<li>Click...dialog box.</li>|[remove section]        |
2886|<li>Use the drop-down list  |<li>Use the list        |
2933|to the Inbox folder         |from the Inbox folder   |
2949|Filters don't apply...      |[incorrect. delete or   |
    |                            |rewrite.]               |
3130|Open the Tools menu         |[remove paragraph]      |          
3183|an mail account             |a mail account/an email |
    |                            |account                 |
3183|<b>Account</b>              |<strong>Account</strong>|
    |                            |[other items too]       |
3248|mail mail                   |mail                    |
3326|<a href="#subscribing_t...  |[remove. link to self]  |
3354|an account                  |an IMAP account         |
4365|<br />                      |[remove]                |
4588|Addressing                  |Composing & Addressing  |
4768|With last two               |With the last two       |
5054|option                      |button                  |
5112|Remember the last...        |[switch with next <li>] |
5129|Play a sound                |[remove item]           |
5180|<li>                        |<li><strong>            |
    |<p><strong>                 |                        |
5189|                            |[toolbar options]       |
5183|or if want to               |or if you want to       |
5264|<li>                        |<li><strong>            |
    |<p><strong>                 |                        |
5528|from incoming, outgoing, or |from outgoing or        |
5531|<p><strong>Note...          |[rewrite. incoming no   |
    |                            |longer supported]       |
5675|list.).</li>                |list.)</li>             |


several places use <li style="list-style: none"> for sub-lists. in
ordered lists, this causes a skip in one number, e.g. from 3 strait
to 5.


Reproducible: Always
Steps to Reproduce:
1.
2.
3.

Comment 1

[Giacomo Magnini]

Attachment: Work in progress...

Ok, this is a first cut at fixing the reported errors.
Moved some stuff around in Preferences, adding class="win" for windows only
options (probably much more is needed), fixed the obviuos errors, and removed
useless stuff.

Comment 2

[Giacomo Magnini]

(In reply to comment #0)
> 366 |mail_newmail_alert.png      |task_mail.png           |

Done.

> 366 |colspan="4"                 |colspan="2"             |

4 is used everywhere else.

> 498 |<li>Open the View ...Sidebar|[removed]               |

Done.

> 1355|In the Name tab             |In the Contact tab      |
> 1598|#deleting_pop_or_imap_mes...|#deleting_messages      |
> 1631|#deleting_pop_or_imap_mes...|#deleting_messages      |
> 1865|has four tabs:              |has three tabs:         |
> 1869|Name                        |Contact                 |

Done.

> 1927|href=""                     |href="#using_address_books"|

Fixed elsewhere.

> 1993|Open Window menu            |Open the Window menu    |
> 2238|<li>Click...dialog box.</li>|[remove section]        |
> 2886|<li>Use the drop-down list  |<li>Use the list        |
> 2933|to the Inbox folder         |from the Inbox folder   |

Done.

> 3130|Open the Tools menu         |[remove paragraph]      |          

No, the menu was wrong. It's in Message, and menu items are a little bit
different. Done.

> 3183|an mail account             |a mail account/an email |
>     |                            |account                 |
> 3183|<b>Account</b>              |<strong>Account</strong>|
>     |                            |[other items too]       |
> 3248|mail mail                   |mail                    |

Done.

> 3326|<a href="#subscribing_t...  |[remove. link to self]  |

This is a little bit hard to fix. 
I've modified the link to point to Adding another News Server (or similar), but
the truth is that the section regarding setting up an account should be modified
to handle also Newsgroup accounts... As it is now, it explains only pop and imap
ones. 

> 3354|an account                  |an IMAP account         |
> 4365|<br />                      |[remove]                |

Done. Useless <br /> removed everywhere, just like <li><p>, and all <b>
converted to <strong>.

> 4588|Addressing                  |Composing & Addressing  |
> 4768|With last two               |With the last two       |
> 5054|option                      |button                  |

Done.

> 5112|Remember the last...        |[switch with next <li>] |
> 5129|Play a sound                |[remove item]           |

Moved stuff around and added class="win" for platform specific details.

> 5183|or if want to               |or if you want to       |

Oops! Missed in the supplied patch, fixed locally.

> 5528|from incoming, outgoing, or |from outgoing or        |

Done.

> 5675|list.).</li>                |list.)</li>             |

Done.

> several places use <li style="list-style: none"> for sub-lists. in
> ordered lists, this causes a skip in one number, e.g. from 3 strait
> to 5.

Will have a go at this next.
All not listed above is still pending: rewriting sections is not really possible
for me, since english is not my own language. Some help will be needed here.
Adding people in-the-know for this.

Comment 3

[Giacomo Magnini]

Attachment: WIP nr. 2

Removed all useless <li style> and added forgotten fix.

Comment 4

[Tsahi Asher]

(In reply to comment #2)
> (In reply to comment #0)
> 
> > 366 |colspan="4"                 |colspan="2"             |
> 
> 4 is used everywhere else.
> 

and all places got it wrong. there are only two columns in these image tables.

Comment 5

[Giacomo Magnini]

Fixed locally. Will provide a new patch and ask for review: I think it's better
to finish off this bug starting from a better position, so that the patch
doesn't get too big even for review. And if someone else steps up to rewrite
parts of the docs, he/she will find the file in a better shape. I've got a few
ideas also for splitting up this enormous file into some more managagle bits...

Comment 6

[Giacomo Magnini]

Attachment: Ok, here we go: first cleanup

Ok, this is the first part of the clean up:
- all previuos fixes included
- colspans fixed
- &nspb; cruft removed
- removed ugly formatting from Using Message Views (I guess class="ui" can be
removed from some .css file, but I can't find it).
Should be applied after the third patch in bug 257507 (just to be sure).
Please leave bug open for rewriting of a few paragraphs.

Comment 7

[Giacomo Magnini]

Ok, I've found the class definition inside helpFileLayout.css for ui:
since mail_help.xhtml is/was the only user, can we remove it from the css file?
It will save a few bytes! :)

Comment 8

[Tsahi Asher]

(In reply to comment #5)
> I've got a few
> ideas also for splitting up this enormous file into some more managagle bits...

please see bug 246405 about this.

Comment 9

[Giacomo Magnini]

Attachment: More cruft removal and caption added to search bar image

Better patch. More cruft removed and added image title to search bar (it was
the only image missing one).
Comments for previuos obsoleted patch still apply.

Comment 10

[Stefan [:stefanh]]

Oops, wrong bug... --> Giacomo.

Comment 11

[Giacomo Magnini]

Attachment: Updated patch

Ouch! Unbitrotted patch, taking care of the removal of .ui from
helpFileLayout.css, which was used only in mail_help.xhtml for a single
paragraph.

Comment 12

[Giacomo Magnini]

Attachment: Newer patch, un bitrotted again, with more fixes.

Comment 13

[[e-mail]]

I think it would be neat to use <dl><dt><img/></dt><dd>Thread Button</dd></dl>
for those captions - with some appropriate CSS styles of course.

Comment 14

[Giacomo Magnini]

dl
{
text-align: center;
padding: 0;
float: left;
margin-right: 1em;
}

dl dd
{
margin: 0;
padding: 0;
font-weight: bold;
}

Something like this? If anybody has a better suggestion, feel free! :)

Comment 15

[Tsahi Asher]

please replace

margin-right: 1em;

with

-moz-margin-start: 1em;

for better compatibility with RTL documents.

the float: left is also a problem. maybe something like this will work better:

dl[dir="ltr"] {
  float: left;
}

dl[dir="rtl"] {
  float: right;
}

it is also worth checking if -moz-margin-start isn't in CSS3 support, as simply
margin-start.

Comment 16

[Tsahi Asher]

i made an error. use -moz-margin-end instead of margin-right.

Comment 17

[Stefan [:stefanh]]

Note that the glossary file uses styled dl:s. You might want to use a class for
your caption styles so you dont break the styles in glossary.xhtml.

Comment 18

[Giacomo Magnini]

Don't you all think that the styling of images should be spin off in a new bug?
Let's concentrate on mail_help here, other changes (impacting many files) should
be done elsewhere... Who's going to open a new bug? :)

Comment 19

[[e-mail]]

Comment on attachment 161145 [details] [diff] [review]
Newer patch, un bitrotted again, with more fixes.

Mostly good, just a few nits:

Your thread button table is unbalanced, the second row only has one column.

The screen name relates to AOL; clicking on the IM button attempts to load AIM
to chat to the specified screen name.

Where's your search bar image? I think the width of 180 on the search bar
caption is a bit enthusiastic. Hmm... Can we (later) use table captions for
these?

While you're at it, I'd prefer to "Choose a mail account", not "an". I wonder
if "Junk Mail Controls" are singular or plural...

"Click on Preview button" is missing a "the".

Comment 20

[Giacomo Magnini]

(In reply to comment #19)
> Your thread button table is unbalanced, the second row only has one column.
Fixed. (added empty td width 20)

> The screen name relates to AOL; clicking on the IM button attempts to load AIM
> to chat to the specified screen name.
Fixed. (Screen name - the AIM contact name)

> Where's your search bar image? I think the width of 180 on the search bar
> caption is a bit enthusiastic. Hmm... Can we (later) use table captions for
> these?
Changed caption to "Quick mail search bar", used 80 for width (as for
addressbook icon). This will be definetely put to rest if/when images will get
styled.

> While you're at it, I'd prefer to "Choose a mail account", not "an". I wonder
> if "Junk Mail Controls" are singular or plural...
Fixed "an" -> "a", made jmc plural where needed... ;)

> "Click on Preview button" is missing a "the".
Fixed.

Added to the pack &apos; and <q> changes (I had already moved onto this stuff
since submitting the last patch), sorry for that. The only thing needing some
more attention is the plural form for jmc.
BTW, found another typo (critaria->criteria).

Comment 21

[Giacomo Magnini]

Attachment: Nits addressed, squashed another typo, changed ' to &apos; and " to <q></q> form.

Comment 22

[[e-mail]]

Comment on attachment 162456 [details] [diff] [review]
Nits addressed, squashed another typo, changed ' to &apos; and " to <q></q> form.

I think this is okay now.

Comment 23

[Giacomo Magnini]

Stefan - list of paragraphs to rewrite/correct:
1) the <p></p> at lines 156-159 (probably it's not really needed)
2) the <p></p> at lines 2888-2891 (filters *do* apply to existing messages)
3) the <p></p> at lines 5383-5391 (incoming no more supported)

Comment 24

[Stefan [:stefanh]]

(In reply to comment #23)
> Stefan - list of paragraphs to rewrite/correct:
> 1) the <p></p> at lines 156-159 (probably it's not really needed)
> 2) the <p></p> at lines 2888-2891 (filters *do* apply to existing messages)
> 3) the <p></p> at lines 5383-5391 (incoming no more supported)
> 


Fixed by the check-in of attachment #164296 [details] [diff] [review] in bug 111484. If anyone finds
more/other errors -- please open a new bug.

Comment 25

[Gérard Talbot]

There is no Importing Address Books section in the left pane.

Using Mail/Using Address Books/
and then Importing Address Books should be located between Searching Address
Books and Exporting Address Books.

Also the text should be updated:
"You can import address books from Communicator, Netscape 6, Eudora, Outlook,
Outlook Express, or text files (LDIF, tab-delimited (.tab), comma-separated
(.csv), or text (.txt) formats)."
is not entirely true because of bug 35509. At least, the text should read:
"You can import address books from Netscape 6, Netscape 7, Eudora, Outlook,
Outlook Express, or text files (LDIF, tab-delimited (.tab), comma-separated
(.csv), or text (.txt) formats)."

Both Mozilla 1.7.3 release notes and Mozilla 1.8a4 releases notes indicate that
"Mozilla does not import Communicator 4.x addressbooks. (Bug 35509)"
http://www.mozilla.org/releases/mozilla1.7/known-issues.html#mail
http://www.mozilla.org/releases/mozilla1.8a4/known-issues.html#mail

Comment 26

[Gérard Talbot]

This text 
 "You can import address books from Communicator, Netscape 6, Eudora, Outlook,
 Outlook Express, or text files (LDIF, tab-delimited (.tab), comma-separated
 (.csv), or text (.txt) formats)."

should be updated to:

 "You can import address books from Eudora, Outlook,
 Outlook Express, or text files (LDIF, tab-delimited (.tab), comma-separated
 (.csv), or text (.txt) formats)."

Also,

"If you have a Mozilla address book from another user profile or computer, or if
you have an address book from a previous version of Netscape Communicator or
another mail program, you can import its entries into the Address Book window as
a new address book."

should be rewritten to

"If you have a Mozilla address book from another user profile or computer, or if
you have an address book from another mail program, you can import its entries
into the Address Book window as a new address book."

And specific steps to import address books from NS 6.x or NS 7.x should be
given. The current design expects the user to figure out on his own that he can
not import a NS 6.x or NS 7.x address book into Mozilla. The current design
expects the user to figure out on his own that he must first convert the .mab
address book file in his NS 6.x or NS 7.x profile into a text file by using the
export command and then to import it into Mozilla. None of this is currently
explained to NS 6.x/NS 7.x users migrating to Mozilla.
"having to export all addresses as text then re-import is silly."
https://bugzilla.mozilla.org/show_bug.cgi?id=121725#c9

Unless the user uses NS 6.x/NS 7.x profile, he won't be able to import a
targeted address book in 1 step. The process is not well designed nor explained. 

Comment 27

[Giacomo Magnini]

Attachment: Add missing entry to help-toc.rdf

Simple fix for missing toc entry.
I don't think that we should alter the help files for importing NS 4.x address
books, since there is a bug open about this and it has shown some progress
lately. Plus, release notes report already the missing functionality, which
should/will be there someday...

Comment 28

[Giacomo Magnini]

Attachment: Rewrote paragraph as suggested (Checked in)

As I said, I didn't touch the part involving NS ab import, but the paragraph
suggested is clearer anyway.

Comment 29

[Ian Neal]

Comment on attachment 172880 [details] [diff] [review]
Rewrote paragraph as suggested (Checked in)

Checking in mail_help.xhtml;
/cvsroot/mozilla/extensions/help/resources/locale/en-US/mail_help.xhtml,v  <-- 
mail_help.xhtml
new revision: 1.50; previous revision: 1.49
done

Comment 30

[Giacomo Magnini]

Closing the bug as explained before. Moving to other bugs.

Comment 31

[Stefan [:stefanh]]

v