246405 - mail_help.xhtml should be split to several files

Status: RESOLVED FIXED

(SeaMonkey :: Help Documentation, enhancement)

Description

[Tsahi Asher]

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

currently, the help file for the mail-news, mail_help.xhtml, is the largest file
in the help system, totaling at 203,000 lines and 182kB. for comparison, the
second largest file, composer_help.html, is just over half of that.

most localizers of mozilla agree, i believe, that the size of this file poses a
problem:
1. any change in the file renders the entire file as invalid for inclusion in
the next language pack, until the changes are updated in the translation,
leaving it with no translated help at all for mail. because of the large amounts
of text in the help system, many language packs don't include a complete
translation of the help. if this file was split in 3-4 parts, at least some of
them could be entered to the pack, if the localizer didn't make it to update the
change in time for the release, or didn't translate the whole file for some
other reason.
2. load time: on my AMD 600MHz, WinXP, with 256MB 100MHz SDRAM, it takes this
file 2-3 seconds to load. i think this is unacceptable for a local file.

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




i hope i'm posting to the right component here. sorry if i'm wrong.

Comment 1

[Frédéric Chateaux]

http://bugzilla.mozilla.org/show_bug.cgi?id=95770#c100

mail_help.xhtml could be split in:
- mail_help
- addressbook_help
- cs_mail_prefs_help
- mail_settings_help
- working_offline_help
- newsgroup_help
- junk_mail_help

Comment 2

[Tsahi Asher]

where will "organizing your messages" come?

i understand that everything up to "using addressbooks" will be in mail_help, right?

Comment 3

[R.J. Keller]

> - mail_help
> - addressbook_help
> - cs_mail_prefs_help
> - mail_settings_help
> - working_offline_help
> - newsgroup_help
> - junk_mail_help

I was thinking just doing mail_help, news_help, and addressbook_help. We don't
want to split it into too many. junk_mail_help and others are basically the same
as mail_help. 

Comment 4

[Frédéric Chateaux]

