253657 - Help Doc on Menu Reference is incomplete

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Francesco Lodolo [:flod]]

User-Agent:       Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7) Gecko/20040626 Firefox/0.9.1
Build Identifier: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7) Gecko/20040626 Firefox/0.9.1

I refer to Menu_Reference.xhtml (the date at the end of the page is 10 july
2004); I hope this is the last and most updated version.

In the FILE section the "Close Tab" menu item has disappeared; is it an error?

In the TOOLS section, information about Extensions and Themes are incomplete.

*Extensions*
"Opens the Extension Manager, where you can see all extensions installed on this
version of Firefox. You can also choose to uninstall some extensions from this
dialog."

Why only "some" extensions? Also, there is no reference to the update and
disable function.

*Themes*
"Opens the Theme Manager. From here, you can switch the current theme that
Firefox is using. You can also install and uninstall themes from this dialog."

Same problem: no information about the possibility to update existing theme.

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

Comment 1

[R.J. Keller]

(In reply to comment #0)
> In the FILE section the "Close Tab" menu item has disappeared; is it an error?

Close Tab is only there when a tab is open.

> 
> In the TOOLS section, information about Extensions and Themes are incomplete.

I'll add a link to customization.xhtml

> 
> *Extensions*
> "Opens the Extension Manager, where you can see all extensions installed on this
> version of Firefox. You can also choose to uninstall some extensions from this
> dialog."
> 
> Why only "some" extensions? Also, there is no reference to the update and
> disable function.

That's because it's in customization.xhtml. I added a link.

> 
> *Themes*
> "Opens the Theme Manager. From here, you can switch the current theme that
> Firefox is using. You can also install and uninstall themes from this dialog."
> 
> Same problem: no information about the possibility to update existing theme.

Did the same thing for extensions.

Just checked in the fix, so we should be done here. Reopen if I missed something.

Comment 2

[R.J. Keller]

> 
> *Extensions*
> "Opens the Extension Manager, where you can see all extensions installed on this
> version of Firefox. You can also choose to uninstall some extensions from this
> dialog."
> 
> Why only "some" extensions? Also, there is no reference to the update and
> disable function.

oh, and I removed the word "some".

Comment 3

[Francesco Lodolo [:flod]]

(In reply to comment #1)
> (In reply to comment #0)
> > In the FILE section the "Close Tab" menu item has disappeared; is it an error?
> 
> Close Tab is only there when a tab is open.
> 
I know this is a Firefox's feature, but I mean why there is no explanation of
this behaviour in this document?

Something like that in texturizer.net 
**Close Tab
**This menu item is visible only if more than one browser tab is currently open.
Closes the current tab and selects the rightmost tab.

Comment 4

[R.J. Keller]

(In reply to comment #3)
> I know this is a Firefox's feature, but I mean why there is no explanation of
> this behaviour in this document?
> 
> Something like that in texturizer.net 
> **Close Tab
> **This menu item is visible only if more than one browser tab is currently open.
> Closes the current tab and selects the rightmost tab.

ahh! good point! I fixed this.

Comment 5

[Steffen Wilberg]

I removed the double </p>.
The doc is wrong as well. It now says that "New tab" is only visible if more
than one tab is open. But "New tab" is visible all the time.

If the tab bar is visible (showing 1 or more tabs), we have "Close tab" and
"Close window".
If the tab bar is invisible, we have "Close" instead. The shortcut for that is
Ctrl+W like Close tab. So I'd suggest:

  Close tab: ... This is called "Close" if the tab bar is not displayed.
  Close window: ... This is only visible if the tab bar is displayed.

Maybe you can improve the wording, but you get the idea.

Comment 6

[Jeff Walden (gone starting June 8)]

-->me

I'm working on a fix for this right now, which is actually considerably more
complicated than it would seem.  There are several new menu entries that need
documentation, some information is inaccurate, we appear to be missing
documentation for a whole menu present only on the Mac because no one working on
Help uses a Mac (I'm hoping to get some help via IRC, tho it may not happen),
and the platformization of Help is complicated by the fact that while we can
remove the platform-specific info (in particular, Edit>Prefs vs. Tools>Opts
because the items are in completely different code locations in the docs) from
help via CSS, we can't remove the corresponding Table of Contents items (bug
254992, just filed).

I'm keeping on this, attempting to work my way around the issues mentioned above
as best as I can.  Expect the patch to come with lots of clarifications of the
various issues solved.  As with many of the other patches I've uploaded
recently, it'll also contain fixes for bug 249231 because that fix is so bloody
big.  (It's hassle, but I have no idea how to work around it.)

Comment 7

[Jeff Walden (gone starting June 8)]

Attachment: Patch for everything except Window menu on Mac

I'm tempted to attach comments as an attachment because they're huge, but I
don't know what effect that would have on getting them read, so I'm putting
them below.

This patch fixes these issues (explanations after where I think they're
needed):

-incorrect info for File>New Tab
-expanded File->Close Tab info
-renamed File->Close to add "(Window)" afterwards, because if tabs are open
"Window" might be present
  -adding an extra entry to Help for it seems pointless
-File>Print Preview is mentioned in docs as not on Macs
-display correct name for Exit in docs (Exit==Win,Quit==!Win)
  -in ToC, will still display as Exit because users of Win>Mac && Win>Lin
-add Edit>Paste (oddly, it wasn't even in docs)
-make Edit>Select All info more correct (will select text *and other items* on
page)
-document new Find Toolbar under correct menu item
-fix an instance of "Find in This Page..." (was missing final three dots)
-add Edit>Preferences to display in docs on Linux
  -in ToC, will display regardless of platform
-add "..." to end of wrongly-named View>Toolbars>Customize
-remove obsolete ref to download manager being in a tab
-mark up a menu path in docs
-make tone of Reload entry more consistent with rest
-remove text about how View Source will be possible externally in Firefox 1.0+
  -not needed, would look bad for 1.0 release
  -still in place in comment if it's decided it should stay
-grammar fix for Back/Forward entries
  -also made toolbar ref consistent with others by removing "navigation"
-tweak JS Console entry's tone to be consistent (information mostly the same)
-make Tools>Options appear in docs on non-Linux
-For IE Users is noted as Windows/Mac only
-Release Notes entry is apparently gone (waiting for absolutely-certain
confirmation from blake, tho it appears it's so cuz made a week ago)
  -commented out to make reinsertion easy if necessary
-document "Tell a Friend" and "Promote Firefox" (new entries)
  -because sites won't be live until 1.0PR, descriptions are intentionally
vague
-a billion fixes for "web site"/"web page" terminology corrections, courtesy of
bug 249231


Rationale for decisions:

If an item is expected at a certain location for the platform but is expected
at another location on another platform (Prefs vs. Opts), hide and display for
only the appropriate platforms.  Why?  If you're on Windows, you expect
Tools>Options.	If you're on Linux, you expect Edit>Preferences.  You're not
likely to go looking for an item in the wrong location and click on it (to find
nothing relevant is displayed when you open the location in the ToC).  Thus,
the confusion this will cause is more minimal.

If an item is not expected or is expected for a specific platform, always
display it but mention it as platform-specific.  Why?  If a user on an
unsupported platform accesses it through the ToC out of curiosity, its not
being there will be confusing.	It's better to always show it and explain than
to not have it show and cause confusion.  The user on the supported platform
won't know the difference.

If an item is platform-specific, don't add a mention to that effect in ToC. 
Why?  It'll clutter the look, and for some entries the look will get really
wide.  For example, [Help>For Internet Explorer Users] would have the ToC
hierarchy:

Menu Reference
|->Help
   |->For Internet Explorer Users (Windows and Mac Only)

It'll get fugly.  Additionally, the ToC entry then won't represent the menu
item as closely as it probably should.	The only exception (and it's a lateral
one that's not a platform issue, oddly) is for File>Close (Window), where I've
put " (Window)" in because I think it's not confusing enough to matter.

THE ONLY thing not fixed is documentation of the Window menu on Mac (discovered
by viewing the XUL file in lxr).  I was going to see if someone was on IRC who
could help, but it's too late for me to do that tonight/this morning.  If
someone wants to do a followup patch that's probably the best option.  My
secondhand docs wouldn't be as good as another's firsthand docs, anyways. 
(Besides, Mac users really shouldn't need the Window menu documented, but at
least to me Help is all about anality.)

Comment 8

[Steffen Wilberg]

Comment on attachment 155666 [details] [diff] [review]
Patch for everything except Window menu on Mac

>Index: menu_reference.xhtml
>-  <h3 id="close">Close Window</h3>
>+  <h3 id="close">Close (Window)</h3>
Excellent idea.

>-  <h3 id="print_preview">Print Preview</h3>
>+  <h3 id="print_preview">Print Preview (Windows and Linux Only)</h3>
Why do you capitalize "Only" (here and in for_ie_users)?

>+  <h3 id="paste">Paste</h3>
>+  <p>Pastes text stored in the clipboard into a web form.</p>
...or into the location bar, or the search bar, or the find bar!
How about just "Pastes text stored in the clipboard"?

>+<div class="mac">
>+
>+<h2 id="window">Window</h2>
We shouldn't add the "Window" heading as long as we don't have content for
that. Just replace that by a comment.

r=me with these fixed.

Comment 9

[Steffen Wilberg]

This depends on bug 254508 (css platform classes).

Comment 10

[Jeff Walden (gone starting June 8)]

Attachment: Previous patch w/comments addressed

(In reply to comment #8)
> >-  <h3 id="print_preview">Print Preview</h3>
> >+  <h3 id="print_preview">Print Preview (Windows and Linux Only)</h3>
> Why do you capitalize "Only" (here and in for_ie_users)?

Two reasons: first, there were situations like this in the menu reference
before, and "Only" was capitalized in those locations.	Second, I saw it as
something that probably should be fixed, but given the time crunch I decided it
wasn't worth wasting time with that extra little change.  I've reverted all the
"Only" instances to "only" in the updated patch for you to check into the tree.


> >+  <h3 id="paste">Paste</h3>
> >+  <p>Pastes text stored in the clipboard into a web form.</p>
> ...or into the location bar, or the search bar, or the find bar!
> How about just "Pastes text stored in the clipboard"?

In my opinion your wording would be inaccurate if the cursor isn't in a text
field, because nothing would be pasted.  Additionally, the information about
Undo, Cut, and Delete references the text as stored in a web form, so it was
for consistency.  Removing "web form" completely for all the affected entries
would be inaccurate, because Undo doesn't apply if the last action was to move
to a new site and Cut/Paste don't work if text on the page but not in a form is
selected.  "text field" is more accurate, and we've got several references to
filling in "fields" in Help anyways, so I'll use that to fix the affected
entries.

> >+<div class="mac">
> >+
> >+<h2 id="window">Window</h2>
> We shouldn't add the "Window" heading as long as we don't have content for
> that. Just replace that by a comment.

I removed the div and h2 and left the comment (with an extra line to mention
that the undocumented menu is Window).

Two other bugs I noticed while tweaking: the entry for Web Search has a
sentence ending in a preposition and has "Web" uncapitalized (I should probably
make that a dictated spelling), and Work Offline is missing a period at the end
of a sentence.	I've fixed both errors.

The tweaked patch is attached for checkin.

Comment 11

[R.J. Keller]

Comment on attachment 155758 [details] [diff] [review]
Previous patch w/comments addressed

r=[e-mail]. I'll check this in.

Comment 12

[R.J. Keller]

Fix checked in.