232794 - Help documentation should not hardcode product/brand names

Status: NEW

(SeaMonkey :: Help Documentation, defect)

Description

[Ben Bucksch (:BenB)]

Based on bug 206840.

Vendors may (and actually do) use slightly or completely different product
names, so you should not hardcode the product names, but use placeholders like
&brandShortName; or &browserBrandName; or &mailnewsBrandName; or similar. With
that, you can aso easily switch all docs when mozilla.org changes its names.

Comment 1

[R.J. Keller]

This should be fixed with the XHTML conversion. If I am wrong, reopen.

Comment 2

[Daniel Wang]

help_help.xhtml
:85 <p>Many specialized Mozilla windows and dialog boxes ...
:97 <li>Avoid being too broad with your search: words like "Firebird"
:98 and "Mozilla" could possibly return all of the pages in ...

privacy_help.xhtml
:91 the French version of Mozilla 1.2 on a Windows 2000 computer.</p>

profiles_help.xhtml
:52 <tt> ./mozilla -profilemanager</tt></span></li>
:83 command line: <tt> ./mozilla -profilemanager</tt></span></li>

welcome_help.xhtml

Comment 3

[Ben Bucksch (:BenB)]

We (ManyOne) are planning to fix this. Need prior buy-in from Mozilla module
owners, because the changes (all product names) will be so extensive (but
simple) that it's practically impossible to maintain. Will post proposal later.

Comment 4

[R.J. Keller]

--> me

Going to talk to neil about this on IRC (hopefully I can catch him) and then
we'll get this fixed.

Comment 5

[Ben Bucksch (:BenB)]

Attachment: Branding placeholder proposal - HTML

Here's the promised proposal. It tries to over all the cases we need to cover
and know about (mozilla.org, Netscape, Beonex, ManyOne) as well as most other
perceivable ones.

Comment 6

[Ben Bucksch (:BenB)]

Attachment: Branding placeholder proposal - CSV

Comment 7

[Ben Bucksch (:BenB)]

The proposal is not perfect, though: E.g., if the browser doesn't have its own
name, it's just called "<suitename> browser", what do we do with capitalization,
e.g. "The ManyOne browser comes with..." and "Open the ManyOne browser...". Or
shortname: "The browser comes with...", "Open the browser..." and just "Browser"
(Preferences pane name).
FYi, for Beonex, the suitename is "Beonex Communcator", while the apps are
called "Beonex Navigator", "Beonex Mailnews" etc.

Comment 8

[R.J. Keller]

Attachment: Patch - using BenB's proposal

Comment 9

[Ben Bucksch (:BenB)]

Awesome! Thanks!

I guess we should use placeholders starting with lowercase for consistency (I
know that my proposals use upper case)? I assume it's just a global search/replace.

 <!ENTITY  vendorShortName       "Mozilla">
+<!ENTITY  OrgShortName          "&brandShortName;">

I didn't realize that we already have a vendorShortName, we should probably just
use that (and vendorLongName) instead of orgShort/LongName, the intention was
the same.

+  ... lower-left corner of any &brandShortName; window.</li>

I'd like to deprecate brandShortName and prefer to replaced it with one of the
more specific placeholders, in this case suiteShortName. You could make a
comment to that effect in brand.dtd as well.

BTW: If we are not allowed to change brand.dtd, it's fine with me for now to
have a dtd file specific to the help files, and include that in all the help 
files in addition to brand.dtd.

+<!ENTITY  BrowserLongName       "&brandShortName; &BrowserShortName;">

Same here, just orgShortName

-  <li>Use the Navigator browser
+  <li>Use the &BrowserShortName; browser

This is used a lot. We should find something better for this, this may not make
sense in all cases (e.g. when the browser doesn't hacve a name on its own,
&BrowserShortName; = just "browser"). I'd just replace the whole "the Navigator
browser" with "&BrowserShortName;", ending up with e.g. "Use Navigator to open ...".

+  ... For example, the domain name for the &OrgShortName;
   website is <tt>www.mozilla.org</tt>.

That won't work :)