(In reply to comment #3)
> 
> I was thinking just doing mail_help, news_help, and addressbook_help. We don't
> want to split it into too many. junk_mail_help and others are basically the same
> as mail_help. 

It's not just a question of logical splitting. If we split the single
mail_help.xhtml only in 3, we'll still end up with mail_help file bigger than
the other ones. These big file is not pleasant at all to work with. It'd be
easier for the translators to work with smaller files, around 30-40 ko max.

Mail_help should contain only general ToC of mail help and the "getting started"
section". All other sections, should be in separates files.

For example, the french mail_help file make 283ko. It take an entirely week to
be checked correctly (links, UI term, etc.). It is a very hard job.

Comment 5

[Daniel Wang]

preference and security docs should always in separate files. So I'd say:
- mail_help (include topics on address books)
- cs_mail_prefs_help
- mail_settings_help
- newsgroup_help

Addressbook and mail are inter-related. For example, when you talk about junk
mail control or organizing mail, you need to talk about managing multiple
addressbooks (person + collected).

Managing Mail is close to a "tips on using mail" type document. I prefer we only
skim through topics on managing mail and junk control, and split the tip part
into separate files under mozilla.org/docs/end-user/guide/

Comment 6

[Tsahi Asher]

only that mozilla.org/docs/end-user/guide/ is not linked from, say,
welcome_help. not everyone will wander through the documentation on mozilla.org
unless they really have a problem.

Comment 7

[R.J. Keller]

I made a proposal of splitting most of Mozilla's help files in a blog entry I
made (http://rjkeller.blogspot.com/2004/06/seamonkey-help-file-splitup.html).
Maybe this would be an appropriate solution?

Comment 8

[R.J. Keller]

eh, I don't think I copy and pasted the code right in that blog entry :). I'll
update it once I find the right code (can't remember where I saved it!!!).

Comment 9

[Frédéric Chateaux]

This won't facilitate our work. The files mail_help and composer_help are still
too huge :(

Comment 10

[Benoit]

I just wanted to show some support on Frédéric's points. The fact is we (the
French translation team) are probably one of the largest localization teams,
with many people ready to help. 

But still, with files as large as 280KB (the french language is somewhat more
verbose than english), we just can't split up the work between several
contributors although we do have them available. Frédéric is really doing this
*alone*.

As an user, I must also add that pages that takes more than 3 or 4 screens
aren't appealing to read. This one takes 89 screens on a 1024x768 monitor, that
should be dramatically reduced. One could also argue about the paper wasted when
someone wants to print some part of the manual, in our case that's 76 pages for
Mozilla 1.6.

Comment 11

[R.J. Keller]

After looking at mail_help.xhtml again, maybe it would be best to split each
individual mail topic into a separate file and have them be stored in the mail
folder to help with organization.

What do you think of that? To view all the files being split, just view all the
topics listed for Mail & Newsgroups Help on the TOC.

Comment 12

[Tsahi Asher]

i didn't get the new folders thing. you seem to want to put the help files with
their relevant dtd/properties files, right? if so, this will complicate our
lives, because we might miss a file somewhere in the directory sturcture. the
help files are translated seperately from the rest of the UI.

in case you want to just add folders under the help folder, i can't see how this
helps us either, unless you expect a naming problem with the files.

Comment 13

[R.J. Keller]

(In reply to comment #12)
> i didn't get the new folders thing. you seem to want to put the help files with
> their relevant dtd/properties files, right? if so, this will complicate our
> lives, because we might miss a file somewhere in the directory sturcture. the
> help files are translated seperately from the rest of the UI.

Complicate? I'm not sure who you talked to, but most localizers would prefer
having mail_help moved into about 6+ different files which would be added to a
mail directory.


> in case you want to just add folders under the help folder, i can't see how this
> helps us either, unless you expect a naming problem with the files.

It helps with organization. It isn't a major help, but it does make it easier
when we might want to not build mail-news documentation when mail-news is not
built. The advantages aren't as much to the localizer as the general structure.

Comment 14

[Tsahi Asher]

(In reply to comment #13)
> (In reply to comment #12)
> > i didn't get the new folders thing. you seem to want to put the help files with
> > their relevant dtd/properties files, right? if so, this will complicate our
> > lives, because we might miss a file somewhere in the directory sturcture. the
> > help files are translated seperately from the rest of the UI.
> 
> Complicate? I'm not sure who you talked to, but most localizers would prefer
> having mail_help moved into about 6+ different files which would be added to a
> mail directory.
> 

indeed, most localizers want to split the file, but do most localizers (or at
least, those CC'ed here) want to split the help to folders, or even worse,
distributing the help files between the components folders?

i'd like to have a better explanation about what exactly are you planning here,
so we can have a reasonable discussion.

Comment 15

[R.J. Keller]

(In reply to comment #14)
> indeed, most localizers want to split the file, but do most localizers (or at
> least, those CC'ed here) want to split the help to folders, or even worse,
> distributing the help files between the components folders?
> 
> i'd like to have a better explanation about what exactly are you planning here,
> so we can have a reasonable discussion.

No, but most of the programmers/developers would prefer that. There are actually
many advantages to doing that. We don't necessarily have to build the files into
the JAR file with the folders (we can put them all into one directory like we do
now), but the source tree would have this.

If I recall correctly, I don't think the localizers work off of the source tree,
just the JAR so there shouldn't be an issue. It'd still be the same way as it is
now.

What I am planning (which may not happen due to other issues) is not build
MailNews help when MailNews is not built. With the folder system, this makes it
easier.

I don't see your point on how this complicates things. It increases organization
significantly. If you have 6+ files for mail_help that are mixed up with all the
other help docs, it would make it easier to have them in a folder so you know
that the content you are translating is mail_help. You could prioritize certain
components that might be more vital. I know that there aren't a whole lot of
advantages, but I don't see any disadvantages.

Comment 16

[Tsahi Asher]

(In reply to comment #15)
> (In reply to comment #14)
> > indeed, most localizers want to split the file, but do most localizers (or at
> > least, those CC'ed here) want to split the help to folders, or even worse,
> > distributing the help files between the components folders?
> > 
> > i'd like to have a better explanation about what exactly are you planning here,
> > so we can have a reasonable discussion.
> 
> No, but most of the programmers/developers would prefer that. There are actually
> many advantages to doing that. We don't necessarily have to build the files into
> the JAR file with the folders (we can put them all into one directory like we do
> now), but the source tree would have this.
> 

in that case, it's fine with me. i thought you were talking about the directory
structure in the JAR file.

> 
> What I am planning (which may not happen due to other issues) is not build
> MailNews help when MailNews is not built. With the folder system, this makes it
> easier.
> 
> I don't see your point on how this complicates things. It increases organization
> significantly. If you have 6+ files for mail_help that are mixed up with all the
> other help docs, it would make it easier to have them in a folder so you know
> that the content you are translating is mail_help. You could prioritize certain
> components that might be more vital. I know that there aren't a whole lot of
> advantages, but I don't see any disadvantages.

the important thing is to have all the files under chrome://help/locale/... if
you add any sub-folders under that, it's fine. 

Comment 17

[R.J. Keller]

> the important thing is to have all the files under chrome://help/locale/... if
> you add any sub-folders under that, it's fine. 

Yes, that is what I meant! Sorry if you misunderstood me.

Comment 18

[R.J. Keller]

Accepting bug. I already got some work done and will hopefully have a patch soon.

Comment 19

[Stefan [:stefanh]]

(In reply to comment #18)
> Accepting bug. I already got some work done and will hopefully have a patch soon.

Just a thought: could the filenames be fixed at the same time (bug 226191)?

Comment 20

[R.J. Keller]

(In reply to comment #19)
> (In reply to comment #18)
> > Accepting bug. I already got some work done and will hopefully have a patch
soon.
> 
> Just a thought: could the filenames be fixed at the same time (bug 226191)?

ahh! good point! grrrr, now I gotta fix all the links again :p.

Comment 21

[R.J. Keller]

Moving to new Help component owner.

Comment 22

[Giacomo Magnini]

(In reply to comment #1)
> mail_help.xhtml could be split in:
> - mail_help
> - addressbook_help
> - cs_mail_prefs_help
> - mail_settings_help
> - working_offline_help
> - newsgroup_help
> - junk_mail_help

I'm experimenting a bit on the split, and here are my .02 Euro:
23400 Sep 14 10:18 addressbook-help.xhtml
22913 Sep 14 10:06 cs-mail-prefs-help.xhtml
38650 Sep 14 10:25 mail-account-settings-help.xhtml
89826 Sep 15 09:35 mail-help.xhtml
7138 Sep 14 10:14 news-help.xhtml
21232 Sep 15 09:36 working-offline-help.xhtml
Now, junk mail control doesn't seem to worth a new file, and please keep in mind
that the news-help would need a new section describing how to set up a news
account (which is currently missing, since the starting paragraph in mail_help
describes only POP and IMAP accounts).
Any thoughts on other things that could be taken out of mail_help.xhtml?
Note: All files are valid XHTML files (complete with headers and such), but all
the links must still be fixed...

Comment 23

[Stefan [:stefanh]]

One problem with the help files is that in some files you can scroll the whole
document and in some files you'll have to use the left pane to navigate through
a subject (section).

If we're about to split mail_help I vote for Frédérics proposal: split the file
in one sub-section == one file, and then have a separate introduction file with
a master "In this section" (could probably be renamed to "Table of contents" if
split in this way). This is just my 2 SEK, but following the sub-sections when
splitting the file seems logical.

The rest of the files could be split in the same way. Having one file split and
keeping the others might cause some confusion when you're about to navigate
through the docs.


If someone feels to discuss this we could open a bug "Split the help files" (or
something like that) and continue the discussion in there. This bug could then
be made a blocker of the new "meta" bug.

Comment 24

[Giacomo Magnini]

Attachment: First cut, open to discussion

Here is the resulting split I was talking about, with fixed inline references.
Obviously I didn't fix any reference in the other help files, this is just a
test/base for discussion. Feel free to comment on.

Comment 25

[Stefan [:stefanh]]

Looks good to me, but I still think it's an issue to have it like this:

-One file---------------------------------------------
Using Mozilla Mail & Newsgroups
  Getting Started with Mozilla Mail & Newsgroups
  Reading Messages
  Sending Messages
  Creating HTML Mail Messages
  Using Attachments
  Deleting Messages
  Organizing Your Messages
  Controlling Junk Mail
  Importing Mail from Other Programs

-Other files------------------------------------------
Working Offline
Using Address Books
Mail & Newsgroups Account Settings
Getting Started With Newsgroups
Mail & Newsgroup Preferences

-"In this section" in mail-help.xhtml-----------------

    *  Getting Started with Mozilla Mail & Newsgroups
    * Reading Messages
    * Sending Messages
    * Creating HTML Mail Messages
    * Using Attachments
    * Deleting Messages
    * Using Address Books
    * Organizing Your Messages
    * Controlling Junk Mail
    * Importing Mail from Other Programs
    * Getting Started with Newsgroups
    * Working Offline
    * Signing & Encrypting Messages
    * Mail & Newsgroups Account Settings
    * Mail & Newsgroups Preferences




From the "In this section" you get the impression that all the entries can be
found in the file (One reason is that it says "In this section") if you scroll
down the document. Now, some of the entries are in the file - but some are in
separate files. I would (IMHO) prefer if all of them (entries) are in the file
or just one or that the user somehow understands that he wont be able to find
some entries by scrolling (which doesn't seem to be consistent).

Or, maybe this can be solved if the "In this section" were reorganized/renamed?

Comment 26

[Tsahi Asher]

your mail-help is still too big. it needs to be split to 3 IMO. i really don't
care what will each part contain, but i think any file shouldn't be longer than
~10 browser screens (in 1024X768 resolution).

i don't see any problem with having some links in the main content table linked
to other places. it exists in other files too, and even in the existing
mail-help. people shouldn't be scrolling to sections anyway, they should click
the links.

finaly, usually there is a horizonal row (<hr> tag) above the copyright notice
at the botton.

Comment 27

[Frédéric Chateaux]

You'll find here
http://perso.wanadoo.fr/fred.chat/frenchmozilla/help_reorganization.html , the
splitting plan for help files I sent to RJ some time ago and what I am doing for
frenchmozilla.

The root files (mail_help, nav_help, etc.) only contained links to other files,
with short description of the content of each section.

Grey files should be introduce in the help, especially for charzilla, since
those tools are ship with Mozilla (Chatzilla team may help to redact them).

Comment 28

[Tsahi Asher]

do you have an estimate on the size of the files you are proposing? anyway, too
small won't hurt IMO.

Comment 29

[Tsahi Asher]

on the other hand, i fear such a big revision in the help files structure is too
big to be done, unless you submit the patch yourself. maybe we have a better
chance in doing the mail help first, and then continue to other files.

Comment 30

[Robert Kaiser]

MASS-CHANGE:
This bug report is registered in the SeaMonkey product, but has been without a comment since the inception of the SeaMonkey project. This means that it was logged against the old Mozilla suite and we cannot determine that it's still valid for the current SeaMonkey suite. Because of this, we are setting it to an UNCONFIRMED state.

If you can confirm that this report still applies to current SeaMonkey 2.x nightly builds, please set it back to the NEW state along with a comment on how you reproduced it on what Build ID, or if it's an enhancement request, why it's still worth implementing and in what way.
If you can confirm that the report doesn't apply to current SeaMonkey 2.x nightly builds, please set it to the appropriate RESOLVED state (WORKSFORME, INVALID, WONTFIX, or similar).
If no action happens within the next few months, we move this bug report to an EXPIRED state.

Query tag for this change: mass-UNCONFIRM-20090614

Comment 31

[RickieES aka Ricardo Palomares]

Marking as NEW and changing importance to Enhancement.

en-US mail_help.xhtml size is currently 246209 bytes, while other localizations may be even bigger (es-ES, for instance, is 248648 bytes), so splitting it to several files would be nice.

However, I consider that this should be done only after SeaMonkey 2.0 is released. The workload this change will put, specially for localizers, suggests that it will be better to postpone and, even if I may say it, to isolate the work on it from any other change in the whole help contents (and to do this, the best moment is surely just after SM 2.0 release).

Comment 32

[Ian Neal]

Resetting to defaults and adding helpwanted keyword.

Comment 33

[RickieES aka Ricardo Palomares]

I've been reviewing all the comments in the bug. Unfortunately, most of the external references to suggestions about how to deal with this splitting don't work anymore. Besides, the discussion had place back in 2004, and a lot has changed since that. Some complaints about missing content have been addressed (mostly about newsgroup uses) and new content has been added (news & blogs, for instance).

Splitting the file is not just a matter of which points choose to slice the file, however. Every slice involves reviewing a lot of links in mail_help.xhtml and other files that will need to be changed. So I propose to fix this bug in several isolated phases (children bugs?), each one with these tasks:

- Set the "slice point".
- For the new slice (ie., new file, named "mail_<new_file_suffix>.xhtml"), build a list of id tags contained in it.
- Look up for "#<id>" tags in mail_help.xhtml and replace them with "mail_<new_file_suffix>.xhtml#<id>".
- Look up for "mail_help.xhtml#<id>" tags in the rest of help files (including RDF files) and replace them with "mail_<new_file_suffix>.xhtml#<id>".
- Build a ToC at start of the new slice, if needed.

This won't solve some of the complaints above in this bug (the mail_help.xhtml ToC pointing to separate files), but maybe that could be subject of a different bug.

Regarding how to split, the current ToC at the top of mail_help.xhtml is this (notes added to give an overview of the size of each section):

0079<li><a href="#getting_started_with_mozilla_mail_and_newsgroups">Getting
      Started with &brandShortName; Mail &amp; Newsgroups</a></li> (243 lines)
0322<li><a href="#reading_messages">Reading Messages</a></li> (287 lines)
0609<li><a href="#sending_messages">Sending Messages</a></li> (488 lines)
1097<li><a href="#creating_html_mail_messages">Creating HTML Mail
      Messages</a></li> (185 lines)
1282<li><a href="#using_attachments">Using Attachments</a></li> (113 lines)
1395<li><a href="#deleting_messages">Deleting Messages</a></li> (80 lines)
1475<li><a href="#using_address_books">Using Address Books</a></li> (549 lines)
2024<li><a href="#organizing_your_messages">Organizing Your Messages</a></li> (674 lines)
2698<li><a href="#controlling_junk_mail">Controlling Junk Mail</a></li> (142 lines)
2840<li><a href="#importing_mail_from_other_programs">Importing Mail from Other
      Programs</a></li> (46 lines)
2886<li><a href="#getting_started_with_newsgroups">Getting Started with
      Newsgroups</a></li> (182 lines)
3068<li><a href="#getting_started_with_blogs_and_news_feeds">Getting Started
      with Blogs &amp; News Feeds</a></li> (367 lines)
3435<li><a href="#working_offline">Working Offline</a></li>  (472 lines)
    <li><a href="mail_sec_help.xhtml">Signing &amp; Encrypting
      Messages</a></li>
3907<li><a href="#mail_and_newsgroups_account_settings">Mail &amp; Newsgroups
      Account Settings</a></li> (1072 lines)
4979<li><a href="#mail_and_newsgroup_preferences">Mail &amp; Newsgroups
      Preferences</a></li> (624 lines)

Everything but Signing and Encrypting Messages is inside mail_help.xhtml. As a rough reference, the Preferences section in Spanish takes about 8 screens in a 1280x800 screen running on Linux/Gnome.

In my vision, I would start from bottom to top, to make life easier to localizers (I'm one of them). ;-) I doubt between putting Account Settings and Preferences in one file or give each section its own one. Actually, it largely depends on the overall preference about splitting mostly based on file sizes or mostly based on topics, with exceptions in both cases (for instance, giving Importing/Exporting a separate file sounds somewhat exaggerated, since is is just about 50 lines).

Well, this comment is long enough to stop here. :-)

Comment 34

[Ian Neal]

There are some easy split points to decide on, so, yes I would have Account Settings and Preferences as two separate files.
The rest gets more difficult, perhaps:
One file for "Getting Started with Mail & Newsgroups"
One file for "Reading Messages", "Sending Messages", "Creating HTML Mail       Messages", "Using Attachments" and "Deleting Messages"
One file for "Using Address Books"
One file for "Organizing Your Messages"
One file for "Controlling Junk Mail" and "Importing Mail from Other Programs"
One file for "Getting Started with Newsgroups"
One file for "Getting Started with Blogs & News Feeds" - I think this one needs some restructuring
One file for "Working Offline"

I've noticed in the main ToC that it is called "Using Mail" rather than "Using Mail & Newsgroups"

What do you think? Jens?

Comment 35

[Jens Hatlak (:InvisibleSmiley)]

I agree that we should first identify the split points, then decide upon file names, then split. And only then do the necessary link changes. In any case, let's not do anything beyond that in this bug or else we'll get lost.

I think we should even separate that patch-wise once the split points and file names have been sorted out. Something like using "hg copy" to create duplicates and removing what needs to be removed from each copy, then the link/ID changes in a second, followup-up patch on top of that, both to be checked in at the same time. That way history is kept intact and localizers can easily see what has been done.

Regarding "Using Mail" in the ToC (easy things first!): Let's just change that. I see no reason why we should keep saying "Mail" here, and if at some point in time "Mail & Newsgroups" is renamed to "Messenger" or something (bug 513527), that'll be another bug. BTW: "Getting Started with Mail" is another candidate. And I don't care that the title will get longer.

As for the split points: I agree that we should split at section boundaries but not necessarily with only one section per file (AFAIU we're on the same track here). The first section should be in the main file (scrolling to it is a lot more likely than for the other sections), but we should probably rename the file from help_mail to help_mailnews while we're at it. BTW I'm not really concerned about links from the first "In this section" box going to different files (mostly because we already have that in other help files as well), but we might want to file a bug about renaming the box title for top-level boxes to discriminate them from ones for subsections.

I'm mostly in line with the suggestions Ian made in comment 34, but I wouldn't put Junk and Importing into the same file, irrespective of their small sizes, just because those two topics have nothing in common. Alternatively, we might be able to relocate one of the two. E.g. Importing could be moved after the "Getting Started with Mail & Newsgroups" section (first one) and made part of the same file during the split process. Similarly Junk could stay where it is but be put into the same split file as Organizing (which contains subsections for Tagging, Marking and Flagging, all of which are quite related to Junk controls).

Proposed setup:
1. MailNews + Importing
2. Reading + Sending + Creating HTML + Attachments + Deleting
3. AB
4. Organizing + Junk
5. News
6. Blogs/Feeds
7. Offline

Phew! I'll go to bed now...

Comment 36

[RickieES aka Ricardo Palomares]

(In reply to comment #35)
> I agree that we should first identify the split points, then decide upon file
> names, then split. And only then do the necessary link changes. In any case,
> let's not do anything beyond that in this bug or else we'll get lost.
> 
> I think we should even separate that patch-wise once the split points and file
> names have been sorted out. Something like using "hg copy" to create duplicates
> and removing what needs to be removed from each copy, then the link/ID changes
> in a second, followup-up patch on top of that, both to be checked in at the
> same time. That way history is kept intact and localizers can easily see what
> has been done.


As a localizer, I tend to be happier if the patch is small and the overall philosophy of the change can be deducted in a quick overview. That's why I proposed doing this in parts (one per slice), thus multiple patches. I'm not sure if this aligns with Ian's ideas or yours.


> Proposed setup:
> 1. MailNews + Importing
> 2. Reading + Sending + Creating HTML + Attachments + Deleting
> 3. AB
> 4. Organizing + Junk
> 5. News
> 6. Blogs/Feeds
> 7. Offline

I like this, although I think there are two more left: :-)

8. Mail & Newsgroups Account Settings
9. Mail & Newsgroups Preferences

To summarize, these are related topics that have come up in previous comments:

- suite-toc.rdf has "Using Mail" instead of "Using Mail & Newsgroups"
- Getting started with News & Blog Feeds needs restructuring
- Box title for top level boxes should be marked/titled somewhat differently than rest of "In this section:" boxes

Comment 37

[Ian Neal]

In terms of reviewing, the easiest way would be to work from the bottom to the top (as you say), so generate a patch for "Mail & Newsgroups Preferences" with the rest of mail_help.xhtml (with Mail & Newsgroups Preferences removed) left alone apart from the changes needed to link to the new mail_preferences.xhtml file (or whatever it is called). Once that patch is reviewed and committed then look at the next one (this where mercurial queues come in hand).
Suggestions for top level boxes - "Topics Covered:" or "In this chapter:"

Comment 38

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #36)
> - Getting started with News & Blog Feeds needs restructuring

Ian, can you expand a bit on this? Do you think it should be part of this bug? Or a new one be filed?

(In reply to comment #37)
> In terms of reviewing, the easiest way would be to work from the bottom to the
> top (as you say)

OK, why not.

> Suggestions for top level boxes - "Topics Covered:" or "In this chapter:"

I like the latter as it relates to the difference between chapter and section.

BTW: I think "mailnews" would be a better file name prefix than just "mail".

Comment 39

[Ian Neal]

(In reply to comment #38)
> (In reply to comment #36)
> > - Getting started with News & Blog Feeds needs restructuring
> 
> Ian, can you expand a bit on this? Do you think it should be part of this bug?
> Or a new one be filed?
It is probably best as a new bug to try and keep things simple.

Comment 40

[RickieES aka Ricardo Palomares]

(In reply to comment #37)
> In terms of reviewing, the easiest way would be to work from the bottom to the
> top (as you say), so generate a patch for "Mail & Newsgroups Preferences" with
> the rest of mail_help.xhtml (with Mail & Newsgroups Preferences removed) left
> alone apart from the changes needed to link to the new mail_preferences.xhtml
> file (or whatever it is called).


I'm not sure if I'm getting you right. So, shouldn't I update the affected links by the split through the whole help content in this phase?


> Once that patch is reviewed and committed then
> look at the next one (this where mercurial queues come in hand).
> Suggestions for top level boxes - "Topics Covered:" or "In this chapter:"


I guess that I don't need to care about mercurial queues, since I don't intend to commit myself. Or do I? :-)

Comment 41

[Ian Neal]

(In reply to comment #40)
> (In reply to comment #37)
> > In terms of reviewing, the easiest way would be to work from the bottom to the
> > top (as you say), so generate a patch for "Mail & Newsgroups Preferences" with
> > the rest of mail_help.xhtml (with Mail & Newsgroups Preferences removed) left
> > alone apart from the changes needed to link to the new mail_preferences.xhtml
> > file (or whatever it is called).
> 
> 
> I'm not sure if I'm getting you right. So, shouldn't I update the affected
> links by the split through the whole help content in this phase?
Yes, you should, so you will have a mail_help.xhtml with the "Mail & Newsgroups Preferences" chopped from the bottom of it and the links to "Mail & Newsgroups Preferences" updated.

> 
> 
> > Once that patch is reviewed and committed then
> > look at the next one (this where mercurial queues come in hand).
> > Suggestions for top level boxes - "Topics Covered:" or "In this chapter:"
> 
> 
> I guess that I don't need to care about mercurial queues, since I don't intend
> to commit myself. Or do I? :-)

No, but it depends whether you want to only do one patch at a time or have a few on the go.

Comment 42

[Ian Neal]

How is this progressing Ricardo?

Comment 43

[RickieES aka Ricardo Palomares]

(In reply to comment #42)
> How is this progressing Ricardo?

Not much yet, because I want to write a script to automate the updates of cross-file links, and I've been a bit lazy, to be honest. I promise to move faster in coming days.

Comment 44

[Jens Hatlak (:InvisibleSmiley)]

Attachment: split script

(In reply to comment #43)
> (In reply to comment #42)
> > How is this progressing Ricardo?
> 
> Not much yet, because I want to write a script to automate the updates of
> cross-file links, and I've been a bit lazy, to be honest.

This might help. :-)

Actually I first wanted to do it in PHP, where I feel at home, but the shell script was more of a challenge. ;-)

You'll need a recent grep (the one in MozillaBuild is too old, unfortunately). Any decent Linux should do, otherwise Cygwin is your friend.

Comment 45

[RickieES aka Ricardo Palomares]

OK, so this is really embarrassing, you're doing the work for me. :-( I'm going to test your script right now with the last split (Mail & Newsgroup preferences), per comment #36.

Thanks a lot for the script.

Comment 46

[RickieES aka Ricardo Palomares]

Your script seems to work fine (big news to you, uh?). :-) I've forgotten to use hg copy, so I'll need another try. If I've understood comment #35 correctly, the sequence I need to follow is:

1) hg copy mail_help.xhtml splitted_file
2) Remove splitted content in mail_help.xhtml
3) Remove everything but the splitted content in splitted_file
4) Adjust <head> section in splitted_file
5) Adjust splitted link in main ToC of mail_help.xhtml
6) Ensure both files are XHTML valid
7) Provide a patch? (Is it needed at this point?)
8) Run Jens' split script
9) Adjust line widths in modified files
10) Ensure modified files are XHTML/RDF valid
11) Provide a patch

Should I use "mailnews_" as filename preffix, as outlined in comment #38?

Comment 47

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #46)
> Your script seems to work fine (big news to you, uh?). :-)

You might have guessed it: My test case was your first task. ;-)

> 7) Provide a patch? (Is it needed at this point?)

I don't think so. Somewhere before providing a patch you should add the "top level box" ("In this chapter:") task, though.

> Should I use "mailnews_" as filename preffix, as outlined in comment #38?

Depends on which reviewer you choose, or what IanN has to say. ;-)

Comment 48

[Robert Kaiser]

(In reply to comment #46)
> I've forgotten to use hg copy, so I'll need another try.

There is hg copy -A which allows announcing a copy to hg after actually doing it :)

Comment 49

[RickieES aka Ricardo Palomares]

Attachment: Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted using Jens' script and several long lines adjusted to fit into 80 characters. ABSOLUTELY no other changes

This is just a first test patch so we can get an idea of how the entire process would look for each split. Assuming it suits the ideas we all have of solving this bug, then my next question is (I know I asked this before, but I think we must absolutely agree on this before going on): do we have a patch for each and every split, get it reviewed and committed and then start again with the next split? Or do we have a single big patch for the entire split?

If the answer is a patch for each split and no obvious problems stand out in this initial patch, then I'll set the review flag on this.

Also, I've taken the freedom to announce in the patch description that no other changes are being done but the split, link adjustment and aestethic line width fixes. I think it would be nice to write something similar as the commit message for localizers. :-)

Comment 50

[RickieES aka Ricardo Palomares]

(In reply to comment #49)
> do we have a patch for each and

s/have/want/

> every split, get it reviewed and committed and then start again with the next
> split? Or do we have a single big patch for the entire split?


BTW, this looks like it is going to be really easy thanks to Jens' script, so much that all due credit when this bug is fixed must go to him. :-)

Comment 51

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #49)
> Created an attachment (id=454911) [details]
> Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted
> using Jens' script and several long lines adjusted to fit into 80 characters.

I'm not sure we should re-wrap lines where no other (anchor/link) changes were made. I'm not totally opposed to that either but it makes using hg blame harder with very little benefit. I'll leave this decision to Ian.

> This is just a first test patch so we can get an idea of how the entire process
> would look for each split. Assuming it suits the ideas we all have of solving
> this bug, then my next question is (I know I asked this before, but I think we
> must absolutely agree on this before going on): do we have a patch for each and
> every split, get it reviewed and committed and then start again with the next
> split? Or do we have a single big patch for the entire split?

Certainly one patch per new file, no big patch for everything. Either have each one checked in for you after review, then go on, or dive into Mercurial queues (I could hardly help you there, I'm not using those due to the added complexity).

> If the answer is a patch for each split and no obvious problems stand out in
> this initial patch, then I'll set the review flag on this.

You need to add the new file to suite/locales/jar.mn. For each patch. Otherwise it won't be packaged and won't be found by SeaMonkey. If you can, check yourself by re-compiling SeaMonkey after you made changes. Otherwise the reviewer will (have to) do it for you.

Otherwise looks good to me. Maybe have Ian take a quick look, too.

> Also, I've taken the freedom to announce in the patch description that no other
> changes are being done but the split, link adjustment and aestethic line width
> fixes. I think it would be nice to write something similar as the commit
> message for localizers. :-)

Err... I cannot see that in your patch?

Comment 52

[Ian Neal]

(In reply to comment #49)
> Created an attachment (id=454911) [details]
> Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted
> using Jens' script and several long lines adjusted to fit into 80 characters.
> ABSOLUTELY no other changes
I would only make long line adjustments within the section you are actually splitting off, so the ones you have in this patch should wait until they are split off.
If there are any other long line adjustments once all the split patches have been done, then that would be a separate patch.

One patch per new file definitely. I know the first will be the biggest (of course) and most of it is just lines being deleted but it is still daunting having patches that big.

Comment 53

[Ian Neal]

Comment on attachment 454911 [details] [diff] [review]
Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted using Jens' script and several long lines adjusted to fit into 80 characters. ABSOLUTELY no other changes

>+++ b/suite/locales/en-US/chrome/common/help/mail_help.xhtml
>@@ -4971,632 +4972,10 @@
>         is 465.</li>
>     </ul>
>   </li>
> </ul>
> 
> <p>[<a href="#mail_and_newsgroups_account_settings">Return to beginning of
>   section</a>]</p>
> 
Remove this trailing blank line.

Comment 54

[RickieES aka Ricardo Palomares]

(In reply to comment #51)
> I'm not sure we should re-wrap lines where no other (anchor/link) changes were
> made.


OK, changes restored.


> You need to add the new file to suite/locales/jar.mn. For each patch.
> Otherwise it won't be packaged and won't be found by SeaMonkey.


Added. However, I don't have Mozilla Build environment set up and I'm using Mandriva Linux, which makes a bit harder for me to set it up. If you can wait, I could give it a try tomorrow.


> > Also, I've taken the freedom to announce in the patch description that no
> > other changes are being done but the split, link adjustment and aestethic
> > line width fixes. I think it would be nice to write something similar as
> > the commit message for localizers. :-)
> 
> Err... I cannot see that in your patch?


I meant the patch description: "Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted using Jens' script and several long lines adjusted to fit into 80 characters. ABSOLUTELY no other changes"

Comment 55

[RickieES aka Ricardo Palomares]

Attachment: Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted using Jens' script. ABSOLUTELY no other changes [Checkin: Comment 63]

Second try. :-)

Comment 56

[Ian Neal]

(In reply to comment #55)
> Created an attachment (id=455297) [details]
> Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted
> using Jens' script. ABSOLUTELY no other changes
> 
> Second try. :-)

Looks good to me on first view, I'll have to apply and test before 100% happy.

Comment 57

[Jens Hatlak (:InvisibleSmiley)]

IanN: ping

Comment 58

[Ian Neal]

Comment on attachment 455297 [details] [diff] [review]
Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted using Jens' script. ABSOLUTELY no other changes [Checkin: Comment 63]

I was just thinking about this the other day, been running with the patch for a while and not spotted any problems. r=me

Comment 59

[RickieES aka Ricardo Palomares]

(In reply to comment #58)
> Comment on attachment 455297 [details] [diff] [review]
> Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted
> using Jens' script. ABSOLUTELY no other changes
> 
> I was just thinking about this the other day, been running with the patch for a
> while and not spotted any problems. r=me


So, I understand I can proceed with the next split, can't I?

Comment 60

[rsx11m]

Maybe get this checked in first and then take it from there in an incremental way rather than ending up with one big patch?

Comment 61

[RickieES aka Ricardo Palomares]

(In reply to comment #60)
> Maybe get this checked in first and then take it from there in an incremental
> way rather than ending up with one big patch?


OK, I've added checkin-needed keyword (it the right way, isn't it?).

I wonder if "helpwanted" keyword is still needed now that the bug seems to be on track. :-?

Comment 62

[rsx11m]

If there is nothing else to do here, or if you will take care of whatever
else has to be done following that patch, you can sure remove the helpwanted. I'm actually not entirely sure either what its meaning is - it appears to be redundant once a bug is taken, and also if nobody owns a bug...

Comment 63

[Ian Neal]

Comment on attachment 455297 [details] [diff] [review]
Mail & Newsgroup preferences split from mail_help.xhtml, with links adjusted using Jens' script. ABSOLUTELY no other changes [Checkin: Comment 63]

http://hg.mozilla.org/comm-central/rev/3061bbc82e7d

Ready for the next one now :)

Comment 64

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #61)
> (In reply to comment #60)
> > Maybe get this checked in first and then take it from there in an incremental
> > way rather than ending up with one big patch?
> 
> OK, I've added checkin-needed keyword (it the right way, isn't it?).

Yes, even though both Ian and me are closely monitoring this bug so one of us
will push whatever patch here has reviews for you anyway. I was already about
to do just that when I noticed that my usual method of using git apply leaves
hg without the information that the new file was copied from the old one and
then adapted (in fact it doesn't know about the new file at all, but in other
cases that's just a matter of hg add). After some investigation I found that the right way to do it is hg import [-u -m] -f (I keep uncommitted changes around). But Ian was faster. ;-)

> I wonder if "helpwanted" keyword is still needed now that the bug seems to be
> on track. :-?

It's not. As far as I understand it it means that the bug commenters either do not have the knowledge or time to fix the bug or to clarify how to fix it.
Clearly that's not the case here (anymore).

Comment 65

[RickieES aka Ricardo Palomares]

(In reply to comment #64)
> (...) I was already about
> to do just that when I noticed that my usual method of using git apply leaves
> hg without the information that the new file was copied from the old one and
> then adapted (in fact it doesn't know about the new file at all, but in other
> cases that's just a matter of hg add). After some investigation I found that
> the right way to do it is hg import [-u -m] -f (I keep uncommitted changes
> around). But Ian was faster. ;-)


Oops, I've started to work in the next split and, while checking the result, I've just come to an internal link in mail_help.xhtml pointing to the splitted section that has not been updated to point to the new file (line 311 in mail_help.xhtml, internal link <a href="#security">... should have been converted to <a href="mailnews_account_settings.xhtml#security">...).

I'll have to check if this happened in the first split. Please, give me three or four days to report back and, if I manage to fully understand Jens' script, to provide a new version of it. Sorry for not having catched this before. :-(

Comment 66

[Jens Hatlak (:InvisibleSmiley)]

Yes, you're right. That was an oversight on my side. Sorry about that. I'm already working on a fix for the script.

Meanwhile here are the missing references for the first split so you don't have to wait for me and can start correcting those:

jens:help > for id in $(grep -hoE " id=\"[^\"]+\"" mailnews_preferences.xhtml | sed 's, id=,,;s,",,g'); do grep -n "\"#$id\"" mail_help.xhtml; done
531:  in the <a href="#mail_and_newsgroups">Mail &amp; Newsgroups Preferences</a>
414:  an alert when new mail arrives, see <a href="#notifications">Mail &amp;
860:    <a href="#composition">Composition</a> preferences. This command is
940:    <a href="#composition">Composition</a>. (If no subcategories are visible,
4419:    <a href="#composition">forwarding inline</a>.</li>
1185:    <a href="#send_format">Send Format</a>. (If no subcategories are visible,
4423:  specified for all <a href="#addressing_preferences">address books</a> in the
727:    <p>If you have <a href="#address_autocompletion">address autocompletion</a>
1531:  <a href="#address_autocompletion">address autocompletion</a>.</p>
4425:  <a href="#address_autocompletion">address autocompletion</a>, and you can
2775:  <a href="#junk_and_suspect_preferences">Junk &amp; Suspect Mail preference
4698:  <a href="#junk_and_suspect_preferences">Mail &amp; Newsgroups Preferences -
833:    <a href="#return_receipts_preferences">Mail &amp; Newsgroups Preferences -
971:  <a href="#return_receipts_preferences">Return Receipt</a> preferences to
989:    <a href="#return_receipts_preferences">Return Receipts</a>. (If no
997:  <a href="#return_receipts_preferences">Mail &amp; Newsgroups Preferences -
4748:  <a href="#return_receipts_preferences">Mail &amp; Newsgroups Preferences -
4754:    preferences specified by <a href="#return_receipts_preferences">Mail &amp;
3554:  <a href="#network_and_storage_preferences">offline preferences</a> for all
3610:  menu to change your <a href="#network_and_storage_preferences">offline
3681:  menu to change your <a href="#network_and_storage_preferences">offline

Comment 67

[Jens Hatlak (:InvisibleSmiley)]

Attachment: split script v2

This should fix it. I added the new case (grep+if) in part 1, after the anchor of the current loop run has been determined and printed.

Comment 68

[RickieES aka Ricardo Palomares]

(In reply to comment #66)
> Yes, you're right. That was an oversight on my side. Sorry about that. I'm
> already working on a fix for the script.


No problem, I'm right now reviewing my just-started Perl script to try to finish it (that was my homework, after all, and I'm the one to blame for not doing it). It seems that the same issue happens with mail_help.xhtml internal links used in splitted content (for instance, "working_offline" in line 634 of mailnews_preferences.xhtml).


> Meanwhile here are the missing references for the first split so you don't
> have to wait for me and can start correcting those:


Thank you very much. I guess we want a "fix-only" patch to complete the first split and then proceed with the next split, don't we?

I may work a little bit more in my Perl script anyway (I feel I'm closer than my previous attempts, where I had big problems trying to find the right regular expresions to use). In fact, I already have the internal links to fix in both mail_help.xhtml and mailnews_preferences.xhtml.

Comment 69

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #68)
> It seems that the same issue happens with mail_help.xhtml internal
> links used in splitted content (for instance, "working_offline" in line 634 of
> mailnews_preferences.xhtml).

Strange. My script was supposed to take care of that, and running it again on mailnews_preferences.xhtml proved to me that it works (even in the first, now obsolete version). Did you modify it before you used it?

Anyway, once you have your Perl script it would be interesting to compare its results to those of mine (v2 of course).

> I guess we want a "fix-only" patch to complete the first
> split and then proceed with the next split, don't we?

Exactly.

Comment 70

[RickieES aka Ricardo Palomares]

(In reply to comment #69)
> (In reply to comment #68)
> > It seems that the same issue happens with mail_help.xhtml internal
> > links used in splitted content (for instance, "working_offline" in line 634 of
> > mailnews_preferences.xhtml).
> 
> Strange. My script was supposed to take care of that, and running it again on
> mailnews_preferences.xhtml proved to me that it works (even in the first, now
> obsolete version). Did you modify it before you used it?


Actually, I had to "retype" every newline character (merge and break every line with the next one) because my shell didn't like the way it was when I downloaded the patch. I've just downloaded it again and compared with my "modified" version and the only differences are a couple of additional newlines at the end, and an "exit 0" that I added because I kept getting a syntax error at the end of the script.

Comment 71

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #70)
> Actually, I had to "retype" every newline character (merge and break every line
> with the next one) because my shell didn't like the way it was when I
> downloaded the patch.

Pro tip: Open the file with vi (vim), type ":set ff=unix", press Enter, type ":w" (to save, or ":x" to also quit), again press Enter. Or, on Windows, use a decent editor like Notepad++ or SciTE which allows you to change the line ends. In no event should you (have to) change the line ends manually.

Comment 72

[RickieES aka Ricardo Palomares]

(In reply to comment #71)
> Pro tip: Open the file with vi (vim), type ":set ff=unix", press Enter, type
> ":w" (to save, or ":x" to also quit), again press Enter. Or, on Windows, use a
> decent editor like Notepad++ or SciTE which allows you to change the line ends.
> In no event should you (have to) change the line ends manually.


To be honest, I was quite puzzled to have to mess with line-endings in Linux given a shell script. :-? I don't know if I misunderstood some error message or what.

Anyway, I'm attaching a yet to be further tested version of my Perl script and its output. Please, be merciful with my rusty programming abilities. O:-)

Comment 73

[RickieES aka Ricardo Palomares]

Attachment: First version of Perl script trying to do the same than Jens' shell script

I've tested successfully this script in both en-US and es-ES unfinished first split, and it seems to work fine.

However, I yet have to run it with the second split (once we get the second patch for first split checked in) to be fully sure it works OK.

Comment 74

[RickieES aka Ricardo Palomares]

Attachment: My Perl script output for the unfinished first split

My Perl script is probably more verbose than Jens' script, I can make it quieter if needed.

Comment 75

[RickieES aka Ricardo Palomares]

Attachment: Fix href links in mail_help.xhtml and mailnews_preferences.xhtml that should have been changed in the previous patch

This patch has been generated with the Perl script, not the shell script.

Comment 76

[Ian Neal]

Comment on attachment 460332 [details] [diff] [review]
Fix href links in mail_help.xhtml and mailnews_preferences.xhtml that should have been changed in the previous patch

You need to remember the 80 column limit where it can be done.

Comment 77

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #72)
> To be honest, I was quite puzzled to have to mess with line-endings in Linux
> given a shell script. :-? I don't know if I misunderstood some error message or
> what.

Linux shell scripts must have Linux (LF) line ends to function correctly, especially with the first line (shebang).

> Anyway, I'm attaching a yet to be further tested version of my Perl script and
> its output. Please, be merciful with my rusty programming abilities. O:-)

If I try really hard I can read simple Perl, but never bothered to learn it so that I could write it. I'm a PHP guy. ;-) BTW I finally came around to writing a PHP script that checks all Help files for wrong links. It found 37 errors, most of which had been introduced through this bug. I can attach it if you want, or you can give your Perl fu another try. :-)

Comment 78

[RickieES aka Ricardo Palomares]

Attachment: Fix href links in mail_help.xhtml and mailnews_preferences.xhtml that should have been changed in the previous patch (second try) [Checkin: Comment 79]

Somehow I got confused about this, sorry.

Comment 79

[Ian Neal]

Comment on attachment 460691 [details] [diff] [review]
Fix href links in mail_help.xhtml and mailnews_preferences.xhtml that should have been changed in the previous patch (second try) [Checkin: Comment 79]

http://hg.mozilla.org/comm-central/rev/94612a230a11

Comment 80

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #77)
> BTW I finally came around to writing
> a PHP script that checks all Help files for wrong links. It found 37 errors,
> most of which had been introduced through this bug. I can attach it if you
> want, or you can give your Perl fu another try. :-)

I attached it to bug 582710.

Comment 81

[RickieES aka Ricardo Palomares]

(In reply to comment #76)
> You need to remember the 80 column limit where it can be done.


I'm about to prepare the second split, now hopefully with the right changes, and I wonder if I should adjust line widths in files affected by the split others than mail_help.xhtml and the new split file. For instance, there are four links changed in mail_sec_help.xhtml that turn the respective lines go beyond 80 characters long. Can/Should I adjust them? In Comment #51, Jens said:

> I'm not sure we should re-wrap lines where no other (anchor/link) changes were
> made. I'm not totally opposed to that either but it makes using hg blame harder
> with very little benefit. I'll leave this decision to Ian.

and, in Comment #52, Ian said:

> I would only make long line adjustments within the section you are actually
> splitting off, so the ones you have in this patch should wait until they are
> split off.
> If there are any other long line adjustments once all the split patches have
> been done, then that would be a separate patch.


I'm not completely sure if Ian means that line width adjustments should happen exclusively in the new splitted file, leaving apart mail_help.xhtml and the rest of help content files. If so, previous patches would have failed this condition, since both adjusted width also in mail_help.xhtml.

TIA

Comment 82

[RickieES aka Ricardo Palomares]

(In reply to comment #80)
> (In reply to comment #77)
> > BTW I finally came around to writing
> > a PHP script that checks all Help files for wrong links. It found 37 errors,
> > most of which had been introduced through this bug. I can attach it if you
> > want, or you can give your Perl fu another try. :-)
> 
> I attached it to bug 582710.


I've run it in both en-US (with the mailnews_account_settings.xhtml new split, and my Perl script run on the directory) and es-ES, and it reports 0 errors in both. Shouldn't it report the other errors mentioned in bug 582710? I'm running it in the current help directory this way:

$ php helplinkcheck.php .

Comment 83

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #81)
> (In reply to comment #76)
> > You need to remember the 80 column limit where it can be done.
> I'm not completely sure if Ian means that line width adjustments should happen
> exclusively in the new splitted file, leaving apart mail_help.xhtml and the
> rest of help content files. If so, previous patches would have failed this
> condition, since both adjusted width also in mail_help.xhtml.

I'd say just continue like you did before, correcting all line lengths of changes lines.

(In reply to comment #82)
> I've run it in both en-US (with the mailnews_account_settings.xhtml new split,
> and my Perl script run on the directory) and es-ES, and it reports 0 errors in
> both. Shouldn't it report the other errors mentioned in bug 582710? I'm running
> it in the current help directory this way:
> 
> $ php helplinkcheck.php .

It seems your php binary doesn't output warnings. I always ran my script with a full path, and it appears that's a requirement (of course it could be changed easily, but there's no real need). Just add a slash at the end (making it ./).

Comment 84

[Ian Neal]

(In reply to comment #81)
> (In reply to comment #76)
> and, in Comment #52, Ian said:
> 
> > I would only make long line adjustments within the section you are actually
> > splitting off, so the ones you have in this patch should wait until they are
> > split off.
> > If there are any other long line adjustments once all the split patches have
> > been done, then that would be a separate patch.
> 
> 
> I'm not completely sure if Ian means that line width adjustments should happen
> exclusively in the new splitted file, leaving apart mail_help.xhtml and the
> rest of help content files. If so, previous patches would have failed this
> condition, since both adjusted width also in mail_help.xhtml.
As Jens says, keep doing it the way you have been doing, as that is the way I intended for you to do it.

Comment 85

[RickieES aka Ricardo Palomares]

Attachment: My Perl script output for the second split

Perl script output after second split (mail & news account settings)

Comment 86

[RickieES aka Ricardo Palomares]

Attachment: Jens' shell script output for the second split

Jens' shell script output. While both outputs are sorted in different ways, I've visually compared some of the outputs and it seems that both scripts report the same modifications.

Comment 87

[RickieES aka Ricardo Palomares]

Attachment: Mail & Newsgroup account settings split from mail_help.xhtml, with links adjusted using my Perl script. ABSOLUTELY no other changes [Checkin: Comment 90]

The link adjustments have been done by running my Perl script, mainly because the Perl script outputs line numbers and it eases the width line adjustments (well, and also because I'm proud to finally have got it running!). :-)

Comment 88

[Ian Neal]

(In reply to comment #87)
> Created attachment 461062 [details] [diff] [review]
> Mail & Newsgroup account settings split from mail_help.xhtml, with links
> adjusted using my Perl script. ABSOLUTELY no other changes
> 
> The link adjustments have been done by running my Perl script, mainly because
> the Perl script outputs line numbers and it eases the width line adjustments
> (well, and also because I'm proud to finally have got it running!). :-)

You're missing the jar.mn changes...

Comment 89

[Ian Neal]

Comment on attachment 461062 [details] [diff] [review]
Mail & Newsgroup account settings split from mail_help.xhtml, with links adjusted using my Perl script. ABSOLUTELY no other changes [Checkin: Comment 90]

Added jar.nm changes locally and not found any issues.

Comment 90

[Ian Neal]

Comment on attachment 461062 [details] [diff] [review]
Mail & Newsgroup account settings split from mail_help.xhtml, with links adjusted using my Perl script. ABSOLUTELY no other changes [Checkin: Comment 90]

http://hg.mozilla.org/comm-central/rev/ed94c018e778

Checked in with jar.nm change too.

Comment 91

[RickieES aka Ricardo Palomares]

Attachment: Patch to split "Working offline"

I've chosen "mailnews_offline.xhtml" as filename for this split; I think a shorter name is better if it is not confusing.

I've written a brief introduction at the top of the file; you really should take a look to it and propose changes if you don't like it. :-)

Comment 92

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #91)
> Created attachment 462204 [details] [diff] [review]
> Patch to split "Working offline"

"&brandShortName; Mail & News" should probably be "&brandShortName; Mail & Newsgroups" (MailNews is just the short version of that).

Comment 93

[RickieES aka Ricardo Palomares]

(In reply to comment #92)
> "&brandShortName; Mail & News" should probably be "&brandShortName; Mail
> & Newsgroups" (MailNews is just the short version of that).


Besides that, do everybody agree with the introduction I've written? I expected more improvement requests in it. :-)

If everything else is OK, I'll provide a new patch tonight.

Comment 94

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #93)
> (In reply to comment #92)
> > "&brandShortName; Mail & News" should probably be "&brandShortName; Mail
> > & Newsgroups" (MailNews is just the short version of that).
> 
> 
> Besides that, do everybody agree with the introduction I've written?

I'll leave that to the reviewer. ;-)

> If everything else is OK, I'll provide a new patch tonight.

If you do, please update and check that the changes from bug 582710 (just checked in) persist.

Comment 95

[Ian Neal]

Comment on attachment 462204 [details] [diff] [review]
Patch to split "Working offline"

+<p>&brandShortName; Mail &amp; News includes advanced features to help you
+  manage your messaging needs when you are not connected to the Internet.
+  You can download mail and news messages before going offline for later
+  reading, and you can defer mail messages and newsgroup posts until you
+  get back online. All of this is explained in this document.</p>

As Jens, mentioned, change to Newsgroups at the beginning.
Need to specify what is being deferred. "...you can defer sending of mail messages and newsgroup posts..." perhaps?
Last sentence has too many this's. "All of these features are explained in this document." perhaps?

r=me with that fixed (and as Jens says keeping changes from bug 582710).

Comment 96

[RickieES aka Ricardo Palomares]

(In reply to comment #95)
> Last sentence has too many this's. "All of these features are explained in this
> document." perhaps?


"All of these features" or "All these features"? The latter sounds more natural to me, but as I'm not a native English speaker, I'm probably wrong.

I've just checked that changes from bug 582710 have smoothly merged with my working copy. Nice. :-)

Comment 97

[RickieES aka Ricardo Palomares]

Attachment: Patch to split "Working offline" with changes requested in comments #94 and #95, and including changes in bug 582710 [Checkin: Comment 100]

Searching for "All these features" in Google reported about 11M results, whereas doing the same for "All of these features" gives back about 72M. So I was wrong, and have keep "All of these features...". :-)

Comment 98

[RickieES aka Ricardo Palomares]

Setting "checkin-needed" to get it committed to the repo.

Comment 99

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #98)
> Setting "checkin-needed" to get it committed to the repo.

The updated patch is missing the hg copy part. I guess that can be fixed during check-in, though.

Comment 100

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #99)
> (In reply to comment #98)
> > Setting "checkin-needed" to get it committed to the repo.
> 
> The updated patch is missing the hg copy part. I guess that can be fixed during
> check-in, though.

http://hg.mozilla.org/comm-central/rev/5c7911129336

The jar.mn changes were also missing from the updated patch. Fixed upon check-in, too. Please diff your patches before submitting (can happen to all of us, but please try to keep it in mind).

Comment 101

[Ian Neal]

Comment on attachment 463118 [details] [diff] [review]
Patch to split "Working offline" with changes requested in comments #94 and #95, and including changes in bug 582710 [Checkin: Comment 100]

Sorry, did spot the missing jar.mn changes but forgot to mention them. Thanks for picking up the missing hg copy though.

Comment 102

[RickieES aka Ricardo Palomares]

(In reply to comment #100)
> (In reply to comment #99)
> > 
> > The updated patch is missing the hg copy part. I guess that can be fixed
> > during check-in, though.
> 
> http://hg.mozilla.org/comm-central/rev/5c7911129336
> 
> The jar.mn changes were also missing from the updated patch. Fixed upon
> check-in, too. Please diff your patches before submitting (can happen to all
> of us, but please try to keep it in mind).


Sorry for missing the jar.mn part, I must get used not to create the diff in the help directory. Regarding the hg copy issue, to be honest I have absolutely no idea what happened and how could I have fixed it. I believed that, once I did hg copy to create the new splitted file, that would persist as long as the patch wasn't checked in and nobody else committed and pushed a file with the same name. :-?

Comment 103

[RickieES aka Ricardo Palomares]

(In reply to comment #100)
> > 
> > The updated patch is missing the hg copy part. I guess that can be fixed during
> > check-in, though.
> 
> http://hg.mozilla.org/comm-central/rev/5c7911129336


Oops, while mirroring recent changes into es-ES Localization I've found that the patch does the hg copy thing, but doesn't actually adjust the mailnews_offline.xhtml content at all.

I'm out of home now and my laptop doesn't have Internet access (I'm using another PC to check and write this). I will provide a patch as soon as I get home in about an hour.

I'm really sorry for this inconvenience. Could you explain me what went wrong with the hg copy process and why my second patch didn't include it (apparently, that new file should had not been modified by any other patch and, therefore, I expected no changes in that part of the patch)? If I understand what was the problem, I can pay more attention next time. Sorry again.

Comment 104

[RickieES aka Ricardo Palomares]

Attachment: Missing adjustment in mailnews_offline.xhtml to make it a real split [Checkin: Comment 105]

Revission in comment 100 just did hg copy from mail_help.xhtml to mailnews_offline.xhtml but did not make any changes to the new file to get it an actual split of Working offline section.

Comment 105

[Ian Neal]

Comment on attachment 464050 [details] [diff] [review]
Missing adjustment in mailnews_offline.xhtml to make it a real split [Checkin: Comment 105]

http://hg.mozilla.org/comm-central/rev/b3d432fa6c19

Comment 106

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #103)
> Oops, while mirroring recent changes into es-ES Localization I've found that
> the patch does the hg copy thing, but doesn't actually adjust the
> mailnews_offline.xhtml content at all.

Bah, that's my fault. I had everything laid out nicely for check-in when hg refused to push because of "multiple heads". There's a command to solve that, but I had uncommitted changes in my tree, which didn't allow me to use it. I was trying different things, in the end losing all my uncommitted changes (not too many, fortunately). Then I didn't have the nerve to do a diff again, also because it was only then when I found that the jar.mn changes had been missing, too. So I just used a modified version of your patch that didn't include the mailnews_offline.xhtml changes because I had done that separately, after doing the hg copy step. Of course that was now gone with all the other uncommitted changes, which I didn't realize. :-(

> I'm really sorry for this inconvenience. Could you explain me what went wrong
> with the hg copy process and why my second patch didn't include it (apparently,
> that new file should had not been modified by any other patch and, therefore, I
> expected no changes in that part of the patch)?

As you can see I'm not a Mercurial expert either. I'm not even using queues. In fact I'm more of an SVN guy. Simple, straight-forward (yes I know hg is useful for pros but way too complex for me!). I could imagine that maybe hg lost track of the "copy" state when you removed the file (did you?) and did and hg pull or similar. Just a guess.

BTW: http://hgbook.red-bean.com/read/mercurial-in-daily-use.html says one can tell hg that a file was copied after-the-fact using "hg copy --after a n". Haven't tried it, though. In this case, to get the same result, you would probably have had to temporarily revert the changes to the source file, do the hg copy --after and then reapply the changes to the source file.

Comment 107

[RickieES aka Ricardo Palomares]

(In reply to comment #106)
> Bah, that's my fault. I had everything laid out nicely for check-in when hg
> refused to push because of "multiple heads". There's a command to solve that,
> but I had uncommitted changes in my tree, which didn't allow me to use it. I
> was trying different things, in the end losing all my uncommitted changes (not
> too many, fortunately). Then I didn't have the nerve to do a diff again, also
> because it was only then when I found that the jar.mn changes had been missing,
> too. So I just used a modified version of your patch that didn't include the
> mailnews_offline.xhtml changes because I had done that separately, after doing
> the hg copy step. Of course that was now gone with all the other uncommitted
> changes, which I didn't realize. :-(


Have I said "I'm really, really sorry" yet? :-( I have the next patch ready, with jar.mn, and I'm going to review it before uploading it to get sure it includes the hg copy thing, no lines longer than 80 characters and no traces of nuts. :-)


> I could imagine that maybe hg lost track
> of the "copy" state when you removed the file (did you?) and did and hg pull
> or similar. Just a guess.


I didn't touch mailnews_offline.xhtml after the first patch (that included the hg copy track). After you told me to care about changes from bug 582710, I updated comm-central using python client.py checkout, reviewed that bug 582710 had been applied in the new patch and uploaded the new version (although I forgot to create the diff from the locales directory instead of directly from chrome/common/help). That's what has puzzled me about this, that the file should had been still a new file for Mercurial after updating the repo... or not? Maybe doing a checkout erased my local changeset and that's why the file no longer had the hg copy state. :-?


> BTW: http://hgbook.red-bean.com/read/mercurial-in-daily-use.html says one can
> tell hg that a file was copied after-the-fact using "hg copy --after a n".
> Haven't tried it, though. In this case, to get the same result, you would
> probably have had to temporarily revert the changes to the source file, do the
> hg copy --after and then reapply the changes to the source file.


Yes, that's the long version of the -A flag Robert mentioned in comment #48. If, for any reason, I have to update the repo after creating a split file and before providing the final, to be checked in patch, I'll make sure it contains the hg copy status.

Comment 108

[RickieES aka Ricardo Palomares]

Attachment: Patch to split "Getting started with blogs and news feeds" [Checkin: comment 116]

This time I've double-checked that jar.mn is included, the new file is created through an hg copy operation and no line wider than 80 characters is introduced due to the patch. Let's cross fingers. :-)

Comment 109

[Ian Neal]

(In reply to comment #108)
> Created attachment 464184 [details] [diff] [review]
> Patch to split "Getting started with blogs and news feeds"
> 
> This time I've double-checked that jar.mn is included, the new file is created
> through an hg copy operation and no line wider than 80 characters is introduced
> due to the patch. Let's cross fingers. :-)

All looks good, you'll need to request a= if you want it in the tree at the moment though.

Comment 110

[RickieES aka Ricardo Palomares]

(In reply to comment #109)
> All looks good, you'll need to request a= if you want it in the tree at the
> moment though.


That's approval, I guess. Does it involve additional workload for a driver/superreviewer? If so, I'm fine with some delay. :-)

Comment 111

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #110)
> (In reply to comment #109)
> > All looks good, you'll need to request a= if you want it in the tree at the
> > moment though.
> 
> That's approval, I guess.

Correct.

> Does it involve additional workload for a driver/superreviewer?

No. It just means that you need to write in a comment why you think it's valuable and safe to take the patch in question for the respective release (here: alpha 3). In this case the value is low (just internal restructuring, but not even the final bit of that) but on the other hand the risk is also low. Your call.

Comment 112

[RickieES aka Ricardo Palomares]

(In reply to comment #111)
> No. It just means that you need to write in a comment why you think it's
> valuable and safe to take the patch in question for the respective release
> (here: alpha 3). In this case the value is low (just internal restructuring,
> but not even the final bit of that) but on the other hand the risk is also low.
> Your call.


I think I will wait. For what I've read from SM Status Meeting, it seems SM2.1a3 is a matter of days. I'm on holidays now and hope to be faster with splitting en-US & porting it to es-ES, so if I don't badly screw it up with patches :-) this bug should be fixed by the end of August.

Comment 113

[RickieES aka Ricardo Palomares]

(In reply to comment #112)
> I think I will wait. For what I've read from SM Status Meeting, it seems
> SM2.1a3 is a matter of days. I'm on holidays now and hope to be faster with
> splitting en-US & porting it to es-ES, so if I don't badly screw it up with
> patches :-) this bug should be fixed by the end of August.


Apparently, the tree is open now:

http://tinderbox.mozilla.org/SeaMonkey/

Can I set the checkin-needed flag? Or is it better to wait until SM2.1a3 is officially released?

Comment 114

[rsx11m]

Since the release branch has been cut, go ahead with your checkin request.

Comment 115

[RickieES aka Ricardo Palomares]

Checkin-needed flag set. I've manually checked that no changesets touching the affected files have entered into the repo after I created the patch.

Comment 116

[Jens Hatlak (:InvisibleSmiley)]

Comment on attachment 464184 [details] [diff] [review]
Patch to split "Getting started with blogs and news feeds" [Checkin: comment 116]

http://hg.mozilla.org/comm-central/rev/65f92e04143a

Comment 117

[RickieES aka Ricardo Palomares]

I'd like to discuss the filenames for the remaining sections to split. Until now, it seems that I've been sensible with regard to this, but we're about to mix sections, and I'd rather read your opinions before taking too much freedom. :-)

> Proposed setup:
> 1. MailNews + Importing
> 2. Reading + Sending + Creating HTML + Attachments + Deleting
> 3. AB
> 4. Organizing + Junk
> 5. News


The above are the remaining sections. I'd propose these names:

1. mail_help.xhtml (my guess)
2. mailnews_using_mail.xhtml
3. mailnews_addressbooks.xhtml
4. mailnews_organizing.xhtml
5. mailnews_newsgroups.xhtml

Is this fine?

Comment 118

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #117)
> 1. mail_help.xhtml (my guess)

If we wanted to achieve consistency this should be mailnews_help.xhtml, and mail_sec_help.xhtml should be renamed to mailnews_security.xhtml or something like that. That would require some link adjustments, though. I'll leave the decision to Ian.

The rest is fine with me, only addressbooks may as well be address_books.

Comment 119

[Ian Neal]

(In reply to comment #118)
> (In reply to comment #117)
> > 1. mail_help.xhtml (my guess)
> 
> If we wanted to achieve consistency this should be mailnews_help.xhtml, and
> mail_sec_help.xhtml should be renamed to mailnews_security.xhtml or something
> like that. That would require some link adjustments, though. I'll leave the
> decision to Ian.
> 
> The rest is fine with me, only addressbooks may as well be address_books.

I would suggest:
mailnews_getting_started.xhtml

As far as the addressbook, either stick with mailnews_addressbooks.xhtml or mailnews_addressing.xhtml

I agree with Jens on the renaming of mail_sec_help.xhtml to mailnews_security.xhtml

Comment 120

[RickieES aka Ricardo Palomares]

Attachment: Patch to split "Getting started with newsgroups" [Checkin: Comment 123]

Comment 121

[RickieES aka Ricardo Palomares]

Before I forget... Once patch 467360 lands, the next section at the bottom of mail_help.xhtml will be "Importing mail", which should be moved after the first section "Getting Started with &brandShortName; Mail & Newsgroups". Do you think we can do that move in a separate patch, so we don't carry it as a "backpack" at the end of mail_help during the remaining splits?

Comment 122

[Ian Neal]

(In reply to comment #121)
> Before I forget... Once patch 467360 lands, the next section at the bottom of
> mail_help.xhtml will be "Importing mail", which should be moved after the first
> section "Getting Started with &brandShortName; Mail & Newsgroups". Do you think
> we can do that move in a separate patch, so we don't carry it as a "backpack"
> at the end of mail_help during the remaining splits?

If it is easier, do it as a separate patch.

Comment 123

[Ian Neal]

Comment on attachment 467360 [details] [diff] [review]
Patch to split "Getting started with newsgroups" [Checkin: Comment 123]

http://hg.mozilla.org/comm-central/rev/05a1075aee8f

Comment 124

[RickieES aka Ricardo Palomares]

Attachment: Moving "Importing mail from other programs" right after "Getting started with Mail & Newsgroups" [Checkin: Comment 125]

As discussed in comment #121 and #122, here it is my proposed patch to relocate "Importing mail from other programs" to its final position as agreed in comment #36.

Comment 125

[Ian Neal]

Comment on attachment 469660 [details] [diff] [review]
Moving "Importing mail from other programs" right after "Getting started with Mail & Newsgroups" [Checkin: Comment 125]

http://hg.mozilla.org/comm-central/rev/10733fbe5be9

Comment 126

[RickieES aka Ricardo Palomares]

Attachment: Patch to split "Organizing + Junk" [Checkin: Comment 128]

Sorry, I'm back to job and I have less free time.

I've set the mailnews_organinizing HEAD title to "Organizing Your Messages and Controlling Junk", I hope that's OK.

Comment 127

[Ian Neal]

Comment on attachment 474352 [details] [diff] [review]
Patch to split "Organizing + Junk" [Checkin: Comment 128]

Looks good and applies fine too r=me

Comment 128

[Ian Neal]

Comment on attachment 474352 [details] [diff] [review]
Patch to split "Organizing + Junk" [Checkin: Comment 128]

http://hg.mozilla.org/comm-central/rev/563207057822

Comment 129

[RickieES aka Ricardo Palomares]

Attachment: Patch to split "Using address books" [Checked in: Comment 130]

Comment 130

[Ian Neal]

Comment on attachment 476620 [details] [diff] [review]
Patch to split "Using address books" [Checked in: Comment 130]

http://hg.mozilla.org/comm-central/rev/03d3b0290b78

Comment 131

[RickieES aka Ricardo Palomares]

Attachment: Patch to split Reading..., Sending..., Creating HTML mail..., Using attachments and Deleting messages [Checked in: Comment 132]

Since we agreed to name this split as mailnews_using_mail.xhtml, I've set the HEAD title of it to "Using &brandShortName; Mail".

I've also fixed the line width of the ToC entry "Controlling Junk" in mail_help.xhtml.

The next (and last!) :-) patch should cover the renaming of mail_help.xhtml to mailnews_getting_started.xhtml and mail_sec_help.xhtml to mailnews_security.xhtml. Or should I file a new bug for it?

Comment 132

[Ian Neal]

Comment on attachment 478565 [details] [diff] [review]
Patch to split Reading..., Sending..., Creating HTML mail..., Using attachments and Deleting messages [Checked in: Comment 132]

http://hg.mozilla.org/comm-central/rev/d7d688b76bb3

Comment 133

[RickieES aka Ricardo Palomares]

(In reply to comment #131)
> The next (and last!) :-) patch should cover the renaming of mail_help.xhtml to
> mailnews_getting_started.xhtml and mail_sec_help.xhtml to
> mailnews_security.xhtml. Or should I file a new bug for it?


I had not forgotten about this. :-) Although it should be just a matter of a grep or a sed call, I've prepared a "rename-sm-help.pl" script which is a short tweaked version of the update script, so it warns when the link changes to reflect the rename lead to lines longer than 80 characters. It may be useful for localizers following this bug.

I guess I should use "hg rename mail_help.xhtml mailnews_getting_started.xhtml" (and the same for mail_sec_help.xhtml) for the actual renaming, am I right?


(In reply to comment #119)
> I would suggest:
> mailnews_getting_started.xhtml

For mail_help.xhtml rename, should I change the <head> and/or first <h1> titles from "Using &brandShortName; Mail & Newsgroups" to "Getting Started with &brandShortName; Mail &amp; Newsgroups"? I'm almost certain I shouldn't touch the <h1> title, but I doubt about the <head> one.

TIA

Comment 134

[Ian Neal]

(In reply to comment #133)
> I guess I should use "hg rename mail_help.xhtml mailnews_getting_started.xhtml"
> (and the same for mail_sec_help.xhtml) for the actual renaming, am I right?
Sounds right, but a separate patch for each.
> 
> 
> (In reply to comment #119)
> > I would suggest:
> > mailnews_getting_started.xhtml
> 
> For mail_help.xhtml rename, should I change the <head> and/or first <h1> titles
> from "Using &brandShortName; Mail & Newsgroups" to "Getting Started with
> &brandShortName; Mail &amp; Newsgroups"? I'm almost certain I shouldn't touch
> the <h1> title, but I doubt about the <head> one.

Seems correct to change the <head> one, but not the <h1> one.

Comment 135

[RickieES aka Ricardo Palomares]

Attachment: Renaming mail_sec_help.xhtml to mailnews_security.xhtml [Checked in: Comment 136]

It seemed to me that mail_help.xhtml deserved to have the honor of starring the last, closing patch in this bug. :-)

Comment 136

[Ian Neal]

Comment on attachment 481083 [details] [diff] [review]
Renaming mail_sec_help.xhtml to mailnews_security.xhtml [Checked in: Comment 136]

http://hg.mozilla.org/comm-central/rev/e71902981730

Comment 137

[RickieES aka Ricardo Palomares]

Attachment: Renaming mail_help.xhtml to mailnews_getting_started.xhtml

...and the historic moment has finally arrived. :-) This is the final patch to rename mail_help.xhtml to mailnews_getting_started.xhtml.

Comment 138

[RickieES aka Ricardo Palomares]

Attachment: Renaming mail_help.xhtml to mailnews_getting_started.xhtml (<head> title changed) [Checked in: Comment 148]

...and, of course, I screwed it. :-) Sorry, I forgot to change the <title> contents in the previous patch.

Comment 139

[RickieES aka Ricardo Palomares]

(In reply to comment #36)
> To summarize, these are related topics that have come up in previous comments:
> 
> - suite-toc.rdf has "Using Mail" instead of "Using Mail & Newsgroups" (comment #34)
> - Getting started with News & Blog Feeds needs restructuring (comment #34)
> - Box title for top level boxes should be marked/titled somewhat differently
> than rest of "In this section:" boxes (comment #35)


And these things came up during discussion and now that we're finishing this bug, we should decide if new bugs should be filed for them.

Comment 140

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #139)
> > - suite-toc.rdf has "Using Mail" instead of "Using Mail & Newsgroups" (comment #34)

Repeating from my comment 35:
"Regarding "Using Mail" in the ToC (easy things first!): Let's just change that.
I see no reason why we should keep saying "Mail" here, and if at some point in
time "Mail & Newsgroups" is renamed to "Messenger" or something (bug 513527),
that'll be another bug. BTW: "Getting Started with Mail" is another candidate.
And I don't care that the title will get longer."

So I suggest to file a follow-up bug for these two.

> > - Getting started with News & Blog Feeds needs restructuring (comment #34)

I hope Ian still knows what he was after there in particular, so I recommend he files that follow-up if need be. He already suggested that a follow-up should be filed in comment 39.

> > - Box title for top level boxes should be marked/titled somewhat differently
> > than rest of "In this section:" boxes (comment #35)

Again from my comment 35:
"we might want to file a bug about renaming the box title for top-level boxes to
discriminate them from ones for subsections."
then Ian in comment 37:
"Suggestions for top level boxes - "Topics Covered:" or "In this chapter:""
and me again in comment 38:
"I like the latter as it relates to the difference between chapter and section"

So a follow-up bug about renaming top-level box headings to read "In this chapter:" should be filed. If further discussion about the details should be needed, it can happen there then.

Comment 141

[Stefan [:stefanh]]

(In reply to comment #140)
> (In reply to comment #139)
> > > - suite-toc.rdf has "Using Mail" instead of "Using Mail & Newsgroups" (comment #34)
> 
> Repeating from my comment 35:
> "Regarding "Using Mail" in the ToC (easy things first!): Let's just change
> that.
> I see no reason why we should keep saying "Mail" here, and if at some point in
> time "Mail & Newsgroups" is renamed to "Messenger" or something (bug 513527),
> that'll be another bug. BTW: "Getting Started with Mail" is another candidate.
> And I don't care that the title will get longer."

The idea is to try to make everything visible without forcing people to resize the pane.

Comment 142

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #141)
> The idea is to try to make everything visible without forcing people to resize
> the pane.

Well, I would agree with you, but...

"Using Mail" is short, but "SeaMonkey Keyboard Shortcuts" on the same level is probably already longer than "Using Mail & Newsgroups" would be.

On the same level as "Getting Started with Mail" we have "Importing Mail from Other Programs", "Getting Started With Blogs & News Feeds" and "Mail & Newsgroups Account Settings", all of which are about as long as if we added "& Newsgroups" to "Getting Started with Mail".

But my main point is really that both the section and the subsection are really about the whole module rather than just mail, i.e. it's (primarily) from a content point of view that I say these should be changed.

Anyway, if no-one is totally opposed to the idea we should probably just file that follow-up and take the discussion there.

Comment 143

[Stefan [:stefanh]]

(In reply to comment #142)
> "Using Mail" is short, but "SeaMonkey Keyboard Shortcuts" on the same level is
> probably already longer than "Using Mail & Newsgroups" would be.

Hey, that's funny - like a user wouldn't know that the documented shortcuts are seamonkey's ;-)
 
> Anyway, if no-one is totally opposed to the idea we should probably just file
> that follow-up and take the discussion there.

Sounds like a good idea.

Comment 144

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #143)
> (In reply to comment #142)
> > "Using Mail" is short, but "SeaMonkey Keyboard Shortcuts" on the same level is
> > probably already longer than "Using Mail & Newsgroups" would be.
> 
> Hey, that's funny - like a user wouldn't know that the documented shortcuts are
> seamonkey's ;-)

Feel free to file a bug. No, really!

> > Anyway, if no-one is totally opposed to the idea we should probably just file
> > that follow-up and take the discussion there.
> 
> Sounds like a good idea.

Filed bug 603213.

Comment 145

[RickieES aka Ricardo Palomares]

(In reply to comment #144)
> Filed bug 603213.


OK, I'll take it once the last patch in this bug is checked in. Probably I should be able to prepare already the patch for it, but I'd rather stay in the safe side. :-)

I have a query with SM help open bugs (67 now). I'm not sure how many of them I could work on before SM 2.1 shipping. Part of the problem is that I tend to be very verbose, when I compare myself to help contents added by others. Anyway, I'll talk about this in m.d.a.seamonkey.

Comment 146

[Ian Neal]

(In reply to comment #140)
> (In reply to comment #139)
> > > - Getting started with News & Blog Feeds needs restructuring (comment #34)
> 
> I hope Ian still knows what he was after there in particular, so I recommend he
> files that follow-up if need be. He already suggested that a follow-up should
> be filed in comment 39.
Well it is the only section that has a section within it (Organizing your feeds) and whether it should be that way - opinions?

Comment 147

[Jens Hatlak (:InvisibleSmiley)]

(In reply to comment #146)
> Well it is the only section that has a section within it (Organizing your
> feeds)

Not entirely true: Mail & Newsgroups Account Settings has subsections, too. And some of the other sections have subsections as well, just no "In this section:" boxes (div class="contentBox"). Since "Organizing your feeds" is quite short I'd say let's just remove the box and be done with it; then we'll be in sync with the other sections (they use h3 for the subsections, too). I'll leave it to you whether that needs a new bug or not.

  ^
  |
My 2c

Comment 148

[Ian Neal]

Comment on attachment 482075 [details] [diff] [review]
Renaming mail_help.xhtml to mailnews_getting_started.xhtml (<head> title changed) [Checked in: Comment 148]

http://hg.mozilla.org/comm-central/rev/0e5b3203a874

Comment 149

[Ian Neal]

Fix bustage from missing file rename http://hg.mozilla.org/comm-central/rev/142d4b846ed0

Comment 150

[RickieES aka Ricardo Palomares]

(In reply to comment #149)
> Fix bustage from missing file rename
> http://hg.mozilla.org/comm-central/rev/142d4b846ed0


Sorry again, I wasn't able to provide a right last patch. :-(

Comment 151

[Ian Neal]

(In reply to comment #150)
> (In reply to comment #149)
> > Fix bustage from missing file rename
> > http://hg.mozilla.org/comm-central/rev/142d4b846ed0
> 
> 
> Sorry again, I wasn't able to provide a right last patch. :-(

No problems, thank you for all the work you have put into this bug.

Comment 152

[Stefan [:stefanh]]

Hey Ricardo, feel free resolve this if you consider it fixed :-)

Comment 153

[RickieES aka Ricardo Palomares]

(In reply to comment #152)
> Hey Ricardo, feel free resolve this if you consider it fixed :-)


Sorry, I've been a bit busy this weekend, and I also found a couple of days ago that my local working copy was not in peace with comm-central after pulling and updating, something that didn't happen before after checking in the patchs.

I have just confirmed that the reason was my missing hg rename. That caused hg to interrupt the update of local files, which in turn made hg stat . to show differences in the files.

Everything is OK now, so I'm closing this bug (at last!). :-)