253521 - use "Menu > Menuitem" everywhere

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Steffen Wilberg]

In the Themes and Extensions sections in customization.xhtml, the reference to
menuitems isn't like everywhere else.

Comment 1

[Steffen Wilberg]

Attachment: patch

This includes minor cleanup like removing double spaces.

Comment 2

[Steffen Wilberg]

Comment on attachment 154636 [details] [diff] [review]
patch

>-<p>Once in the Extensions dialog, select the extension that you wish to remove.
>+<p>Once in the Extensions Manager, select the extension that you wish to remove.
>   Then, click the Uninstall button. You may need to close and then reopen
>-  &brandShortName; for all changes to take effect.</p>
>+  &brandShortName; for changes to take effect.</p>
I removed the "all" here, since there is no effect at all until you restart
Firefox. For example, mouse gestures still work after uninstalling All-in-One
Gestures.

Comment 3

[Steffen Wilberg]

Attachment: diff -uw of that

Without the whitespace changes.

Comment 4

[Jeff Walden (gone starting June 8)]

When I wrote the Language Style guide, I didn't mention sentence spacing.  I
considered it, but I didn't think it would matter much.  Perhaps it matters a
little more than I thought.

Sentence spacing has to be the most nitpicky change I could have proposed.  The
end user never sees it.  Both types of spacing are common.  Maintaining a
specific choice here requires a certain amount of effort.  Is the return worth
the effort?  Out of habit I always used two, so my changes in the docs I've
touched (which is probably most) are double-spaced between sentences.  I've also
seen some that were single-spaced (so my changes were double but the original
stayed single).

For this patch it doesn't matter because the work's already been done.  In the
future, tho, is it really a worthwhile goal to standardize sentence spacing? 
It's nothing the end user will ever see, and I get the feeling it'll just create
more nitpicky work for any would-be patcher or reviewer.

Comment 5

[Jeff Walden (gone starting June 8)]

As an FYI, R.J., there are some minor changes for bug 253538 that might be worth
adding to this patch.  The change would correct a grammatical error.  I've
outlined the necessary change in that bug, and I don't think it'll impact any
l10n efforts.

Comment 6

[Steffen Wilberg]

R.J. said on IRC that we shouldn't use ">", because someone who needs Help might
not understand that. So instead of this:
  Select <span class="menuPath">Tools &gt; Options</span>.
we should use this:
  Select <span class="menuPath">Options</span> from the <span
  class="menuPath">Tools</span> menu.
A grep for "&gt;" in browser/components/help/locales/en-US yields 26 hits (after
I deleted my ~-files).

But then someone said that
"In Help code the standard form for citing menu items has been arbitrarily
decided as Menu > [Submenu >] Menu Item (encased within a <span
class="menuPath"> to keep consistency with the Mozilla Firefox site."
http://www.mozilla.org/projects/help-viewer/documentation_coding-style.php#use_correct_element

(I won't bother about spaces in the future, I completely forgot they're
invisible in (x)html.)

Comment 7

[Jeff Walden (gone starting June 8)]

(In reply to comment #6)
> "In Help code the standard form for citing menu items has been arbitrarily
> decided as Menu > [Submenu >] Menu Item (encased within a <span
> class="menuPath"> to keep consistency with the Mozilla Firefox site."

That was me thinking that it would be good to keep it the same style as on
http://texturizer.net/firefox/tips.html#beh_reuse (possibly after some minor
discussion).  If it needs to change I don't think anyone will care too much.  I
don't think it'll be particularly helpful for l10n, tho, because I remember part
of the reason for the [Menu] > [Item] format was to help make them less
confusing (by being consistent) and easier to localize.

Comment 8

[Steffen Wilberg]

R.J., we need a decision here: Use "Menu > Menuitem" everywhere or nowhere.

Comment 9

[R.J. Keller]

(In reply to comment #8)
> R.J., we need a decision here: Use "Menu > Menuitem" everywhere or nowhere.

nowhere

Comment 10

[R.J. Keller]

Steffen,

We simply don't have time for this. It's too close to the release. A lot of the
localizers have already started translating help and I wouldn't want to put them
through this radical of a change.

We can do this after 1.0.

Comment 11

[Jeff Walden (gone starting June 8)]

WONTFIX because what's used now is good enough, should be understandable, and is
used on <http://www.mozilla.org/support/firefox/>.

Comment 12

[Steffen Wilberg]

See comment 0: "click on Tools from the menu bar and select the Themes menu item."
That should be "select Tools > Themes". Reopening.

Comment 13

[Steffen Wilberg]

Attachment: new patch

Fixes comment 12, and tweaks the wording.

Comment 14

[Steffen Wilberg]

Checking in mozilla/browser/components/help/locale/en-US/customization.xhtml;
/cvsroot/mozilla/browser/components/help/locale/en-US/customization.xhtml,v  <--
 customization.xhtml
new revision: 1.17; previous revision: 1.16
done