+ For example, confirm that you can successfully view the page
      <tt>http://www.mozilla.org</tt>.</li>

&vendorWebsiteURL;? We probably have that somewhere already, actually.

   (<img alt="cookie notification icon"
-  src="chrome://cookie/content/taskbar-cookie.gif"></img>)
+  src="chrome://cookie/content/taskbar-cookie.gif">)

I think that's a bug, XHTML requires proper closure.


I haven't found any problem, but please make sure not to change technical
instances, e.g. commandline options.

Comment 10

[R.J. Keller]

Attachment: Patch #2

(In reply to comment #9)
> I guess we should use placeholders starting with lowercase for consistency (I

> know that my proposals use upper case)? I assume it's just a global
search/replace.

sure

> 
>  <!ENTITY  vendorShortName	   "Mozilla">
> +<!ENTITY  OrgShortName	   "&brandShortName;">
> 
> I didn't realize that we already have a vendorShortName, we should probably
just
> use that (and vendorLongName) instead of orgShort/LongName, the intention was

> the same.

OK, removed it. Actually, I didn't catch it myself :).

> 
> +  ... lower-left corner of any &brandShortName; window.</li>
> 
> I'd like to deprecate brandShortName and prefer to replaced it with one of
the
> more specific placeholders, in this case suiteShortName. You could make a
> comment to that effect in brand.dtd as well.
> 
> BTW: If we are not allowed to change brand.dtd, it's fine with me for now to
> have a dtd file specific to the help files, and include that in all the help 

> files in addition to brand.dtd.

Neil said it was fine over IRC, and he's owner of XP Apps now.

> 
> +<!ENTITY  BrowserLongName	   "&brandShortName; &BrowserShortName;">
> 
> Same here, just orgShortName

vendorShortName, yeah :).

> 
> -  <li>Use the Navigator browser
> +  <li>Use the &BrowserShortName; browser
> 
> This is used a lot. We should find something better for this, this may not
make
> sense in all cases (e.g. when the browser doesn't hacve a name on its own,
> &BrowserShortName; = just "browser"). I'd just replace the whole "the
Navigator
> browser" with "&BrowserShortName;", ending up with e.g. "Use Navigator to
open ...".

For what reason? The point here is branding. I don't see a branding advantage
here. Just less text.

> 
> +  ... For example, the domain name for the &OrgShortName;
>    website is <tt>www.mozilla.org</tt>.
> 
> That won't work :)

yeah, I was thinking of that too, but wasn't really sure what to put. Maybe a
better idea might be to put a totally separate Web site that isn't related to
Mozilla at all (google.com?). For now, tell me if the patch is OK other than
this issue.

I put in a workaround that probably won't work for most people. I'd say lets
move that to another bug or ask Neil if adding a vendor URL is OK.

> 
> + For example, confirm that you can successfully view the page
>	<tt>http://www.mozilla.org</tt>.</li>
> 
> &vendorWebsiteURL;? We probably have that somewhere already, actually.

Not that I've seen (other than release notes URL). Could be wrong though. Tell
me if there is one.

> 
>    (<img alt="cookie notification icon"
> -  src="chrome://cookie/content/taskbar-cookie.gif"></img>)
> +  src="chrome://cookie/content/taskbar-cookie.gif">)
> 
> I think that's a bug, XHTML requires proper closure.

hmm. strange that it didn't give me any parsing errors. I'll add the / to the
end.

> 
> 
> I haven't found any problem, but please make sure not to change technical
> instances, e.g. commandline options.

I didn't do a find and replace. I replaced each one manually to make sure it'd
work in that instance. IMO, commandline options shouldn't be in Help.

Comment 11

[Ben Bucksch (:BenB)]

+  website is <tt>www.&vendorShortName;.org</tt>.

huh? That won't work for sure. Unless we have a vendorWebsiteURL, you should
just use Mozilla / www.mozilla.org or Yahoo / www.yahoo.org as examples.

I'll pass on the rest to Jerome, ManyOne's doc writer. Thanks!

Comment 12

