Closed Bug 373457 Opened 13 years ago Closed 10 years ago

Document add-ons/extensions manager

Categories

(SeaMonkey :: Help Documentation, defect)

defect
Not set

Tracking

(Not tracked)

RESOLVED FIXED
seamonkey2.0

People

(Reporter: stefanh, Assigned: rpmdisguise-nave)

References

Details

(Keywords: fixed-seamonkey2.0, Whiteboard: [l10n-impact-help])

Attachments

(2 files, 8 obsolete files)

39.07 KB, patch
stefanh
: review+
Details | Diff | Splinter Review
1.20 KB, patch
iann_bugzilla
: review+
Details | Diff | Splinter Review
Suiterunner will ship with toolkits add-ons manager. The manager needs to be described in our help docs.
please delele all bugs
(In reply to comment #1)
> please delele all bugs
> 

What do you mean?
Blocks: 423281
Version: unspecified → Trunk
This looks like it should be added as an entry to customize_hep.xhtml table of contents, and probably be written in a separate document (addons_manager_help.xhtml, for instance). Does this sound reasonable?
(In reply to comment #3)
> This looks like it should be added as an entry to customize_hep.xhtml table of
> contents, and probably be written in a separate document
> (addons_manager_help.xhtml, for instance). Does this sound reasonable?

I also think that customize_help.xhtml is the right place to start (not necessarily the only one, though). However, since its table of contents links to anchors on the same page, I guess you should do the same for the Add-ons Manager instead of creating a new page, at least as far as linking from the TOC is concerned.
(In reply to comment #4)
> I also think that customize_help.xhtml is the right place to start (not
> necessarily the only one, though). However, since its table of contents links
> to anchors on the same page,


Not all entries in ToC are anchors; browser preferences and advanced preferences link to cs_nav_prefs_navigator.xhtml and cs_nav_prefs_advanced.xhtml, for instance. :-)



> I guess you should do the same for the Add-ons
> Manager instead of creating a new page, at least as far as linking from the
> TOC is concerned.


I have still not taken the bug myself. ;-) But I'm going to think about it. The reason to propose a separated page is because I feel this could end being a quite large addition, don't you think so?
(In reply to comment #5)
> (In reply to comment #4)
> > I also think that customize_help.xhtml is the right place to start (not
> > necessarily the only one, though). However, since its table of contents links
> > to anchors on the same page,
> 
> Not all entries in ToC are anchors; browser preferences and advanced
> preferences link to cs_nav_prefs_navigator.xhtml and
> cs_nav_prefs_advanced.xhtml, for instance. :-)

You are right, but that's bad practice if you ask me. The box caption reads "In this section:" but the last three links point to other sections instead of subsections.

I think it would be better to do it like on Using Privacy Features, i.e. introduce a new section starting with the current box and above that insert a new box with a caption like "Customizing topics:" containing the last three links of the old box and above that one link pointing to the new section below. After that change adding yet another link to another section about the Add-ons Manager would not be a problem anymore.

> The reason to propose a separated page is because I feel this could end
> being a quite large addition, don't you think so?

Actually I agree, I was only concerned about the mixture of in-page and external anchors but since those already exists it's now only a matter of how to improve the situation (see above).

The above is just my POV and I'm not a reviewer. Since Stefan will be away for quite some time you may want to ask IanN what he thinks.
(In reply to comment #6)
> The above is just my POV and I'm not a reviewer. Since Stefan will be away for
> quite some time you may want to ask IanN what he thinks.







    *  What is an add-on
    * Types of add-ons
    * Accessing the Add-on Manager
    * The Get add-ons tab
    * The Extensions tab
    * The Themes tab
    * The Languages tab
    * The Plugins tab
(In reply to comment #7)
> (In reply to comment #6)
> > The above is just my POV and I'm not a reviewer. Since Stefan will be away for
> > quite some time you may want to ask IanN what he thinks.


Damn it, I didn't intend to add this half-done comment. :-) Well, IanN has been added.

Regardless of whether the content goes into customize_help.xhtml or in a separate "using_the_addon_manager.xhtml", this is my proposal of ToC for the add-on manager section:

>     * What is an add-on
>     * Types of add-ons
>     * Accessing the Add-on Manager
>     * The Get add-ons tab
>     * The Extensions tab
>     * The Themes tab
>     * The Languages tab
>     * The Plugins tab


Any comments?

Based on experience with bug 286975, I'd like to be sure the feature is frozen so it won't change while I'm writing the docs. I guess it will be that way, since it is part of toolkit shared components and shared with Firefox 3.5.x, but it would be nice a confirmation on it. :-)

TIA
I think it fits quite neatly into customize_help.xhtml and that looks like a good starting point for a ToC
(In reply to comment #8)
> >     * What is an add-on
> >     * Types of add-ons

I'd just have one "About Add-ons" instead of those two, containing an introduction, talking about extensions and themes.

> >     * Accessing the Add-on Manager

Is there another way besides the Tools menu? If not adding a paragraph to the first section might be enough.

> >     * The Get add-ons tab
> >     * The Extensions tab
> >     * The Themes tab
> >     * The Languages tab
> >     * The Plugins tab

These are not really tabs, especially with the Modern theme where they are buttons now (you'll need a recent nightly to check that). I'd just refer to them as sections and simply put their names as Help subsections (BTW mind case, e.g. "Get Add-ons").

> Based on experience with bug 286975, I'd like to be sure the feature is frozen
> so it won't change while I'm writing the docs. I guess it will be that way,
> since it is part of toolkit shared components and shared with Firefox 3.5.x,
> but it would be nice a confirmation on it. :-)

The basic functionality is probably frozen (SM 2.0 feature freeze is next Tuesday) but there may still be theme changes to come (I don't know of any, though).
This bug is open but targeted for seamonkey2.0a1, which has been released a long time ago. Please set the target milestone to an appropriate value, "---" if it has no specific target.
Target Milestone: seamonkey2.0a1 → seamonkey2.0
(In reply to comment #10)
> (In reply to comment #8)
> > >     * What is an add-on
> > >     * Types of add-ons
> 
> I'd just have one "About Add-ons" instead of those two, containing an
> introduction, talking about extensions and themes.


Agreed, I've merged those into "About Add-ons".


> > >     * Accessing the Add-on Manager
> 
> Is there another way besides the Tools menu? If not adding a paragraph to the
> first section might be enough.


Actually, there are two ways: the Tools menu, and the Advanced -> Software updates preference panel, which includes a button to launch the add-on manager.

But I'm thinking that there are three ways to install add-ons (add-on manager, clicking on a XPI link in an authorized website, and opening an XPI file from the local filesystem), and that it should be documented. So, I may change the "Accessing the add-on manager" section for something like "Installing and managing add-ons".


> > >     * The Get add-ons tab
> > >     * The Extensions tab
> > >     * The Themes tab
> > >     * The Languages tab
> > >     * The Plugins tab
> 
> These are not really tabs, especially with the Modern theme where they are
> buttons now (you'll need a recent nightly to check that). I'd just refer to
> them as sections and simply put their names as Help subsections (BTW mind case,
> e.g. "Get Add-ons").


I don't like too much using just "Get Add-ons". How would it sound "The Get Add-ons Panel"?
(In reply to comment #12)
> (...) So, I may change the
> "Accessing the add-on manager" section for something like "Installing and
> managing add-ons".

Good idea. Note: Use title case for headings (but "Add-ons", not "Add-Ons").

> I don't like too much using just "Get Add-ons". How would it sound "The Get
> Add-ons Panel"?

Acceptable to me. I'm not a reviewer, though.
I've noticed that there is actually no information in help contents about what are add-ons, and since I'm covering that in what I'm writing, I'm thinking of changing the title of the section/page from "Using the Add-on Manager" to "Using Add-ons". This also changes the ToC, which would change to just:

* About Add-ons
* Installing and managing Add-ons

with the second point having a subToC:

* Installing Add-ons
* Installing Add-ons globally
* The Get Add-ons panel
* The Extensions panel
* The Themes panel
* The Languages panel
* The Plugins panel
* Configuring Add-ons
* Removing Add-ons

Inside "Installing Add-ons" would be a subheading (not linked in the ToC) explaining the two ways to access the Add-on Manager.

I know the second section, "Installing Add-ons globally", may raise some controversy, since it won't be available after 2.0 series, but I find it pretty interesting for the kind of users SM is targeted to.

BTW, is this correct/polite if I assign this bug to myself? :-)
(In reply to comment #14)
> I'm thinking of
> changing the title of the section/page from "Using the Add-on Manager" to
> "Using Add-ons".

Maybe even just "Add-ons".

> I know the second section, "Installing Add-ons globally", may raise some
> controversy, since it won't be available after 2.0 series, but I find it pretty
> interesting for the kind of users SM is targeted to.

I would skip it, not only for the above reason but also because it's a command-line feature which you, if you describe it, need to get right (e.g. from my experience it only works with absolute paths). To save yourself from doing it in vain I should make sure to ask Ian and/or Stefan beforehand what they think about this.

> BTW, is this correct/polite if I assign this bug to myself? :-)

Absolutely, go ahead. Assignee should always be the one who is actively working on (implementing/fixing) the bug.
First draft patch. I have left out RDF files on purpose, waiting for comments on content.

Asking review to Stefan, to split workload between IanN and him. Feel free to correct me. :-)
Assignee: neil → rpmdisguise-otros
Status: NEW → ASSIGNED
Attachment #398096 - Flags: review?(stefanh)
(In reply to comment #15)
> (In reply to comment #14)
> > I'm thinking of
> > changing the title of the section/page from "Using the Add-on Manager" to
> > "Using Add-ons".
> 
> Maybe even just "Add-ons".


OK, done that way.


> > I know the second section, "Installing Add-ons globally", may raise some
> > controversy, since it won't be available after 2.0 series, but I find it pretty
> > interesting for the kind of users SM is targeted to.
> 
> I would skip it, not only for the above reason but also because it's a
> command-line feature which you, if you describe it, need to get right (e.g.
> from my experience it only works with absolute paths). To save yourself from
> doing it in vain I should make sure to ask Ian and/or Stefan beforehand what
> they think about this.


Since I had already written it when I wrote my previous comment :-) I've decided to keep it until the patch is reviewed.


> > BTW, is this correct/polite if I assign this bug to myself? :-)
> 
> Absolutely, go ahead. Assignee should always be the one who is actively working
> on (implementing/fixing) the bug.

Done.
(In reply to comment #16)
> Created an attachment (id=398096) [details]

Stefan is usually quite busy so I'll address the obvious things here to ease his review (don't be shocked, it's all just nits; your contribution is very welcome!):

>+    <li><a href="about_add-ons">About Add-ons</a></li>
>+    <li><a href="installing_add-ons">Installing Add-ons</a></li>
>+    <li><a href="installing_add-ons_globally">Installing Add-ons
>+      globally</a></li>
>+    <li><a href="the_get_add-ons_panel">The Get Add-ons panel</a></li>
>+    <li><a href="the_extensions_panel">The Extensions panel</a></li>
>+    <li><a href="the_themes_panel">The Themes panel</a></li>
>+    <li><a href="the_languages_panel">The Languages panel</a></li>
>+    <li><a href="the_plugins_panel">The Plugins panel</a></li>
>+    <li><a href="configuring_add-ons">Configuring Add-ons</a></li>
>+    <li><a href="removing_add-ons">Removing Add-ons</a></li>

The href values miss leading hashes (#).

>+<p>An Add-on is a piece of software that can be added to &brandShortName; to
>+  change its appearance, behaviour, or to add new features. It also can change

In en-US, it's "behavior".

>+  <li><strong>Extensions</strong>: This type of Add-on either changes the way
>+    &brandShortName; behaves or add new behaviour to it. For instance, there

Again "behavior" and "adds".

>+  <li><strong>Themes</strong>: Themes change the appearance and design of
>+    &brandShortName;, but doesn&apos;t add or change features. They act as a

"don&apos;t".

>+  <li><strong>Languages</strong>: While you can download &brandShortName; in
>+    your favorite language from a list of almost 20, you may add additional
>+    languages to it in the form of language packs. This way, different users
>+    may use &brandShortName; in its own language without having to install the

"their" instead of "its".

>+    program for every one. This is specially useful if you are going to install

"everyone".

>+<p>Add-ons are always packaged as XPI files, except in the case of plugins,

I think themes can also appear as simple .jar files, at least that's how it was in the past.

>+  which usually are binaries specific for the target operating system (but can
>+  be also packaged as XPI files containing inside the OS-specific binary).</p>

"can also be" AFAIK (ask Ian or another native speaker).

>+<ul>
>+  <li>By clicking on a link in a web site. The link may point directly to an
>+    XPI file, or use JavaScript functions from Mozilla API.

"on a web site" AFAIK (again, native speaker...).

>+    <p><strong>Note</strong>: As a security measure, &brandShortName; only
>+      allows installing Add-ons from a list of permitted sites. If you click on
>+      a link to install an XPI in a web site and nothing happens, check if the
>+      web site is in the permitted sites list, from the

"on the ... list" AFAIK (NS...).

>+  <li>By opening an XPI file from your local filesystem. You can open a local
>+    file selecting Open file... from the File menu, or by pressing

(Here and further down:) I don't know in how far Help has been updated but in general SM is using Unicode ellipses nowadays instead of just three dots.

>+  <li>Only for plugins, since they are connectors to external programs, it may
>+    happen that you need to install a separate program while &brandShortName;
>+    is closed so both the external program and the corresponding plugin for
>+    &brandShortName; get correctly installed.</li>

"installed correctly" AFAIK (NS...).

>+<p><tt>C:\Program Files\&brandShortName;\&brandShortName;.exe C:\Documents And
>+Settings\Administrator\My Documents\Downloads\MyExtension.xpi</tt></p>

First, the -install-global-extension is missing there and second I'm not sure you can use &brandShortName; to construct the application binary name.

>+<p>The Get Add-ons panel in the Add-on Manager uses web services provided by
>+  the Mozilla Add-ons web site to present a list of recommended Add-ons, as
>+  well as giving you the option to search Mozilla Add-ons repository directly

Missing "the" before "Mozilla Add-ons repository".

>+  <li>To search for Add-ons based in its name, description or tags, use the
>+    Search box. Type the words you want to look up for and press
>+    <kbd>Enter</kbd>. You will get a list of matching Add-ons. To clear the
>+    search box terms and the result list, click in the brush inside the search
>+    box.

"based on name", "look up and", "click the brush icon" AFAIK (NS...).

>+    <p><strong>Note</strong>: If no Add-on matchs your criteria, you will get

"matches".

>+  <li>To open a new browser window (or a new browser tab, depending on your
>+    preferences) with Mozilla Add-ons web site, click on Browse All

Missing "the" before "Mozilla Add-ons web site".

>+  <li>To get more info about one of the recommended Add-ons in the list
>+    displayed by default, click on the entry. The entry will expand, displaying
>+    a larger image, a full description of the Add-on, and an indication of the
>+    Add-on type (extension, theme, etc.). You will also be able to install the
>+    Add-on by clicking in the Add to &brandShortName; button inside the
>+    expanded entry.</li>

"clicking the".

>+  <li>To get more info on any of the installed extensions, click on the entry

Writing out "information" is probably better.

>+    <p><strong>Note</strong>: disabled extensions will appear dimmed.
>+      Incompatible extensions will appear dimmed, since they are also disabled,

I think the term "disabled" is used consistently instead of "dimmed" everywhere else so even if the word appeared multiple times in the sentence with that change it'll probably still be better.

>+      and with a forbidden sign over the extension icon (incompatible
>+      extensions are those which define themselves as not valid for the version
>+      of &brandShortName; you are using).</p>

I'd also use "not compatible with" instead of "valid for" here for consistency.

>+  <li>To access an extension preferences (if the extension features a

"preferences of an extension" sounds better to me.

>+    <p><strong>Note</strong>: if the extension does not feature a preferences
>+      panel, the Preferences button will be disabled. You can&apos;t access to
>+      preferences of disabled or incompatible extensions.</p>

remove "to" after "access".

>+  <li>To disable an extension currently enabled, click on the entry
>+    corresponding to the desired extension, then click the Disable button. An
>+    info bar will appear to remind you to that changes will apply once you

(And below:) "remind you that" (no "to").

>+    <p>If there are new updates, a new panel will show in the Add-on Manager

I'd say "If updates are found" (updates are always new, no?).

>+      update and uncheck the rest, and then click the Install updates... to
>+      retrieve updated Add-ons. Once downloaded, you will need to restart
>+      &brandShortName; so updates are applied.</p>

"button" missing after "Install updates..." (or remove "the" before it). Also I'd say "to apply the updates".

>+  <li>To get more info and a preview on any of the installed themes, click on
>+    the entry on the list. The entry will expand and show the full description

I'd say "click on an entry from the list".

>+    <p><strong>Note</strong>: contrary to extensions, you only can use a theme
>+    at the same time.</p>

"you can only use one theme at a time" (or "only one theme can be active at a time").

>+  <li>To disable a language pack currently enabled, click on the entry
>+    corresponding to the desired language pack, then click the Disable button.
>+    An info bar will appear to remind you to that changes will apply once you

(And below:) "remind you that" (no "to").

>+<p><strong>Note</strong>: Don&apos;t confuse disabling or enabling the language
>+  pack with selecting the language itself for the UI. To change the language of
>+  &brandShortName; UI, you must go to Appearance panel of &brandShortName;
>+  preferences.</p>

I'm not sure every potential user understands "UI". To be on the safe side you might as well write it out.

>+<p><strong>Note</strong>: If the extension does not feature a preferences
>+  panel, the Preferences button will be disabled. You can&apos;t access to
>+  preferences of disabled or incompatible extensions.</p>

no "to" after "access". Also "cannot" sounds better to me here (but maybe that's just me).

>+<p>To remove an extension, access the Extensions panel of the Add-on Manager,
>+  then click on the entry corresponding to the desired extension, then click
>+  the Uninstall button. An info bar will appear to remind you to that changes

"remind you that" (no "to").



>+++ bug373457/glossary.xhtml	2009-09-02 10:52:51.000000000 +0200

>+<dt id="add-on">add-on</dt><dd>A piece of software that can be added to
>+  &brandShortName; to change its appearance, behaviour, or to add new features.

"behavior".

>+  It also can change the language in which the user interface is shown. See
>+  also <a href="extension">extension</a>, <a href="language_pack">language
>+  pack</a>, <a href="plugin">plugin</a>, and <a href="theme">theme</a>.</dd>

Anchor links require hashes (#).

>+<dt id="extension">extension</dt><dd>A type of <a href="#add-on">add-on</a>
>+  that changes behaviour of &brandShortName; or adds new features to it.</dd>

"behavior".
(In reply to comment #18)
> (In reply to comment #16)
> > Created an attachment (id=398096) [details] [details]
> 
> Stefan is usually quite busy so I'll address the obvious things here to ease
> his review (don't be shocked, it's all just nits; your contribution is very
> welcome!):


First of all, I'm very sorry for being so buggy. I promise I'd knock my head on the wall next time I upload a patch without proof-reading it. :-)


> >+<p>An Add-on is a piece of software that can be added to &brandShortName; to
> >+  change its appearance, behaviour, or to add new features. It also can change
> 
> In en-US, it's "behavior".


Changed every appearance, sorry. I had in mind to review it, because I was not sure which form was the en-US, but I finally forgot about it.

> >+<p>Add-ons are always packaged as XPI files, except in the case of plugins,
> 
> I think themes can also appear as simple .jar files, at least that's how it was
> in the past.


Yep, I've been looking at SM themes in Mozilla Add-ons site and most of them seem to be packed as JAR files. I guess I can no longer say that I'm a fan of themes. :-)


> >+  which usually are binaries specific for the target operating system (but can
> >+  be also packaged as XPI files containing inside the OS-specific binary).</p>
> 
> "can also be" AFAIK (ask Ian or another native speaker).

No need to ask, you're right: :-)

http://forum.wordreference.com/showthread.php?t=899769
http://www.english-test.net/forum/ftopic22261.html


> >+<ul>
> >+  <li>By clicking on a link in a web site. The link may point directly to an
> >+    XPI file, or use JavaScript functions from Mozilla API.
> 
> "on a web site" AFAIK (again, native speaker...).


Here I doubt (googling for "link on a web" vs. "link in a web" returns almost the same amount of matches); let's wait for a native speaker. :-)

> 
> >+    <p><strong>Note</strong>: As a security measure, &brandShortName; only
> >+      allows installing Add-ons from a list of permitted sites. If you click on
> >+      a link to install an XPI in a web site and nothing happens, check if the
> >+      web site is in the permitted sites list, from the
> 
> "on the ... list" AFAIK (NS...).


Again, I'm not so sure here. I've found this:

http://www.english-test.net/forum/ftopic24465.html
http://www.usingenglish.com/forum/ask-teacher/48851-list-vs-list.html




> 
> >+  <li>By opening an XPI file from your local filesystem. You can open a local
> >+    file selecting Open file... from the File menu, or by pressing
> 
> (Here and further down:) I don't know in how far Help has been updated but in
> general SM is using Unicode ellipses nowadays instead of just three dots.


Changed to &hellip;. It works, at least in the SM 2.0b2 browser window.


> 
> >+  <li>Only for plugins, since they are connectors to external programs, it may
> >+    happen that you need to install a separate program while &brandShortName;
> >+    is closed so both the external program and the corresponding plugin for
> >+    &brandShortName; get correctly installed.</li>
> 
> "installed correctly" AFAIK (NS...).


Again, Google shows technical match in result figures of "correctly installed" vs. "installed correctly". Native speaker, can you help us? :-)


> >+<p><tt>C:\Program Files\&brandShortName;\&brandShortName;.exe C:\Documents And
> >+Settings\Administrator\My Documents\Downloads\MyExtension.xpi</tt></p>
> 
> First, the -install-global-extension is missing there and second I'm not sure
> you can use &brandShortName; to construct the application binary name.


Flag added, sorry. I'm not sure to understand your comment about the &brandShortName; entity. Honestly, I wrote the main content using KompoZer 0.8a4 in a separate file, so I had to write the literal "SeaMonkey". Once the content was complete, I merged it with customize_help.xhtml, opened it in Bluefish, and did a mass-replace to &brandShortName;. Still, I understand that's the best approach for a vendor package of SeaMonkey.


> >+  <li>To search for Add-ons based in its name, description or tags, use the
> >+    Search box. Type the words you want to look up for and press
> >+    <kbd>Enter</kbd>. You will get a list of matching Add-ons. To clear the
> >+    search box terms and the result list, click in the brush inside the search
> >+    box.
> 
> "based on name", "look up and", "click the brush icon" AFAIK (NS...).


I've changed to fit your corrections. I only have a tiny doubt in "look up and" vs. "look up for and".


> >+    <p><strong>Note</strong>: disabled extensions will appear dimmed.
> >+      Incompatible extensions will appear dimmed, since they are also disabled,
> 
> I think the term "disabled" is used consistently instead of "dimmed" everywhere
> else so even if the word appeared multiple times in the sentence with that
> change it'll probably still be better.


I wanted to express the visual style more than the meaning of it. You and I know that a dimmed/greyed entry is a disabled entry, but maybe people reading help don't. That's why I used "dimmed" to explain that it means "disabled".


> >+<p><strong>Note</strong>: Don&apos;t confuse disabling or enabling the language
> >+  pack with selecting the language itself for the UI. To change the language of
> >+  &brandShortName; UI, you must go to Appearance panel of &brandShortName;
> >+  preferences.</p>
> 
> I'm not sure every potential user understands "UI". To be on the safe side you
> might as well write it out.


I've replaced by "user interface".

All other changes have been corrected as you propose. I'll wait till tomorrow to upload the new patch, so others can comment on remaining open issues.

Thank you very much for your thorough review.
(In reply to comment #19)
> > >+<p><tt>C:\Program Files\&brandShortName;\&brandShortName;.exe C:\Documents And
> > >+Settings\Administrator\My Documents\Downloads\MyExtension.xpi</tt></p>
> > 
> > First, the -install-global-extension is missing there and second I'm not sure
> > you can use &brandShortName; to construct the application binary name.
> 
> 
> Flag added, sorry. I'm not sure to understand your comment about the
> &brandShortName; entity. Honestly, I wrote the main content using KompoZer
> 0.8a4 in a separate file, so I had to write the literal "SeaMonkey". Once the
> content was complete, I merged it with customize_help.xhtml, opened it in
> Bluefish, and did a mass-replace to &brandShortName;. Still, I understand
> that's the best approach for a vendor package of SeaMonkey.

Generally using the entity is correct but I doubt you can/should use it to specify the default installation folder name or even binary name. I don't think we have entities for those purposes, though. Maybe the reviewers knows better.

> > >+  <li>To search for Add-ons based in its name, description or tags, use the
> > >+    Search box. Type the words you want to look up for and press
> > >+    <kbd>Enter</kbd>. You will get a list of matching Add-ons. To clear the
> > >+    search box terms and the result list, click in the brush inside the search
> > >+    box.
> > 
> > "based on name", "look up and", "click the brush icon" AFAIK (NS...).
> 
> I've changed to fit your corrections. I only have a tiny doubt in "look up and"
> vs. "look up for and".

I guess we all agree that you can search for something but I strongly doubt you can "look up for" something. You can look something up, though. Also note that "for" after "look up" is not always wrong, e.g. when "look up" is meant in the sense of lifting one's sight.

> > >+    <p><strong>Note</strong>: disabled extensions will appear dimmed.
> > >+      Incompatible extensions will appear dimmed, since they are also disabled,
> > 
> > I think the term "disabled" is used consistently instead of "dimmed" everywhere
> > else so even if the word appeared multiple times in the sentence with that
> > change it'll probably still be better.
> 
> I wanted to express the visual style more than the meaning of it. You and I
> know that a dimmed/greyed entry is a disabled entry, but maybe people reading
> help don't. That's why I used "dimmed" to explain that it means "disabled".

"greyed out" is OK, it's more of a common term and already used in Help:
<http://mxr.mozilla.org/comm-central/search?string=greyed%20out>
"dimmed" on the other hand is not something I'd associate with "disabled". YMMV
Attachment #398096 - Attachment is obsolete: true
Attachment #398893 - Flags: review?(stefanh)
Attachment #398096 - Flags: review?(stefanh)
(In reply to comment #19)
> (In reply to comment #18)
> 
> > >+<ul>
> > >+  <li>By clicking on a link in a web site. The link may point directly to an
> > >+    XPI file, or use JavaScript functions from Mozilla API.
> > 
> > "on a web site" AFAIK (again, native speaker...).
> 
> 
> Here I doubt (googling for "link on a web" vs. "link in a web" returns almost
> the same amount of matches); let's wait for a native speaker. :-)


To reduce open issues, I've changed it to "on".


> > >+    <p><strong>Note</strong>: As a security measure, &brandShortName; only
> > >+      allows installing Add-ons from a list of permitted sites. If you click on
> > >+      a link to install an XPI in a web site and nothing happens, check if the
> > >+      web site is in the permitted sites list, from the
> > 
> > "on the ... list" AFAIK (NS...).
> 
> 
> Again, I'm not so sure here. I've found this:
> 
> http://www.english-test.net/forum/ftopic24465.html
> http://www.usingenglish.com/forum/ask-teacher/48851-list-vs-list.html


This is still "in" in the new patch, waiting for more opinions.


> > 
> > >+  <li>Only for plugins, since they are connectors to external programs, it may
> > >+    happen that you need to install a separate program while &brandShortName;
> > >+    is closed so both the external program and the corresponding plugin for
> > >+    &brandShortName; get correctly installed.</li>
> > 
> > "installed correctly" AFAIK (NS...).
> 
> 
> Again, Google shows technical match in result figures of "correctly installed"
> vs. "installed correctly". Native speaker, can you help us? :-)


To reduce open issues, I've changed it to "correctly installed".


> > >+<p><tt>C:\Program Files\&brandShortName;\&brandShortName;.exe C:\Documents And
> > >+Settings\Administrator\My Documents\Downloads\MyExtension.xpi</tt></p>
> > 
> > First, the -install-global-extension is missing there and second I'm not sure
> > you can use &brandShortName; to construct the application binary name.
> 
> 
> Flag added, sorry. I'm not sure to understand your comment about the
> &brandShortName; entity. Honestly, I wrote the main content using KompoZer
> 0.8a4 in a separate file, so I had to write the literal "SeaMonkey". Once the
> content was complete, I merged it with customize_help.xhtml, opened it in
> Bluefish, and did a mass-replace to &brandShortName;. Still, I understand
> that's the best approach for a vendor package of SeaMonkey.


This is still as "&brandShortName;", waiting for opinions (to the whole "installing globally" section mainly, and if it fits well, then to the use of the entity).

> > >+  <li>To search for Add-ons based in its name, description or tags, use the
> > >+    Search box. Type the words you want to look up for and press
> > >+    <kbd>Enter</kbd>. You will get a list of matching Add-ons. To clear the
> > >+    search box terms and the result list, click in the brush inside the search
> > >+    box.
> > 
> > "based on name", "look up and", "click the brush icon" AFAIK (NS...).
> 
> 
> I've changed to fit your corrections. I only have a tiny doubt in "look up and"
> vs. "look up for and".


Despite my comment, I had removed the "for" after "look up" so now it is "look up and..."

> > >+    <p><strong>Note</strong>: disabled extensions will appear dimmed.
> > >+      Incompatible extensions will appear dimmed, since they are also disabled,
> > 
> > I think the term "disabled" is used consistently instead of "dimmed" everywhere
> > else so even if the word appeared multiple times in the sentence with that
> > change it'll probably still be better.


"greyed out" now insted of "dimmed".

Thanks again, Jens.
(In reply to comment #22)
> (In reply to comment #19)
> > (In reply to comment #18)
> > 
> > > >+<ul>
> > > >+  <li>By clicking on a link in a web site. The link may point directly to an
> > > >+    XPI file, or use JavaScript functions from Mozilla API.
> > > 
> > > "on a web site" AFAIK (again, native speaker...).
> > 
> > 
> > Here I doubt (googling for "link on a web" vs. "link in a web" returns almost
> > the same amount of matches); let's wait for a native speaker. :-)
> 
> 
> To reduce open issues, I've changed it to "on".
I find that "you click on a link in a web site" but in help it is usually "you click on a link on a web page" - note use of page rather than site.
> 
> 
> > > >+    <p><strong>Note</strong>: As a security measure, &brandShortName; only
> > > >+      allows installing Add-ons from a list of permitted sites. If you click on
> > > >+      a link to install an XPI in a web site and nothing happens, check if the
> > > >+      web site is in the permitted sites list, from the
> > > 
> > > "on the ... list" AFAIK (NS...).
Here I would say "...install an XPI from a website" - within help both "web site" and "website" are used but more often "website".

> > > 
> > > >+  <li>Only for plugins, since they are connectors to external programs, it may
> > > >+    happen that you need to install a separate program while &brandShortName;
> > > >+    is closed so both the external program and the corresponding plugin for
> > > >+    &brandShortName; get correctly installed.</li>
> > > 
> > > "installed correctly" AFAIK (NS...).
> > 
> > 
> > Again, Google shows technical match in result figures of "correctly installed"
> > vs. "installed correctly". Native speaker, can you help us? :-)
Both are okay but "installed correctly" is better grammar (I think) - split infinitives otherwise (Like "To Boldy Go" vs "To Go Boldy")

> > > >+<p><tt>C:\Program Files\&brandShortName;\&brandShortName;.exe C:\Documents And
> > > >+Settings\Administrator\My Documents\Downloads\MyExtension.xpi</tt></p>
> > > 
> > > First, the -install-global-extension is missing there and second I'm not sure
> > > you can use &brandShortName; to construct the application binary name.
> > 
> > 
> > Flag added, sorry. I'm not sure to understand your comment about the
> > &brandShortName; entity. Honestly, I wrote the main content using KompoZer
> > 0.8a4 in a separate file, so I had to write the literal "SeaMonkey". Once the
> > content was complete, I merged it with customize_help.xhtml, opened it in
> > Bluefish, and did a mass-replace to &brandShortName;. Still, I understand
> > that's the best approach for a vendor package of SeaMonkey.
> 
> 
> This is still as "&brandShortName;", waiting for opinions (to the whole
> "installing globally" section mainly, and if it fits well, then to the use of
> the entity).
I think it is fine to use &brandShortName; here.
Please, note that this patch modifies glossary.xhtml, which just about to be modified also by bug 221259, thus rendering this patch invalid. Anyway, the patch in this bug (373457) is a draft and lacks changes in RDFs. Once ToC for add-ons section seems to be settled, I'll post a full patch.
Attachment #398893 - Attachment is obsolete: true
Attachment #399350 - Flags: review?(stefanh)
Attachment #398893 - Flags: review?(stefanh)
Ricardo,

I will try to look at this as soon as possible. It might take another week, though. Basically, time is not on my side atm.
This patch still lacks RDF changes. In fact, more than a thorough review, I'm interested in getting a thumbs up for table of contents. This way, I could add RDF changes and a provide a complete patch.
Attachment #399350 - Attachment is obsolete: true
Attachment #400178 - Flags: review?(stefanh)
Attachment #399350 - Flags: review?(stefanh)
(In reply to comment #25)
> I will try to look at this as soon as possible. It might take another week,
> though. Basically, time is not on my side atm.


No problem, I still have to translate to es-ES bug 221259. :-) Furthermore, as I say in comment 26, I'm mainly interested in comments about the ToC, to work in the RDF file changes.
Initial comments (no real review per comment #27):

+    <li><a href="#installing_add-ons_globally">Installing Add-ons
+      globally</a></li>

I don't think we shall cover this. We normally only cover things in the ui. The fact that it will be removed also makes it problematic - both in a sense that saying "We have this cool feature, but we will remove it" sounds a bit strange and in a sense that it'll require a re-visit (needs to be tracked/remembered).

+  <li><strong>Languages</strong>: While you can download &brandShortName; in
+    your favorite language from a list of almost 20.

I think we should keep out of numbers here so we don't need to remember to update this.

+    &brandShortName; browser window, instead of opening a separate window of
+    the target program.</li>

"opening the target program in a separate window" maybe?

+<p>Add-ons are always packaged as XPI files, except in the case of plugins,
+  which usually are binaries specific for the target operating system (but can
+  also be packaged as XPI files containing inside the OS-specific binary).</p>

Hmm, we might need to be clearer with what "XPI files" are. I'd suggest something in line with "Add-ons always comes as packages, each Add-on is a single file with the xpi extension ...". Another possibility would be to not explaining this here.

+  <li>By clicking on a link on a web page. The link may point directly to an
+    XPI file, or use JavaScript functions from Mozilla API.

Similar here, this might be a little bit too techy. Better to just say that you can install add-ons from websites directly by clicking on a link for an Add-on.

+  <li>By opening an XPI file from your local filesystem. You can open a local
+    file selecting Open file&hellip; from the File menu, or by pressing
+    <kbd>Ctrl</kbd>+<kbd>O</kbd>.</li>

There is an install button in the Add-on manager too. When you click the button, the file picker comes up.
I guess we need to say something about the file here if we don't say it in the previous section. Dpending on how you solve maybe we can get away by saying something like "By opening an add-on package previously saved on your hard drive.... ..."?

Note that if you want to cover the kb shortcuts, you need to take care of mac too (Cmd instead of Ctrl, see next note).

+<p>To access the Add-on Manager, follow any of these:</p>
+
+<ul>
+  <li>From any &brandShortName; window, open the Tools menu, then select
+    Add-on Manager.</li>
+  <li>From any &brandShortName; window, open the Edit menu, then select
+    Preferences&hellip;, then expand the Advanced category, then click on
+    Software Installation. In the right pane, click the Add-on Manager
+    button.</li>
+</ul>

The preference part is wrong for mac (no ellipsis, please) - on mac the menuitem is not in the Edit menu, you can solve this by using the "mac" and "noMac" classes:

"open the <span class="mac">&brandShortName;</span><span class="noMac">Edit</span> menu and choose Preferences"

+<p>The Themes Panel in the Add-on Manager lists the installed Add-ons of type
+  Theme.

Just saying "lists the installed themes/extensions/.." (multiple instances) should be enough.

Regarding the TOC, I think it looks good (except for the global install). I wonder if we shall have an entry called "Add-on Manager" or "Using the Add-on Manager", though. Thoughts?
Comment on attachment 400178 [details] [diff] [review]
The same patch adjusted now that bug 221259 has gone into comm-central

Removing the request since there will be a new patch up anyway.
Attachment #400178 - Flags: review?(stefanh)
(In reply to comment #28)

First of all sorry for this late reply. I've applied all your suggestions, except this:


> 
> +  <li>By opening an XPI file from your local filesystem. You can open a local
> +    file selecting Open file&hellip; from the File menu, or by pressing
> +    <kbd>Ctrl</kbd>+<kbd>O</kbd>.</li>
> 
> There is an install button in the Add-on manager too. When you click the
> button, the file picker comes up.


That's just the next list item: :-)

  <li>By opening the Add-on Manager. From there, you can install Add-ons from
    the Get Add-ons panel, or click the Install button.</li>


> Regarding the TOC, I think it looks good (except for the global install). I
> wonder if we shall have an entry called "Add-on Manager" or "Using the Add-on
> Manager", though. Thoughts?


I was about to use a TOC like this:

* About Add-ons
* Installing Add-ons
* Using the Add-on Manager
  * The Get Add-ons panel
  * The Extensions panel
...

But that led to placing most of the subsections under <h4>, which I found a bit too deep, so I removed the "Using the Add-on Manager" heading and declared an <h4 id="accessing_the_addon-manager"> so it could be referenced from other parts of help contents. What I could do is to promote that <h4> to <h3> to end with a TOC like this:

* About Add-ons
* Installing Add-ons
* Accessing the Add-on Manager
* The Get Add-ons panel
* The Extensions panel
...

I'm attaching the new patch in a few minutes.
Attached patch Patch addressing comment #28 (obsolete) — Splinter Review
I've applied all suggestions by Stefan, and merged recent changes in comm-central to the files I'm working with (I'm using a separate directory because I had some bad experienced merging files with Meld; I'll move the changed files to my local work copy of the repository and provide an hg diff patch as soon as you request it).
Attachment #400178 - Attachment is obsolete: true
Attachment #401886 - Flags: review?(stefanh)
Comment on attachment 401886 [details] [diff] [review]
Patch addressing comment #28

Thanks Ricardo - I adjusted your paths and applied the patch and I have some initial comments:

I realise you've probably spent some time thinking of the toc and I'm sorry I didn't noticed this earlier, but the nesting in the toc is too deep. Having one subsection under "Add-ons" is definately enough. It hits me that one possible solution would be to do like this:

Add-ons
  About Add-ons
  Installing Add-ons
  Using the Add-on Manager

If you have a structure like this, I think it would be reasonable to say that anyone expanding the Add-ons section would immediately find where to look for information regarding Add-on Manager usage. Under the "Using the Add-on Manager", you could just mention how to accessing it (without any heading, like an intro text, and maybe also move the mentioning about the manager in the main entry to here)

The disadvantage would be that the panel descriptions obviously should be subsections of "Using the Add-on Manager" and those subsections won't be visible in the toc and the headings will also be a bit small.

Another option, apart from your own suggestion, would be to mention the Add-on Manager and how to access it somewhere before the panel descriptions (and have them in the toc).

What do you think about? I'm not forcing you to pick any of my suggestions, but I would like to discuss the toc structure in order to get this really good :-)


Regarding the content, I've looked through the text and I think this starts looking really good. I have some initial comments (I will try to look at everything in more detail asap after we've settled the toc)

+    This is specially useful if you are going to install &brandShortName; in a
+    shared computer (like computer labs) where people speaking different
+    languages can use it.

I think "in a shared computer (like computer labs)" sounds a bit strange. How about "on a computer that is shared by different users in, for example, a computer lab"

+<p>Add-ons always comes as packages, each Add-on is a single file with the XPI
+  extension, except in the case of plugins, which usually are binaries specific
+  for the target operating system (but can also be packaged as XPI files
+  containing inside the OS-specific binary).</p>

<p>Add-ons always comes as packages. Each Add-on is a single file with the XPI
  extension, except in the case of plugins which usually are binaries specific
  to the target operating system.</p>

(since you say usually, there's no need for mentioning the exception - better keep it simple, I think)

+  <li>By opening an Add-on package from your local filesystem. You can open a
+    previously saved Add-on package selecting Open file from the File menu, or
+    by pressing <span class="mac"><kbd>Cmd</kbd></span><span
+    class="noMac"><kbd>Ctrl</kbd></span>+<kbd>O</kbd>.</li>

By opening a previously saved Add-on package, just like you open a regular file that you previously saved on your hard drive: Select ... ...
(or something like that)


+  <li>By opening the Add-on Manager. From there, you can install Add-ons from
+    the Get Add-ons panel, or click the Install button.</li>
By using the Get Add-ons panel in the Add-on manager or clicking the Install button in any of the panels in the Add-on Manager


+  <li>Only for plugins, since they are connectors to external programs, it may
+    happen that you need to install a separate program while &brandShortName;
+    is closed so both the external program and the corresponding plugin for
+    &brandShortName; get installed correctly.</li>
+  </ul>

Hmm, you can't really install plugins from the Add-ons Manager. I would suggest something like this:

(skip the list item) Note: Plugins are usually installed...

Please also note that you need to update http://mxr.mozilla.org/comm-central/source/suite/locales/en-US/chrome/common/help/nav_help.xhtml#1146

+  well as giving you the option to search the Mozilla Add-ons repository
"repository" might be difficult for users to understand. Perhaps something like "search all available Mozilla Add-ons directly ... "
(In reply to comment #32)
> +<p>Add-ons always comes as packages, each Add-on is a single file with the XPI
> +  extension, except in the case of plugins, which usually are binaries
> specific
> +  for the target operating system (but can also be packaged as XPI files
> +  containing inside the OS-specific binary).</p>
> 
> <p>Add-ons always comes as packages. Each Add-on is a single file with the XPI
>   extension, except in the case of plugins which usually are binaries specific
>   to the target operating system.</p>

"come", since Add-ons is plural (this has been wrong all the way back to comment 28).

> +  <li>By opening the Add-on Manager. From there, you can install Add-ons from
> +    the Get Add-ons panel, or click the Install button.</li>
> By using the Get Add-ons panel in the Add-on manager or clicking the Install
> button in any of the panels in the Add-on Manager

Uppercase M for Manager (first appearance).

> +  well as giving you the option to search the Mozilla Add-ons repository
> "repository" might be difficult for users to understand. Perhaps something like
> "search all available Mozilla Add-ons directly ... "

Or perhaps replace "repository" by "site". AMO doesn't host all available add-ons...
> > +  well as giving you the option to search the Mozilla Add-ons repository
> > "repository" might be difficult for users to understand. Perhaps something like
> > "search all available Mozilla Add-ons directly ... "
> 
> Or perhaps replace "repository" by "site". AMO doesn't host all available
> add-ons...

Sure, that'd work - the idea was that AMO hosts all "Mozilla Add-ons" (since we don't just say "Add-ons"), though.
(In reply to comment #32)
> (From update of attachment 401886 [details] [diff] [review])
> Thanks Ricardo - I adjusted your paths and applied the patch and I have some
> initial comments:
> 
> I realise you've probably spent some time thinking of the toc and I'm sorry I
> didn't noticed this earlier, but the nesting in the toc is too deep. Having one
> subsection under "Add-ons" is definately enough. It hits me that one possible
> solution would be to do like this:
> 
> Add-ons
>   About Add-ons
>   Installing Add-ons
>   Using the Add-on Manager
> 
> If you have a structure like this,


The current structure is 

Add-ons
    *     About Add-ons
    *     Installing Add-ons
    *     The Get Add-ons panel
    *     The Extensions panel
    *     The Themes panel
    *     The Languages panel
    *     The Plugins panel
    *     Configuring Add-ons
    *     Removing Add-ons


> I think it would be reasonable to say that
> anyone expanding the Add-ons section would immediately find where to look for
> information regarding Add-on Manager usage. Under the "Using the Add-on
> Manager", you could just mention how to accessing it (without any heading, like
> an intro text, and maybe also move the mentioning about the manager in the main
> entry to here)
> 
> The disadvantage would be that the panel descriptions obviously should be
> subsections of "Using the Add-on Manager" and those subsections won't be
> visible in the toc and the headings will also be a bit small.


So, something like this?

Add-ons
    *     About Add-ons
    *     Installing Add-ons
    *     Using Add-on Manager
          -     The Get Add-ons panel
          -     The Extensions panel
          -     The Themes panel
          -     The Languages panel
          -     The Plugins panel
    *     Configuring Add-ons
    *     Removing Add-ons


I wonder if you think we could keep the two last entries or if you find them redundant (they are to some extent, indeed). The subsections with a starting "-" in the previous schema wouldn't be part of the TOC sidebar, but just a <div class="inthisSection"> and <h4> headings.

Is that what you're thinking? Except for the <h4>, which it is maybe a bit small (but I can live with it), I find that a good solution.


> Another option, apart from your own suggestion, would be to mention the Add-on
> Manager and how to access it somewhere before the panel descriptions (and have
> them in the toc).
> 
> What do you think about? I'm not forcing you to pick any of my suggestions, but
> I would like to discuss the toc structure in order to get this really good :-)


I don't have a strong preference about any of the above choices. I'm pretty sure any of you have more experience and common sense in this matter. :-)


> Regarding the content, (...)


I'm applying all your comments with the corrections pointed out by Jens.
(In reply to comment #35)

> So, something like this?
> 
> Add-ons
>     *     About Add-ons
>     *     Installing Add-ons
>     *     Using Add-on Manager
>           -     The Get Add-ons panel
>           -     The Extensions panel
>           -     The Themes panel
>           -     The Languages panel
>           -     The Plugins panel
>     *     Configuring Add-ons
>     *     Removing Add-ons
> 
> 
> I wonder if you think we could keep the two last entries or if you find them
> redundant (they are to some extent, indeed). The subsections with a starting
> "-" in the previous schema wouldn't be part of the TOC sidebar, but just a <div
> class="inthisSection"> and <h4> headings.
> 
> Is that what you're thinking? Except for the <h4>, which it is maybe a bit
> small (but I can live with it), I find that a good solution.

OK, lets go for that then ;-) And as you said, the Configuring/Removing sections are not really needed, because you've already mentioned it. When it comes to the main section "Using the Add-on Manager", I think it would be good to mention something about what the the manager is (you could probably move the short description under "Add-ons" to this section and then just mention how to access the manager)

> 
> > Regarding the content, (...)
> 
> 
> I'm applying all your comments with the corrections pointed out by Jens.

Thanks to Jens for correcting my mistakes (a bit embarrassing, actually). If you attach a new patch I can look at the content in detail and do an actual review of it.
Attachment #401886 - Attachment is obsolete: true
Attachment #403267 - Flags: review?(stefanh)
Attachment #401886 - Flags: review?(stefanh)
(In reply to comment #36)
> OK, lets go for that then ;-) And as you said, the Configuring/Removing
> sections are not really needed, because you've already mentioned it. When it
> comes to the main section "Using the Add-on Manager", I think it would be good
> to mention something about what the the manager is (you could probably move the
> short description under "Add-ons" to this section and then just mention how to
> access the manager)


Done. :-) I've added an additional sentence in the introduction in Add-ons, since it looked too short after relocating the Add-on Manager description into its own subsection.
(In reply to comment #37)
> Created an attachment (id=403267) [details]
> New patch merging recent changes in files and changing TOC per comment #36

Did you forgot to add the changes to nav_help.xhtml I pointed out in comment #36? (the text in there refers to how you can see all your installed plugins) or did you just forgot to add the diff?

That said, if you want I can look at the patch in detail now, then you can eventually make some more changes and at that time include the nav_help stuff.
(In reply to comment #39)
> Did you forgot to add the changes to nav_help.xhtml I pointed out in comment
> #36? (the text in there refers to how you can see all your installed plugins)
> or did you just forgot to add the diff?


I forgot to do the changes (I took a look to the section the other day, but then I found a lot of changes in help files to localize and I decided to wait until I was up to date in the es-ES localization, and I ended forgetting nav_help.xhtml), sorry.


> That said, if you want I can look at the patch in detail now, then you can
> eventually make some more changes and at that time include the nav_help stuff.


I'm attaching a new patch with nav_help.xhtml changes right now.
Attachment #403267 - Attachment is obsolete: true
Attachment #403323 - Flags: review?(stefanh)
Attachment #403267 - Flags: review?(stefanh)
I'll try to look at this before thursday (since I'm away for the weekend).
I think this should be on the wanted-radar since it's a nice change to have for 2.0. I also think/hope that we can take this even if it slips the l10n freeze.
Flags: wanted-seamonkey2.0?
please remove me from your mailing list 
 
dave55@wowmail.com
(In reply to comment #44)
> please remove me from your mailing list 
> 
> dave55@wowmail.com

It's called the CC list and I'm pretty sure you could have done that yourself... Anyway, this should be the last mail you receive for this bug.
Flags: wanted-seamonkey2.0? → wanted-seamonkey2.0+
Whiteboard: [l10n-impact-help]
OK, so I've looked through the whole patch, and these are all my comments. It might look like a lot, but it's mainly small things (grammatical/wording). Also, feel free to comment on my suggested changes if you feel strongly about it.

+<p>One of the most exciting ways to customize &brandShortName; is through the
+  addition of Add-ons. In this section, you will learn what are Add-ons, how
"you will learn what Add-ons are"
+  to install them, and how to use the Add-on Mnager.</p>
Manager ;-)

+<p>An Add-on is a piece of software that can be added to &brandShortName; to
+  change its appearance, behavior, or to add new features. It also can change
+  the language in which the user interface is shown. Add-ons can be classified

"It can also change the language shown in the user interface"

+  <li><strong>Extensions</strong>: This type of Add-on either changes the way
+    &brandShortName; behaves or adds new behavior to it. For instance, there

Behaves and behavior sounds too close in this context, maybe "or adds new features".

+      &brandShortName; only allows installing Add-ons from a list of permitted
+      sites. If you click on a link to install an XPI from a website and
Just say "Add-on" instead of XPI.

+      nothing happens, check if the website is in the permitted sites list,
+      from the <a

Perhaps "nothing happens, you can use the Software Installation preferences panel to check if the website is in the permitted sites list" with a link to the panel.

+<p id="accessing_the_add-on_manager">To access the Add-on Manager, follow any
+  of these:</p>
"of these steps:"

+  <li>From any &brandShortName; window, open the Tools menu, then select
+    Add-on Manager.</li>
+  <li>From any &brandShortName; window, open the <span
I don't think we need the window part. The reason for this is that we're not in any particular window here so I think it's obvious that this exists in any window. There are also many places where we don't say this (and you don't mention the window in nav_help).

+  <li>To search for Add-ons based on name, description or tags, use the
+    Search box. Type the words you want to look up and press <kbd>Enter</kbd>.
OK, so here we want to differ between mac and non-mac, mac wants Return instead of Enter (<kbd class... etc).

+    <p><strong>Note</strong>: If no Add-on matches your criteria, you will get
Maybe better with "search criteria"?
+      a warning notice. If there are Add-ons matching your criteria, but they
+      are already installed or otherwise are incompatible with your current
"or otherwise incompatible" or "or incompatible"

+      version of &brandShortName;, there will be a link to open a browser
+      window with them.</p>

It looks to me that the link will take you to a list of all add-ons matching your search criteria, not just the one that is installed (I tried searching for chatzilla).

You could possibly explain this by saying something like this: "Already installed or incompatible Add-ons that matches your search criteria will not be displayed. You can see ... by clicking on the link... "

+  <li>To open a new browser window (or a new browser tab, depending on your
+    preferences) with the Mozilla Add-ons website, click on Browse All
+    Add-ons.</li>
"To open the Mozilla Add-ons website in a new browser window .... "

+  <li>To open a new browser window (or a new browser tab, depending on your
+    preferences) with the full list of recommended Add-ons for
+    &brandShortName;, scroll down the recommended Add-ons list until you see
+    the See All Recommended Add-ons link.</li>
Same here, To display the full list of ... ... in a new browser window,

+  <li>To get more info on any of the installed extensions, click on the entry
"more information about"
+    on the list. The entry will expand and show the full description of the

"in the list".

+  <li>To disable an extension currently enabled, click on the entry
I think it's enough to say "To disable an extension" (you could say "To disable a currently enabled extension", but this might be too obvious - you've already explained that the button is grayed out if it's disabled, but if you feel strongly about it I'm not gonna force you)

+  <li>To enable an extension currently disabled, click on the entry
Here you could say "To enable a currently disabled extension", or just "To enable an extension" (same discussion as above, basically).

+    incompatible), click the button Find updates&hellip;
No ellipsis, please. If you wonder why, we don't use ellipis or "..." at all in Help and I feel it's better to stick with that than to have a mixture.

+    <p>If updates are found, a new panel will show in the Add-on Manager
+      with found updates. 
"If updates are found, they will be displayed in a new panel" (and no ellipsis)

+      From there you can check extensions you want to
+      update and uncheck the rest, and then click the Install updates&hellip;
Hmm... I think it's easy to confuse the "check" here. Can you maybe say "In the panel, you can choose what extensions you want to update and then use the Install updates (is there a capital U in the button label?) button"?



+  <li>To get more info and a preview on any of the installed themes, click on
+    an entry on the list. The entry will expand and show the full description
"in the list"

+    <p><strong>Note</strong>: contrary to extensions, you only can use one
Capital letter after ": " 

+  <li>To disable a language pack currently enabled, click on the entry
(See previous discussion)

+  <li>To enable a language pack currently disabled
(see previous discussion)

+  language of &brandShortName; user interface, you must go to Appearance panel
+  of &brandShortName; preferences.</p>

+<p><strong>Note</strong>: Don&apos;t confuse disabling or enabling the language
+  pack with selecting the language itself for the user interface. To change the
+  language of &brandShortName; user interface, you must go to Appearance panel
+  of &brandShortName; preferences.</p>

Maybe we're a little bit hard here ;-)  How about something like this: "Enabling a language pack in the Language Panel doesn't change the language shown in &brandShortName;&apos; user interface, it only makes the language available for selection in the Appearance Preferences panel" (link to the help in the panel)?

+  Plugin. After accessing the Add-on Manager, click on the Plugins top button
Just "Plugins button" here (no need to mention "top"). And I think you want to link to how to access the add-on manager (as you do elsewhere)

+  <li>To disable a plugin currently enabled, click on the entry corresponding
+    to the desired plugin, then click the Disable button.</li>
+  <li>To enable a plugin currently disabled, click on the entry corresponding
+    to the desired plugin, then click the Enable button.</li>
See the previous discussions about this

+<dt id="add-on">add-on</dt><dd>A piece of software that can be added to
+  &brandShortName; to change its appearance, behavior, or to add new features.
+  It also can change the language in which the user interface is shown. 
Same comment as earlier (user interface language etc)

+<dt id="extension">extension</dt><dd>A type of <a href="#add-on">add-on</a>
+  that changes behavior of &brandShortName; or adds new features to it.</dd>
"the behavior".

+<dt id="theme">theme</dt><dd>A type of <a href="#add-on">add-on</a> that changes
+  the appearance of &brandShortName;. It doesn&apos;t change the way
+  &brandShortName; works, only how it looks.</dd>
I think you already made it clear what it changes by saying "appearance", so I'd suggest just skipping the last sentence.

 <ul>
   <li>Open the Help menu and choose About Plugins.</li>
   <li>Click in the Location Bar, type <kbd>about:plugins</kbd> and press
     <kbd class="mac">Return</kbd><kbd class="noMac">Enter</kbd>.</li>
+  <li>Open the Tools menu, choose Add-on Manager, and select the Plugins
+    panel.</li>
 </ul>
 
+<p>To learn more about the Add-on Manager and its features, see the section
+  <a href="customize_help.xhtml#using_the_add-on_manager">Using the Add-on
+  Manager</a>.</p>


Hmm, don't you think that we should promote the Add-on manager to second place in the list? I realize that it will then be difficult to have a natural connection to the paragraph - I can think of 2 ways to deal with this, though:

1) Just having a link to the Add-on manager section in the <li>.
2) Have a "<strong>Tip</strong>: To learn more... in the <li>
Comment on attachment 403323 [details] [diff] [review]
Patch including nav_help.xhtml changes

Minusing this because my previous comments needs to be addressed (we'll need a new patch).
Attachment #403323 - Flags: review?(stefanh) → review-
(Just dropping in, I hope you don't mind.)

(In reply to comment #46)
> +  language of &brandShortName; user interface, you must go to Appearance panel
> +  of &brandShortName; preferences.</p>
> 
> +<p><strong>Note</strong>: Don&apos;t confuse disabling or enabling the
> language
> +  pack with selecting the language itself for the user interface. To change
> the
> +  language of &brandShortName; user interface, you must go to Appearance panel
> +  of &brandShortName; preferences.</p>

I think there are some "the"s missing there (and maybe throughout the rest of the patch), notably after "language of", "go to" and "of" (the first one is not needed if using the genitive, i.e. "&brandShortName;&apos;s" and the third one looks strange to me either way, but that isn't an issue if you follow Stefan's suggestion below).

> Maybe we're a little bit hard here ;-)  How about something like this:
> "Enabling a language pack in the Language Panel doesn't change the language
> shown in &brandShortName;&apos; user interface, it only makes the language
> available for selection in the Appearance Preferences panel" (link to the help
> in the panel)?

I know this is just a suggestion but please note that "panel" should probably be lower-case here and an "s" is missing after "&apos;". Furthermore we could argue whether "Preferences" should start with a capital, be lower-case or removed altogether.
(In reply to comment #48)
> (Just dropping in, I hope you don't mind.)

Not at all.

> (In reply to comment #46)
> > +  language of &brandShortName; user interface, you must go to Appearance panel
> > +  of &brandShortName; preferences.</p>
> > 
> > +<p><strong>Note</strong>: Don&apos;t confuse disabling or enabling the
> > language
> > +  pack with selecting the language itself for the user interface. To change
> > the
> > +  language of &brandShortName; user interface, you must go to Appearance panel
> > +  of &brandShortName; preferences.</p>
> 
> I think there are some "the"s missing there (and maybe throughout the rest of
> the patch), notably after "language of", "go to" and "of" (the first one is not
> needed if using the genitive, i.e. "&brandShortName;&apos;s" and the third one
> looks strange to me either way, but that isn't an issue if you follow Stefan's
> suggestion below).
> 
> > Maybe we're a little bit hard here ;-)  How about something like this:
> > "Enabling a language pack in the Language Panel doesn't change the language
> > shown in &brandShortName;&apos; user interface, it only makes the language
> > available for selection in the Appearance Preferences panel" (link to the help
> > in the panel)?
> 
> I know this is just a suggestion but please note that "panel" should probably
> be lower-case here and an "s" is missing after "&apos;".
Yeah, true - my mistake.

Furthermore we could
> argue whether "Preferences" should start with a capital, be lower-case or
> removed altogether.
I think it usually starts with uppercase. Better keep it, I think.
(In reply to comment #46)
> OK, so I've looked through the whole patch, and these are all my comments. It
> might look like a lot, but it's mainly small things (grammatical/wording).


I'm sorry to cause so much work, and of course I welcome all corrections and am grateful for you taking the time and patience.


> +      a warning notice. If there are Add-ons matching your criteria, but they
> +      are already installed or otherwise are incompatible with your current
> "or otherwise incompatible" or "or incompatible"
> 
> +      version of &brandShortName;, there will be a link to open a browser
> +      window with them.</p>
> 
> It looks to me that the link will take you to a list of all add-ons matching
> your search criteria, not just the one that is installed (I tried searching
> for chatzilla).
> 
> You could possibly explain this by saying something like this: "Already
> installed or incompatible Add-ons that matches your search criteria will not
> be displayed. You can see ... by clicking on the link... "


I'm a bit confused about the link itself. It reads "See all results (5)" but when I click on it, I get ten results. I'm going to rephrase the paragraph to try to stick as much as possible to the actual behavior of that link.


> +  <li>To get more info on any of the installed extensions, click on the entry
> "more information about"

(...)

> +  <li>To get more info and a preview on any of the installed themes, click on
> +    an entry on the list. The entry will expand and show the full description
> "in the list"


I've changed also "To get more info and a preview on any..." to "To get more information and a preview on any...", per comment above.


> +  Plugin. After accessing the Add-on Manager, click on the Plugins top button
> Just "Plugins button" here (no need to mention "top"). And I think you want to
> link to how to access the add-on manager (as you do elsewhere)


Accessing the Add-on Manager linked, but I'm not sure if you really want me to remove "top" just from this section or I should remove it in the other sections (Get Add-ons, Extensions, Plugins and Language Packs) too.

(In reply to comment #48)
> > +  language of &brandShortName; user interface, you must go to Appearance panel
> > +  of &brandShortName; preferences.</p>
> > 
> > +<p><strong>Note</strong>: Don&apos;t confuse disabling or enabling the
> > language
> > +  pack with selecting the language itself for the user interface. To change
> > the
> > +  language of &brandShortName; user interface, you must go to Appearance panel
> > +  of &brandShortName; preferences.</p>
> 
> I think there are some "the"s missing there (and maybe throughout the rest of
> the patch), notably after "language of", "go to" and "of" (the first one is not
> needed if using the genitive, i.e. "&brandShortName;&apos;s" and the third one
> looks strange to me either way, but that isn't an issue if you follow Stefan's
> suggestion below).


No comment from Stefan about the missing  "the"s? I'm worried especially because of the "and maybe throughout the rest of the patch".

I'm going to prepare a new patch with the rest of points from comment #46 and comment #48.
(In reply to comment #50)
> (In reply to comment #46)
> > +      a warning notice. If there are Add-ons matching your criteria, but they
> > +      are already installed or otherwise are incompatible with your current
> > "or otherwise incompatible" or "or incompatible"
> > 
> > +      version of &brandShortName;, there will be a link to open a browser
> > +      window with them.</p>
> > 
> > It looks to me that the link will take you to a list of all add-ons matching
> > your search criteria, not just the one that is installed (I tried searching
> > for chatzilla).
> > 
> > You could possibly explain this by saying something like this: "Already
> > installed or incompatible Add-ons that matches your search criteria will not
> > be displayed. You can see ... by clicking on the link... "
> 
> 
> I'm a bit confused about the link itself. It reads "See all results (5)" but
> when I click on it, I get ten results. I'm going to rephrase the paragraph to
> try to stick as much as possible to the actual behavior of that link.


What about this?

    <p><strong>Note</strong>: If no Add-on matches your search criteria, you
      will get a warning notice. If there are Add-ons matching your criteria,
      but they are already installed or otherwise incompatible with your
      current version of &brandShortName;, there will be a link to perform a
      broader search in the Mozilla Add-ons website.</p>
Maybe it is too late, but I found myself in the middle of two hundred string changes between SM and TB, including some changes in files affected by this bug. Sorry. :-(
Attachment #403323 - Attachment is obsolete: true
Attachment #404524 - Flags: review?(stefanh)
Sorry, I've been away all weekend (I just got back from Prague), but I'll try to look at this when I get back from work tomorrow. You know, the freeze is not until tuesday ;)
(In reply to comment #50)

> 
> I'm sorry to cause so much work, and of course I welcome all corrections and am
> grateful for you taking the time and patience.

Hey, I'm very grateful that you're doing this :-) I will unfortunately cause you some more work since I've discovered some more things in your patch that I probably have noticed in the first round.
 
> ... I'm not sure if you really want me to
> remove "top" just from this section or I should remove it in the other sections
> (Get Add-ons, Extensions, Plugins and Language Packs) too.

Yes, I want. And now I notice that you mix the button clicking wording a bit, it's sometimes "click on the xx button", "click the xx button" and "click the button xx". It should actually always be "click the xx button" and, further on, you never say "click on".

This is actually my fault, but "click on the/an entry in the list" is not correct either, it should be "click the/an entry in the list". "click on a link" is not right either (sorry). So, no "Click on", just "Click". I think to both you and me (Swedish) clicking on something sounds natural, but when someone mentioned the "Push the door" signs to me (it never says "Push on the door") I suddenly became enlightened. So, please change all "click on" to just "click" and swap the "click the button xx" to "click the xx button".

More comments:

+    <p><strong>Note</strong>: As an additonal security measure,
+      &brandShortName; only allows installing Add-ons from a list of permitted
+      sites. If you click on a link to install an Add-on from a website and
+      nothing happens, you can use the <a
+      href="cs_nav_prefs_advanced.xhtml#software_installation">Software
+      Installation preferences panel</a> to check if the website is in the
+      permitted sites list.</p>

Actually, this is my fault again, but this could appear a bit strange since it's kind of obvious that the website isn't in the list. I think what we should do here instead is just indicating to the user that he/she can add/remove sites to the list and skip the nothing happens part section:

"from the list of permitted sites in the <a href="cs_nav_prefs_advanced.xhtml#software_installation">Software Installation preferences panel</a>"

+<ul>
+  <li>Open the Tools menu, then select Add-on Manager.</li>
+  <li>Open the <span class="mac">&brandShortName;</span><span
+    class="noMac">Edit</span> menu, then select Preferences, then expand the
+    Advanced category, then click on Software Installation. In the right pane,
+    click the Add-on Manager button.</li>

It's a matter of choice, but lots of "then" here, let me suggest a slightly better way imo:

"menu and choose Preferences" (after "menu"), expand the Advanced category and click Software Installation."



+  <li>To search for Add-ons based on name, description or tags, use the
+    Search box. Type the words you want to look up and press <span
"Search box. Type a word or phrase and press" (just a suggestion, not mandatory)

+    class="mac"><kbd>Return</kbd></span><span
+    class="noMac"><kbd>Enter</kbd></span>. You will get a list of matching
+    Add-ons. To clear the search box terms and the result list, click the
+    brush icon inside the search box.
The icon is problematic, because it looks different depending on OS/Theme. I think we need to live without the "brush" here and just say "icon" (unless you have a better suggestion). A more drastic solution is to

+    <p><strong>Note</strong>: If no Add-on matches your search criteria, you
+      will get a warning notice. If there are Add-ons matching your criteria,
+      but they are already installed or otherwise incompatible with your
+      current version of &brandShortName;, there will be a link to perform a
+      broader search in the Mozilla Add-ons website.</p>

I'm also totally confused  what the link "See allresults(xx) actually means since the amount shown never matches the results I get when I click on the link (I expected 62, but got 347!). I think it's better to leave out the text for now and maybe get a better explanation in a follow-up when we know more about it. What we could say is that the search won't return any results if the add-ons found are installed or incompatible. So, I'd suggest just writing:

"<p><strong>Note</strong>:  If no Add-on matches your search criteria, you
will get a warning notice. Add-ons that are already installed or incompatible with your current version of &brandShortName; will not be displayed in the list of search results.</p>" (I don't think you need to inform the user about the warning, but I'm fine keeping it if you think it's needed)

+    <p>If no updates are found, an info bar will inform you about it.</p>
The same here actually - the user will automatically be informed about this when it happens and then it's obvious. Keep it if you want, but only if you keep the previous one ;-)

+  <a href="cs_nav_prefs_appearance.xhtml#appearance">Appearance Preferences
+  panel</a> of &brandShortName; preferences.</p>

Actually, it's obvious that the panel is in seamonkey's preferences, so please remove " of &brandShortName; preferences"
Comment on attachment 404524 [details] [diff] [review]
New patch with all suggestions from comments #46 and beyond, and latest changes in comm-central

Minusing because I want a new patch with all corrections that I can skim through. You basically have r+ on the new patch, though. I'm not sure I will be able to look at the new patch this evening, but if you put up a new patch with all the corrections I promise I will look through it sometime around 1900 CEST tomorrow. That should leave us with some time to get this in before the freeze (it's 2400 PST iirc).
Attachment #404524 - Flags: review?(stefanh) → review-
(In reply to comment #54)

> you some more work since I've discovered some more things in your patch that I
> probably have noticed in the first round.
"should have"
(In reply to comment #54)

> +    class="mac"><kbd>Return</kbd></span><span
> +    class="noMac"><kbd>Enter</kbd></span>. You will get a list of matching
> +    Add-ons. To clear the search box terms and the result list, click the
> +    brush icon inside the search box.
> The icon is problematic, because it looks different depending on OS/Theme. I
> think we need to live without the "brush" here and just say "icon" (unless you
> have a better suggestion). A more drastic solution is to
"completely remove the clear section" - sorry for the spam.
(In reply to comment #54) 
> Hey, I'm very grateful that you're doing this :-) I will unfortunately cause
> you some more work since I've discovered some more things in your patch that I
> probably have noticed in the first round.


No problem. Sorry for my late answer, but Yahoo! SMTP servers tend to delay message delivery for hours; I checked my account on Mon 5 @ 17:00 CEST, and I had no messages (and it was 8 hours after your comments).


> > ... I'm not sure if you really want me to
> > remove "top" just from this section or I should remove it in the other sections
> > (Get Add-ons, Extensions, Plugins and Language Packs) too.
> 
> Yes, I want. And now I notice that you mix the button clicking wording a bit,
> it's sometimes "click on the xx button", "click the xx button" and "click the
> button xx". It should actually always be "click the xx button" and, further on,
> you never say "click on".


OK, and a good explanation. I've reviewed all click* and button appearances. I've also removed "top" in the "top button" appearances.


> +  <li>To search for Add-ons based on name, description or tags, use the
> +    Search box. Type the words you want to look up and press <span
> "Search box. Type a word or phrase and press" (just a suggestion, not
> mandatory)


It sounds better, definitely. :-)


> +    <p><strong>Note</strong>: If no Add-on matches your search criteria, you
> +      will get a warning notice. If there are Add-ons matching your criteria,
> +      but they are already installed or otherwise incompatible with your
> +      current version of &brandShortName;, there will be a link to perform a
> +      broader search in the Mozilla Add-ons website.</p>
> 
> I'm also totally confused  what the link "See allresults(xx) actually means
> since the amount shown never matches the results I get when I click on the link


I got you!! Did you really click ON the link?? ;-P


> "<p><strong>Note</strong>:  If no Add-on matches your search criteria, you
> will get a warning notice. Add-ons that are already installed or incompatible
> with your current version of &brandShortName; will not be displayed in the list
> of search results.</p>" (I don't think you need to inform the user about the
> warning, but I'm fine keeping it if you think it's needed)
> 
> +    <p>If no updates are found, an info bar will inform you about it.</p>
> The same here actually - the user will automatically be informed about this
> when it happens and then it's obvious. Keep it if you want, but only if you
> keep the previous one ;-)


I've removed both, because re-reading it it sound a bit offensive to readers, especially the second one. :-)

Everything else in your comment I've removed is also fixed as per your suggestions.

I'm providing a new patch in a few minutes. Problem is, I'll be working tomorrow in the afternoon and I may not arrive at home (where I could fix any reamining issue) until 20:00 CEST.
This time the patch has been made in my local working copy of comm-central using hg diff -U 8; hopefully it could be used to commit into comm-central if it passes the review.
Attachment #404524 - Attachment is obsolete: true
Attachment #404719 - Flags: review?(stefanh)
Comment on attachment 404719 [details] [diff] [review]
Patch applying fixes outlined in comment #54

I only spotted to small things:
+    <p><strong>Note</strong>: disabled extensions will appear greyed out.

+    <p><strong>Note</strong>: if the extension does not feature a preferences

I'll fix the lowercases when I land the patch. Thanks for the patch, Ricardo!
Attachment #404719 - Flags: review?(stefanh) → review+
Landed this with a=KaiRo over IRC:

http://hg.mozilla.org/comm-central/rev/f30e72dc9092
Status: ASSIGNED → RESOLVED
Closed: 10 years ago
Resolution: --- → FIXED
(In reply to comment #60)
> I'll fix the lowercases when I land the patch. Thanks for the patch, Ricardo!


My pleasure, we did it! :-) As always, thank you for your patience, Ian, Jens and you are really great people.
Comment on attachment 404719 [details] [diff] [review]
Patch applying fixes outlined in comment #54

>+    installation, with the Install button disabled during some seconds in
Correct English grammar is "for some seconds".

>+    order to avoid you accidentally click it just as the dialog shows up.
... accidentally clicking it ...
(In reply to comment #63)
> (From update of attachment 404719 [details] [diff] [review])
> >+    installation, with the Install button disabled during some seconds in
> Correct English grammar is "for some seconds".
> 
> >+    order to avoid you accidentally click it just as the dialog shows up.
> ... accidentally clicking it ...

[Before it gets lost:] Ian, do you think these are worth a follow-up patch?
(In reply to comment #64)
> (In reply to comment #63)
> > (From update of attachment 404719 [details] [diff] [review] [details])
> > >+    installation, with the Install button disabled during some seconds in
> > Correct English grammar is "for some seconds".
> > 
> > >+    order to avoid you accidentally click it just as the dialog shows up.
> > ... accidentally clicking it ...
> 
> [Before it gets lost:] Ian, do you think these are worth a follow-up patch?


Since it was my fault, I can create a follow-up bug and provide a patch if you want.
I'm happy with either putting a new patch up on this bug or creating a new bug to put it onto. Which ever way, thanks.
Since I'm not a good friend of playing with revisions and patches in the same file :-) and customize_help.xhtml is already included in (maybe not valid) patch for bug #226191, I'll better wait until that is cleared.
Actually, we're going to need a new bug to adapt this section to the new, tab-based Add-ons Manager, but I thought that it is better to have those grammar errors fixed before moving on.
Attachment #476906 - Flags: review?(iann_bugzilla)
Attachment #476906 - Flags: review?(iann_bugzilla) → review+
Comment on attachment 476906 [details] [diff] [review]
Patch to address grammar errors described at comment #64 [Checked in: Comment 69]

http://hg.mozilla.org/comm-central/rev/a2d109f74af3
Attachment #476906 - Attachment description: Patch to address grammar errors described at comment #64 → Patch to address grammar errors described at comment #64 [Checked in: Comment 69]

(In reply to RickieES aka Ricardo Palomares from comment #19)

(In reply to comment #18)

(In reply to comment #16)

Created an attachment (id=398096) [details] [details]

Stefan is usually quite busy so I'll address the obvious things here to ease
his review (don't be shocked, it's all just nits; your contribution is very
welcome!):

First of all, I'm very sorry for being so buggy. I promise I'd knock my head
on the wall next time I upload a patch without proof-reading it. :-)

+<p>An Add-on is a piece of software that can be added to &brandShortName; to

  • change its appearance, behaviour, or to add new features. It also can change

In en-US, it's "behavior".

Changed every appearance, sorry. I had in mind to review it, because I was
not sure which form was the en-US, but I finally forgot about it.

+<p>Add-ons are always packaged as XPI files, except in the case of plugins,

I think themes can also appear as simple .jar files, at least that's how it was
in the past.

Yep, I've been looking at SM themes in Mozilla Add-ons site and most of them
seem to be packed as JAR files. I guess I can no longer say that I'm a fan
of themes. :-)

  • which usually are binaries specific for the target operating system (but can
  • be also packaged as XPI files containing inside the OS-specific binary).</p>

"can also be" AFAIK (ask Ian or another native speaker).

No need to ask, you're right: :-)

http://forum.wordreference.com/showthread.php?t=899769
http://www.english-test.net/forum/ftopic22261.html

+<ul>

  • <li>By clicking on a link in a web site. The link may point directly to an
  • XPI file, or use JavaScript functions from Mozilla API.

"on a web site" AFAIK (again, native speaker...).

Here I doubt (googling for "link on a web" vs. "link in a web" returns
almost the same amount of matches); let's wait for a native speaker. :-)

  • <p><strong>Note</strong>: As a security measure, &brandShortName; only
  •  allows installing Add-ons from a list of permitted sites. If you click on
    
  •  a link to install an XPI in a web site and nothing happens, check if the
    
  •  web site is in the permitted sites list, from the
    

"on the ... list" AFAIK (NS...).

Again, I'm not so sure here. I've found this:

http://www.english-test.net/forum/ftopic24465.html
https://www.mangazuki.online/manga/apotheosis/

  • <li>By opening an XPI file from your local filesystem. You can open a local
  • file selecting Open file... from the File menu, or by pressing

(Here and further down:) I don't know in how far Help has been updated but in
general SM is using Unicode ellipses nowadays instead of just three dots.

Changed to …. It works, at least in the SM 2.0b2 browser window.

  • <li>Only for plugins, since they are connectors to external programs, it may
  • happen that you need to install a separate program while &brandShortName;
  • is closed so both the external program and the corresponding plugin for
  • &brandShortName; get correctly installed.</li>

"installed correctly" AFAIK (NS...).

Again, Google shows technical match in result figures of "correctly
installed" vs. "installed correctly". Native speaker, can you help us? :-)

+<p><tt>C:\Program Files&brandShortName;&brandShortName;.exe C:\Documents And
+Settings\Administrator\My Documents\Downloads\MyExtension.xpi</tt></p>

First, the -install-global-extension is missing there and second I'm not sure
you can use &brandShortName; to construct the application binary name.

Flag added, sorry. I'm not sure to understand your comment about the
&brandShortName; entity. Honestly, I wrote the main content using KompoZer
0.8a4 in a separate file, so I had to write the literal "SeaMonkey". Once
the content was complete, I merged it with customize_help.xhtml, opened it
in Bluefish, and did a mass-replace to &brandShortName;. Still, I understand
that's the best approach for a vendor package of SeaMonkey.

  • <li>To search for Add-ons based in its name, description or tags, use the
  • Search box. Type the words you want to look up for and press
  • <kbd>Enter</kbd>. You will get a list of matching Add-ons. To clear the
  • search box terms and the result list, click in the brush inside the search
  • box.

"based on name", "look up and", "click the brush icon" AFAIK (NS...).

I've changed to fit your corrections. I only have a tiny doubt in "look up
and" vs. "look up for and".

  • <p><strong>Note</strong>: disabled extensions will appear dimmed.
  •  Incompatible extensions will appear dimmed, since they are also disabled,
    

I think the term "disabled" is used consistently instead of "dimmed" everywhere
else so even if the word appeared multiple times in the sentence with that
change it'll probably still be better.

I wanted to express the visual style more than the meaning of it. You and I
know that a dimmed/greyed entry is a disabled entry, but maybe people
reading help don't. That's why I used "dimmed" to explain that it means
"disabled".

+<p><strong>Note</strong>: Don't confuse disabling or enabling the language

  • pack with selecting the language itself for the UI. To change the language of
  • &brandShortName; UI, you must go to Appearance panel of &brandShortName;
  • preferences.</p>

I'm not sure every potential user understands "UI". To be on the safe side you
might as well write it out.

I've replaced by "user interface".

All other changes have been corrected as you propose. I'll wait till
tomorrow to upload the new patch, so others can comment on remaining open
issues.

Thank you very much for your thorough review.

I also think that customize_help.xhtml is the right place to start (not necessarily the only one, though). However, since its table of contents links to anchors on the same page, I guess you should do the same for the Add-ons Manager instead of creating a new page, at least as far as linking from the TOC is concerned.

You need to log in before you can comment on or make changes to this bug.