[Ben Bucksch (:BenB)]

Sorry, I missed your comment. Responding:

> > addition to brand.dtd.
> Neil said it was fine over IRC, and he's owner of XP Apps now.

Great! :)

[No "The Navigator browser"]
> For what reason? The point here is branding. I don't see a branding
> advantage here. Just less text.

See comment 7. Currently, the ManyOne browser is called just that: "the ManyOne
browser". How would I reflect that? Probably vendor = "ManyOne", browserName =
"browser" (ignoring caps for now). With the current text, I would end up with
"The browser browser".

> vendor URL

I found it: it's "vendorURL" in .../global/.../region.dtd. So, you can use
vendorShortName with vendorURL, they *should* fit.

> strange that it didn't give me any parsing errors.

You mean Mozilla? Maybe because it is forgiving in favor of HTML compat. Use a
validating XML parser to check.

> I replaced each one manually to make sure it'd work in that instance.

wow. Thanks!

Comment 13

[Jerome Bullert]

> [No "The Navigator browser"]
>>>This is used a lot. We should find something better for this, this may
>>>not make sense in all cases (e.g. when the browser doesn't have a name
>>> on its own, &BrowserShortName; = just "browser"). I'd just replace the
>>>whole "the Navigator browser" with "&BrowserShortName;", ending up with
>>>e.g. "Use Navigator to open ...".
>  
>>For what reason? The point here is branding. I don't see a branding
>>advantage here. Just less text.> 
> 
> See comment 7. Currently, the ManyOne browser is called just that: "the ManyOne
> browser". How would I reflect that? Probably vendor = "ManyOne", browserName =
> "browser" (ignoring caps for now). With the current text, I would end up with
> "The browser browser".
>

Seems like trying to deal with the "The" instances effectively would require a
"the" version of every placeholder. For example, a "thebrowserName" placeholder
in addition to a "browserName" placeholder.

Is it possible to set placeholders to a null value. For example, in the scenario
above, if you set browserName = "", from the string 'The &browserName browser',
you end up with "The browser".

Assuming that the spaces after each placeholder are normal spaces, and not
non-breaking spaces, only one space should appear when rendered. Correct?

Comment 14

[Ben Bucksch (:BenB)]

> a "thebrowserName" placeholder

Apart from being nasty, it would not be localizable. E.g. German has one article
per gender. And you probably have other articles.

> Is it possible to set placeholders to a null value.

Yes, but you have places where you need the placeholder alone, e.g. the pref
panel name.

Comment 15

[R.J. Keller]

ben: so what do you propose as the solution? I'd say lets just change the
phrasing of the help text to get around this issue. This doesn't happen with
Mail/News or Composer (unless I'm mistaken).

Comment 16

[R.J. Keller]

Attachment: Patch #3

OK, lets get this proposal in now and do the rephrasing later. This is huge
progress for branders already (IMO) and this is blocking too many changes.
Rephrasing the content can always come later. This is the big stuff.

Comment 17

[Ben Bucksch (:BenB)]

I agree.

Comment 18

[Jerome Bullert]

Most of the patch looks good. I only noticed a few issues:

1. We still need to address some instances where "Mail" or "News"
are referenced separately (not as "Mail & Newsgroups"):

For instance, I noticed some lines while reviewing the patch. In
each of the paragraphs below, the string "&suiteShortName; Mail"
should be replaced with either:
 "&suiteShortName; &mailShortName;"
or
 "&mailLongName;".

Note that these are only the instances that I noticed within the patch.
There could be other such references within the rest of the Help files.

Examples in file: extensions/help/resources/locale/en-US/mail_help.xhtml
--- 
...
+<li><strong>Use &suiteShortName; Mail as the default mail
+application</strong>: Select &mailnewsLongName; as the
 default mail application for Windows and from within other
 applications such as Microsoft Word.</li>
...
+<p>Once &suiteShortName; Mail has been started, the new message alert will
 continue to work even after you close the Mail window (as long as
+another &suiteShortName; application is running).</p>
 </li>
...
+<p>Once &suiteShortName; Mail has been started, the new message alert will
 continue to work even after you close the Mail window (as long as
+another &suiteShortName; application is running).</p>
...
+<p>Once &suiteShortName; Mail has been started, the new messages sound will
 continue to work even after you close the Mail window (as long as
+another &suiteShortName; application is running).</p>
 </li>
 </ul>
---

2. I also noticed some grammar, typo, and similar issues. (Might as well fix
them when we notice them.) The ones I noticed in the patch are:

In the file: extensions/help/resources/locale/en-US/nav_help.xhtml
--- 
+    <p><strong>Note</strong>: You will have to need to restart &suiteShortName;
       after you change to another content pack.</p>

The "have to " should be removed, so that it reads "You will need to restart..."

In the file: extensions/help/resources/locale/en-US/cs_nav_prefs_navigator.xhtml
---
            <li><strong>When encountered</strong>: Displays what kind of action
+	    that will be taken when &suiteShortName; encounter the selected
 	    file type.</li>

--It should be "encounters" as in "...when Mozilla encounters the selected..."
...

   <li><strong>Domain Guessing</strong>: Select this if you want
+    &suiteShortName; to automatically add <tt>www.</tt> and <tt>com.</tt> to a
     web page location that can&apos;t be found. For more detailed information

--Should be ".com", not "com."

3. I noticed one reference to a branded internet connection. This line will not
be applicable for any Mozilla users and for most other vendor's users. Even for
ManyOne, which offers ISP services, many users will not be subscribing to the
ISP service. ("Bring Your Own Access" users) As a result, this line should
simply read: "...your internet connection..."

In the file: extensions/help/resources/locale/en-US/composer_help.xhtml
 
+<p><strong>Error Description:</strong> You are attempting to publish, but your
&suiteShortName;
   Internet connection is currently in the "offline" state. Your Internet
connection must
   be in the "online" state (connected to the Internet) in order to publish your
pages.</p>

The &suiteShortName; placeholder should be removed and this should simply read:
 "...your internet connection..."

4. For the "the" instances, I think the only workable solutions are:

A. Change the phrasing in the text as RJ suggests in comment 15 above.
or
B. By policy, we make sure that, if there is no browser name, we set both
browserShortName and browserLongName to match the suite name. If there's no
suite name, we set them all to match the vender name. This should work in most
situations.

In our case, if we don't name the browser or the suite, all of these
placeholders, both long and short, would be set to "ManyOne".

This would cover all of the following phrases:
-"...the ManyOne Edit menu..." (suiteShortName)
-"...of any ManyOne window..." (suiteShortName)
-"...the ManyOne browser..." (browserShortName)

The only situations where this doesn't work are:
A. References to the &browserShortName category in the Preferences. If the
browser is not specifically branded, most likely the category name will be
"browser".

Examples: 
In the file: extensions/help/resources/locale/en-US/customize_help.xhtml
---
   <li>Open the <span class="mac">&brandShortName;</span>
     <span class="noMac">Edit</span> menu and choose Preferences.</li>
+  <li>Click the &browserShortName; category.</li>
   <li>In the Home page section, perform one of the following:

and

B. Sentences where both the Suite name and Browser name are mentioned.

Examples:
In the file: extensions/help/resources/locale/en-US/cs_nav_prefs_appearance.xhtml
---
 <p>The sections listed below describe the preferences panels related to
+  &browserShortName;, the browser component of &suiteShortName;. To see the
   preference panels, follow these steps:</p>

In the file: extensions/help/resources/locale/en-US/cs_nav_prefs_navigator.xhtml
---
+<title>&suiteShortName; &browserShortName; Preferences Help</title>
(Technically, these two placeholders could be replaced with &browserLongName;)

In the file: extensions/help/resources/locale/en-US/customize_help.xhtml
---
 <p>This section describes the customizable aspects of &brandShortName;&apos;s
+  browser component, &browserShortName;.</p>

In the file: extensions/help/resources/locale/en-US/glossary.xhtml
---
 <dt id="component_bar">Component Bar</dt><dd>The toolbar located
+  at the bottom left of any &suiteShortName; window. The Component Bar allows
+  you to switch between &suiteShortName; components by clicking icons for
+  &browserShortName;, &mailnewsShortName;, IRC Chat, and so on.</dd>

In the file: extensions/help/resources/locale/en-US/nav_help.xhtml
--- 
+<p>Welcome to &suiteShortName;! One of the most popular ways people use
+  &suiteShortName; is to browse the Web. &browserShortName;, the &suiteShortName;
   component that lets you visit web pages, offers many ways to visit web pages
   and search the Web.</p>
...
 
+<p>When you start &suiteShortName;, you see &browserShortName;, your browser.
   A &quot;What&apos;s New&quot; page appears automatically in the browser
+  window when you first launch &suiteShortName;.</p>

Comment 19

[Ben Bucksch (:BenB)]

Thanks, Jerome, for looking over it and finding problems.

Others: Note that "+"/"-" in his comments seems to not match the usage in diffs.

You correctly point out some typos, but may they could go into another patch.

> this should simply read: "...your internet connection..."

Correct, but "Internet" is capitalized, it's a name of a single entity.

Comment 20

[Ben Bucksch (:BenB)]

Comment on attachment 163089 [details] [diff] [review]
Patch #3

rubberstamp r=BenB, if you fix Jerome's comments 1. and 3.. Note that I did not
read over most of the patch nor did I run it.

Comment 21

[Stefan [:stefanh]]

I'll fix the errors in 2) while I'm doing bug 111484.

Comment 22

[R.J. Keller]

Neil, any status? only the brand.dtd info should need super-review. The rest
should be fine with just r= (assuming the process didn't change from when I was
owner). I'm afraid that my patch has become obsolete with stefan's changes and
would like to get it in before I end up with more collision problems.

Comment 23

[Ben Bucksch (:BenB)]

Neil, could you review, please? The patch is extremely vulnerable to bitrott due
to its size.

Comment 24

[[e-mail]]

Comment on attachment 163089 [details] [diff] [review]
Patch #3

Please explain the following changes:

"www.mozilla.org" changed to "http://www.mozilla.org/" (tricky one!)

"General Mail & Newsgroups Shortcuts" changed to "General Mail Shortcuts"

"Start Mail & Newsgroups" changed to "Start Mail"

"Mail & Newsgroups" changed to "Mail and News"

Comment 25

[R.J. Keller]

(In reply to comment #24)
> (From update of attachment 163089 [details] [diff] [review] [edit])
> Please explain the following changes:
> 
> "www.mozilla.org" changed to "http://www.mozilla.org/" (tricky one!)
> 
> "General Mail & Newsgroups Shortcuts" changed to "General Mail Shortcuts"
> 
> "Start Mail & Newsgroups" changed to "Start Mail"
> 
> "Mail & Newsgroups" changed to "Mail and News"
> 

Neil, I don't see those changes. General Mail & Newsgroups Shortcuts was changed
to &mailShortName; which should output Mail & Newsgroups (the same thing as before).

Comment 26

[[e-mail]]

Comment on attachment 163089 [details] [diff] [review]
Patch #3

>-  website is <tt>www.mozilla.org</tt>. If the domain name in a server's certificate
>+  website is <tt>&vendorURL;</tt>. If the domain name in a server's certificate
>   doesn't match the actual domain name of the website, it may be a sign that someone is
&vendorURL; is not "www.mozilla.org"

>-    <li><a href="#general_mail_and_newsgroups_shortcuts">General Mail &amp; Newsgroups
>+    <li><a href="#general_mail_and_newsgroups_shortcuts">General &mailnewsShortName;
This one (of many) is incorrect because mailnewsShortName is "Mail and News"
not "Mail & Newsgroups".

>-<h2 id="general_mail_and_newsgroups_shortcuts">General Mail &amp; Newsgroups
>+<h2 id="general_mail_and_newsgroups_shortcuts">General &mailShortName; Shortcuts</h2>
And mailShortName is definitely not "Mail & Newsgroups".

>-    <td>Start Mail &amp; Newsgroups</td>
>+    <td>Start &mailShortName;</td>
Same again.

Comment 27

[R.J. Keller]

(In reply to comment #26)
> &vendorURL; is not "www.mozilla.org"

The goal of that is to create a URL to "somewhere". We didn't want mozilla.org
hard-coded because then it'd be a branding problem and I figured that &vendorURL
would feed me a URL and that sounded good enough. I could just hardcode
www.mozilla.org if you want.

> This one (of many) is incorrect because mailnewsShortName is "Mail and News"
> not "Mail & Newsgroups".

The issue I'm seeing with this is that Mail and News are (and tell me if I'm
wrong) technically two different applications. Mozilla Mail and Mozilla News. It
sounds to me like Mail & News would be more accurate than Mail & Newsgroups.
Tell me if I'm wrong.

Comment 28

[[e-mail]]

(In reply to comment #27)
>(In reply to comment #26)
>>&vendorURL; is not "www.mozilla.org"
>The goal of that is to create a URL to "somewhere".
Lacking context, but the goal here should be to create a hostname, not a URL.

>It sounds to me like Mail & News would be more accurate than Mail & Newsgroups.
mscott quickly vetoed the last attempted rebrand (to "Messenger").

Comment 29

[R.J. Keller]

(In reply to comment #28)
> Lacking context, but the goal here should be to create a hostname, not a URL.

got it. So I'll just hardcode mozilla.org then.

> mscott quickly vetoed the last attempted rebrand (to "Messenger").

So is it Mozilla News or Mozilla Newsgroups?

Comment 30

[[e-mail]]

Mostly you shouldn't need to distinguish between the apps, so you would use
"Mozilla Mail & Newsgroups", however in the few cases (e.g. set as default app
prefs) that you do distinguish, use "Mozilla Mail" and "Mozilla News".

Comment 31

[R.J. Keller]

Attachment: Patch with neils comments

Neil, how does this look?

Comment 32

[[e-mail]]

OK, so taking my points in order of comment 26:

1. The text now says "The domain name of the <vendor> website is
www.mozilla.org"; as you don't have an entity for just the website domain name I
feel you should explicitly specify a well known website and domain name
(although not necessarily Mozilla).

2. You changed the mailnewsLongName although I was referring to
mailnewsShortName - was this an oversight?

3/4 was not addressed either way i.e. no change or explanation.

Comment 33

[Ben Bucksch (:BenB)]

> Mail and News are (and tell me if I'm wrong)
> technically two different applications.

(FYI, they are not. news is just another storage/server method, similar to POP
and IMAP, with some tweaks. Netscape marketing came up with that distinction.)

Comment 34

[Ben Bucksch (:BenB)]

> +<!ENTITY  mailnewsShortName     "Mail and News">

That needs to be "Mail and Newsgroups". Would take care of Neil's comments 3/4
(as far as I understand) and match current texts.

> +<li>Under the &mailnewsShortName; category, click Composition.
>  (If no subcategories are visible, double-click Mail &amp;
>  Newsgroups to expand the list.)</li>

The latter should be replaced, too.

Comment 35

[Ian Neal]

help-toc.rdf probably needs patching too

+<!ENTITY  mailnewsShortName     "Mail and News">
+<!ENTITY  mailnewsLongName      "&vendorShortName; Mail and Newsgroups">

probably should be
+<!ENTITY  mailnewsShortName     "Mail &amp; Newsgroups">
+<!ENTITY  mailnewsLongName      "&vendorShortName; &mailnewsShortName;">

Comment 36

[Ben Bucksch (:BenB)]

rj, can you attach a new patch that neil can give his r= to? (See last comments)

Comment 37

[Ian Neal]

We need this for 1.0a

P.S. The current patch is very bitrotted

Comment 38

[Ian Neal]

Sorry for the spam but on discussions, this a nice to have at the moment rather
than a need to have for 1.0a so removing the blocking+

Comment 39

[[e-mail]]

And iirc you shouldn't use mailShortName in the actual help files.

Comment 40

[Jerome Bullert]

Any progress/update on this?

Comment 41

[R.J. Keller]

(In reply to comment #40)
> Any progress/update on this?

My current plan is to attach individual patches for each help file because the
patches keep bit-rotting too fast. I got finals in school and they should end by
Friday of next week. Hopefully then I'll get some time to work on this more and
get a bit caught up.

Comment 42

[Jerome Bullert]

Are we expecting any progress on this in the near future?

Thanks,
-Jerome

Comment 43

[R.J. Keller]

(In reply to comment #42)
> Are we expecting any progress on this in the near future?
> 
> Thanks,
> -Jerome
> 

I have been busy lately so I probably won't get to them anytime soon.

If you'd like to contribute a patch for this bug, building off of what I already
did, you're welcome to.

Comment 44

[Ben Bucksch (:BenB)]

> building off of what I already did, you're welcome to.

RJ, we need this for a product launch end of the month. The last patch doesn't
even apply against 1.7.3, it's completely rotten. If you don't have time, can
you please give me the script and any steps that you used to generate this?

Comment 45

[Giacomo Magnini]

If needed, I can work on this: but do you need a patch for branch or trunk?
AFAIK doc changes on branch are usually not accepted...

Comment 46

[R.J. Keller]

(In reply to comment #44)
> RJ, we need this for a product launch end of the month. The last patch doesn't
> even apply against 1.7.3, it's completely rotten. If you don't have time, can
> you please give me the script and any steps that you used to generate this?

Hi Ben,

I'm busy working on projects that I'm paid to do so I probably wouldn't be able
to get to this by the end of the month.

As for scripts, I did a simple Find and Replace but analyzed the results
carefully to make sure each situation was appropriate. It took awhile but it
ensured accuracy.

If anyone wants the bug, feel free to reassign.

Comment 47

[Ben Bucksch (:BenB)]

We need a patch for trunk (and maybe 1.8 branch?) in any case.

ManyOne probably needs it for the 1.7 branch as well, depending on other decisions.

Giacomo, f you want to work on it, you're most welcome. Please touch base with
me to ensure we're on the same page.

Comment 48

[Giacomo Magnini]

Attachment: Test diff for discussion

Ok, just a small test patch to see if I got everything in order, and to collect
feedback. Added a vendorHostName to replace instances of "www.mozilla.org"
where needed. I still don't understand if the distinction between Mail and News
is still needed, but I left it as is. Addressed Neil comment about "Mail &
Newsgroups".
Fire your opinions! :)

Comment 49

[Giacomo Magnini]

Attachment: Patch covering all files for a quick test

Comment 50

[Ben Bucksch (:BenB)]

-> giacomo per his request

Comment 51

[Giacomo Magnini]

Attachment: Another round

Fixed missed entries in certs_prefs_help, and the totally overlooked
shortcuts*.xhtml...

Comment 52

[Giacomo Magnini]

Attachment: Missed some brandShortName in shortcuts.xhtml. AFAICS, this should be it.

Comment 53

[Ian Neal]

I think you do need to split this up into smaller patches with more context to
the diff. The only thing I've spotted so far is:
+<!ENTITY  mailnewsShortName     "Mail &amp; Newsgroups">
+<!ENTITY  mailnewsLongName      "&vendorShortName; Mail &amp; Newsgroups">
+<!ENTITY  mailShortName         "Mail">
+<!ENTITY  mailLongName          "&vendorShortName; &mailShortName;">

mailnewsLongName should be "&vendorShortName; &mailnewsShortName;" and why 2
spaces between ENTITY and the entity name?

Comment 54

[Giacomo Magnini]

Attachment: brand.dtd and *.rdf files

Comment 55

[Giacomo Magnini]

Attachment: Help files part 1

p*.xhtml, s*.html, u*.xhtml, validation_help.xhtml and welcome_help.xhtml

Comment 56

[Giacomo Magnini]

Attachment: Help files part 2

nav_help.xhtml

Comment 57

[Giacomo Magnini]

Attachment: brand.dtd and (more) .rdf files

Comment 58

[Giacomo Magnini]

Attachment: Help files part 1.1 (added brand to shortcuts-composer, mailnews and navigator)

Comment 59

[Giacomo Magnini]

Attachment: brand.dtd and (more) .rdf files 1.1: after IanN addition to help-toc.rdf

Minimum impact: will affect only rdf files for a start and add new branding
names.

Comment 60

[Ian Neal]

(In reply to comment #59)
> Created an attachment (id=198004) [edit]
> brand.dtd and (more) .rdf files 1.1: after IanN addition to help-toc.rdf
> 
> Minimum impact: will affect only rdf files for a start and add new branding
> names.
I see you an entry for Sidebar in brand.dtd but you do not seem to have done any
substitutions for it, did you mean not to?

Comment 61

[Giacomo Magnini]

Attachment: Thanks Ian for spotting that!

There were also some "sidebar" entries, which I converted to using entity. Is
it ok?

Comment 62

[Ian Neal]

Comment on attachment 198111 [details] [diff] [review]
Thanks Ian for spotting that!

r=me

Comment 63

[[e-mail]]

Comment on attachment 198111 [details] [diff] [review]
Thanks Ian for spotting that!

>      <rdf:li>
>        <rdf:Description ID="Sidebar"
>-         nc:name="Sidebar"
>+         nc:name="&sidebarName;"
> 	 nc:link="customize_help.xhtml#what_is_sidebar"/>
>      </rdf:li>
I almost plussed this, but then had a brainwave that the patch unfortunately
doesn't have enough context to show, but this entry for example, for Sidebar,
is normally indexed under S. Now if you brand it e.g. to My Sidebar, it now
needs to be indexed under M...

Comment 64

[Robert Kaiser]

Is there any real reason why we need &suiteShortName;?
We're using &brandShortName; as the suite brand name all over the product, and
I'm quite opposed to using a different entity just in help.
Especially in the light of some UI we share with other projects (in mailnews or
toolkit) or that should be easily portable, there's even more reason for
&suiteShortName; being quite unhelpful, as it should be the same as
&brandShortName; in all the scenarios I can reasonably think of (same with
FullName).

Additionally, we should follow the standard that the normal brand entities give
us and use xxxFullName instead of xxxLongName.

Comment 65

[Giacomo Magnini]

Use of vendorShortName is totally bogus across all of the products: FX sets it
to "Mozilla", TB to "Mozilla Thunderbird" and "Mail/News Client", Calendar/SB to
"Mozilla" (even if they *can't* use the name Mozilla, as they have the same
status of "project" just like SM does; but this is another story...).
In profile/, editor/, mail/ and mailnews/ it is used to reference the homepage
of the product, which isn't necessarily the homepage of the vendor (that is,
it'd been much better to use brandShortName instead).
If/when a conclusion has been reached, ping me: I'm not going to mantain >500K
of patches with moving targets.

Comment 66

[Ian Neal]

Until we have some sort of script that automagically generate the index files I think this bug cannot be resolved.

Comment 67

[RickieES aka Ricardo Palomares]

Attachment: "Mozilla" appearances in help files for SeaMonkey in comm-central as of today

I've overviewed the bug and, for what I understand, we should replace "Mozilla" and "SeaMonkey" words for &vendorShortName; and &brandShortName;. Am I wrong?

There are three appearances for "SeaMonkey" and two for "Firefox" ("Thunderbird" is not in help).

Comment 68

[[e-mail]]

Comment on attachment 487104 [details]
"Mozilla" appearances in help files for SeaMonkey in comm-central as of today

>developer_tools.xhtml:49:      <li>Creating Applications with Mozilla - Appendix B3:
This one is the title of a book, so it doesn't need to be changed. As far as I can tell, the other uses of Mozilla refer to the Mozilla Foundation, and so again, don't need to be changed.

The reference to Firefox is correct since it's specific to the spoofing of the User-Agent header to include the equivalent Firefox version.

The references to SeaMonkey in the help are a little tricker, and I'm not sure offhand what to suggest there.