153671 - Navigator Help - some corrections

Status: VERIFIED FIXED

(Documentation Graveyard :: Help Viewer, defect, P1)

Description

[Blake Ross]

I went through the Navigator help and found some mistakes. I know Help is
changing constantly, and it's not finished, but hopefully this helps.  I tried
to focus mainly on mistakes in accuracy.

> 1. Click the Location Bar to select the URL that is already there.

On Unix machines, clicking the location bar just places the caret; it does not
auto-select (because of the autocopy behavior).   This also makes step 2
incorrect on Unix.

> Tip: To quickly select the URL in the Location Bar, press Ctrl+L.

It's Cmd+L on Mac.

> Tip: To quickly open the history list, press Ctrl+H.

It's Cmd+Shift+H on Mac.

This is really outside the scope of this bug, but would it be possible for you
to add help content explaining the difference between the Location bar
autocomplete list (which is global history) and the Location bar history list
(which is a separate list, accessible via the down arrow)?  We've gotten many
complaints from users who thought that the Clear Location Bar history button
would clear the autocomplete list.

The history section does not mention that you can now select a folder and hit
delete to delete everything it contains. This is new since 6.2, and since Help
mentions all the other types of deletion, it should probably mention this one.

> To refresh the current page, or get the most up-to-date version, click
> Reload button, or press Ctrl+Shift+R (Cmd+Shift+R on Mac OS).

This is technically not correct.  Clicking the Reload button is equivalent to
Ctrl+R.  Shift+Clicking the Reload button is equivalent to Shift+Ctrl+R.  I
recommend just putting the Ctrl+R (Cmd+R) shortcut, since Ctrl+Shift+R is hidden.

>  (You default search engine may be different.)

Typo, should be "your".

>    1.  If it is not already open, open My Sidebar by clicking its handle.

This is misleading.  Most people probably don't collapse their sidebar, because
that's not discoverable.  Odds are that if the sidebar isn't visible, they'll
need to hit F9 or go to View > Show/Hide > My Sidebar to open it.

>    2. Right-click and choose "Web Search for [your selected words]" for
> the menu. (To right-click on Mac OS, press Ctrl and click the mouse button.)

It's Cmd and click, not Ctrl and click.


> Under Sidebar Search Tab Preferences, click Advanced, and then OK.

The wording is "Preference" (no trailing s).

> If it is not already open, open My Sidebar by clicking its handle.

See above.

> To find the same word or phrase again: Open the Edit menu and choose
> Find Again.

You may want to add a tip that Ctrl+G (Cmd+G on Mac) can be used to find again
more quickly.

> Tip: To quickly open your Bookmarks menu, press Ctrl+B. 

It's Cmd+B on Mac.  Also, the term "Bookmarks menu" is a little misleading to me
-- it's opening the Bookmarks manager window, not the Bookmarks menu -- but you
know best about end-user terminology.

> To open the History list quickly, press Ctrl+H.

It's Cmd+Shift+H on Mac.

> (On Mac OS, press Ctrl and click the mouse button.)

It's Cmd and click.

> Under "Installed languages packs" select a language pack.

The wording is "language", without the trailing s.

> JPEG, GIF, PNG, and MNG

Also BMP and ICO.

> To learn how to turn off JavaScript, see Advanced Preferences - Scripts
> & Windows.

This panel is now called Scripts & Plugins.

Comment 1

[Daniel Wang]

*** Bug 153800 has been marked as a duplicate of this bug. ***

Comment 2

[Daniel Wang]

from bug 153800

> Find Again    Ctrl+G or F3

F3 does not work in our app.

> Save Linked Page (when a link is selected)   Shift+Enter

You should also mention that Ctrl+Enter (cmd+enter) opens the
selected link in a new tab or window (depending on your prefs).

Comment 3

[Daniel Wang]

Attachment: new image: browse-history-session

Comment 4

[Daniel Wang]

Attachment: new image: browse-history-sidebar

Comment 5

[Daniel Wang]

Attachment: replacement img: locationbar.png

Comment 6

[Daniel Wang]

Attachment: nav_help.html

Comment 7

[rudman]

-->robin.

cc'ing Ian.

Comment 8

[Daniel Wang]

Attachment: nav_help.html (add Type Ahead Find)

add stuff for bug 182186 (& "type ahead find" search keyword)

Comment 9

[Daniel Wang]

Attachment: patch

Comment 10

[R.J. Keller]

--> me

don't think that robin works on mozilla anymore.

Comment 11

[R.J. Keller]

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

Note that I'm not giving you review because this patch is old and corrections
need to be made.

> +<p>JPEG, GIF, PNG, MNG, BMP and ICO.</p>

MNG support is not in mozilla.

I'm dont' know if MacOS is Cmd or Control, but I'm pretty sure you're right
Daniel.

Also, remove the copyright change. Don't think that the date change is needed
either.

Comment 12

[R.J. Keller]

--> Daniel Wang

Comment 13

[R.J. Keller]

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

Daniel, you going to update this patch? I'll check it in once you apply my
comments in comment #11 (which should be quick).

Comment 14

[Daniel Wang]

Attachment: updated patch

search_personal_toolbar.gif is deprecated, please remove.

This patch depends on the first 3 image attachments. Please remember to check
'em in as binary files.

Help on type-ahead-find added. You might wanna check if it agrees with the
firebird help content (if you have it).

Please hold all other patches for nav_help.html. I don't want to redo this
again.

Need to investigate: the page assumes the default search engine to be Netscape
Search. Is this true?

Comment 15

[Daniel Wang]

Blake Ross, a review from you would be also appreciated :-)

Keller, and remember to update TOC for type-ahead-find

Comment 16

[R.J. Keller]

> +<kbd>Ctrl+L</kbd> (<kbd>Cmd+L</kbd> on Mac OS).</p>

<kbd>? What the heck is that? We shouldn't have any of these <kbd> tags (not
sure what they do).

BTW, Blake is neither a peer of help nor does he receive bugmail ;), so I doubt
you'd get one from him. I don't know his knowledge well enough to allow him to
review.

Comment 17

[Daniel Wang]

Keller, not enough caffine? http://mozdev.org/bugs/show_bug.cgi?id=4764

Blake can't do r+ on patches, but he can certainly comment and do r- :-)

Comment 18

[R.J. Keller]

I'd prefer to do this change in a different bug than here. As it says in the
bug, this would require a CSS change. If you want this, file a new bug for it.

Comment 19

[Daniel Wang]

Comment on attachment 133457 [details] [diff] [review]
updated patch

why does this need a CSS change? <kbd> defaults teletype font (same as <tt>). I
looked at firebirdhelp and don't find any CSS definition for kbd

Comment 20

[R.J. Keller]

Comment on attachment 133457 [details] [diff] [review]
updated patch

+<li><p>
+    To go back or forward one page, click the <b>Back</b> or <b>Forward</b>
arrow.
+    </p>
+</li>
+<li><p>


Why do we have <p> tags? Remove them. You also created a p tag that doesn't
have an end tag. I'd prefer to have no <p> tags in <li> tags. it causes
problems.


+<<<<<<< nav_help.html
+<li><b>Web Page, Complete</b>: Save the whole web page, along with images
+and other supporting files. This option allows you to view it as originally
+displayed with images. Mozilla creates a new 
+directory (where the page is saved) to save images and other files necessary 
+=======


What the heck is this? Looks like something went wrong. I see this in a lot of
spaces in your patch


+<a id="Type_Ahead_FindSDX"></a><a id="Find_as_you_typeSDX"></a>


put one anchor per line to keep consistency.


+   <li><p>To search for a link, type several characters into the
+	active browser window to navigate to any link with that
+	text in it.</p>


Let's just do <li>, then do <br><br> for the extra line breaks. I've ran into a
lot of problems with having <p> tags in <li> tags.


+<li><li>To open the History list quickly, press <kbd>Ctrl+H</kbd>
(<kbd>Cmd+Shift+H</kbd> on Mac OS).</li>


Why are you starting two <li> tags? Also, you should have
<kbd>Ctrl</kbd>+<kbd>H</kbd> instead of <kbd>Ctrl+H</kbd> to keep consistency
with firebird help


+Preferences - Scripts &amp; Plug-ns</a>.</p>

Spelling error. It's plug-ins.

Comment 21

[Daniel Wang]

Attachment: nav_help.html patch

Fix many little mistakes. Add Mac OS shortcuts. Correct most markup errors. Use
the new stylesheet. Add contents on find-as-you-type.

I didn't fix all markup errors, but after this, you should be able to convert
nav_help.html to .xhtml w/o much problem.

Comment 22

[Daniel Wang]

Attachment: help-index1.rdf patch - add find-as-you-find to Index

Comment 23

[Daniel Wang]

Attachment: helpFileLayout.css patch - add kbd style

<kbd> default size too small on Windows. I think Linux people have the same
problem.

Comment 24

[R.J. Keller]

Comment on attachment 133655 [details] [diff] [review]
helpFileLayout.css patch - add kbd style

r=[e-mail]

The other patch is really long, so I'll probably not get done reviewing it
tonight.

Comment 25

[Christopher Aillon (sabbatical, not receiving bugmail)]

Comment on attachment 133654 [details] [diff] [review]
help-index1.rdf patch - add find-as-you-find to Index

This looks right, but I am not up to date on my RDF-fu.  You should probably
get someone else to fully review this.	The only thing I would nit about is to
put your nc prefixed attributes on the same column (even though the file seems
to like doing it weirdly.  Two wrongs don't make a right, and all that.)

Comment 26

[R.J. Keller]

Comment on attachment 133654 [details] [diff] [review]
help-index1.rdf patch - add find-as-you-find to Index

Caillon: FYI, see bug 218878 for RDF problem you describe.

Daniel: I'll do this one while I'm doing the other patch. The 2 patches connect
too much to be efficiently reviewed by different reviewers.

Comment 27

[R.J. Keller]

Comment on attachment 133653 [details] [diff] [review]
nav_help.html patch

This is good stuff, Daniel! Got some problems, however.

> +<p>&nbsp;</p>
>  
>  <hr>

remove this.

> +</div>
> +
>  <p>&nbsp;</p>
> -<a NAME="Navigator:home_pageIDX"></a>

remove

> +<!-- ********************************** DANIEL's TO-DO ********************************** -->

What the heck is this? This is very inappropriate for the help files. You can
do this:
<!-- XXXDaniel: ToDo --> and I'll let it slide.

> +    <br><img src="images/browse-history-sidebar.png" alt="History sidebar">

You should have a <br> tag at the end. I recommend having two <br> tags at the
beginning and two in the end.

> +<!-- we don't need the table after we update the images to classic
> +     can't change to .png now because customize_help.html is also using it -->
> +<p>
> +<img src="images/reload.gif"
> +     alt="Navigation Buttons"> 
> +</p>

True, but we haven't changed the images yet, and we probably won't have them
changed for 1.6a, so remove this and put the table back.

>  <p>Sidebar is a customizable frame in your browser where you can keep items 
>  that you need to use all the time&#151;the latest news and weather, your address 
> -book or Buddy List, stock quotes, a calendar&#151;and many other available options. 
> +book, stock quotes, a calendar&#151;and many other available options. 

We shouldn't be referencing Netscape stuff like stock quotes. How about
replacing with this:

"that you need to use all the time&#151;your bookmarks, history, Address Book,
and even
some websites."

This is obviously not the best wording, but do you see the point I'm trying to
make?

> +<p>Other than searching text through a dialog window, you can also

let's say "searching text through the Find dialog, you can also" instead of
saying "a dialog window".

> +<ol>
> +   <li>
> +     To search for a link, type several characters into the
> +     active browser window to navigate to any link with that
> +     text in it.
> +
> +     <p>If you repeat the same character, it will start to cycle
> +     through all the links that begin with that character.
> +     However, if it can find a match with the exact string
> +     you've typed, such as <q><tt>oo</tt></q> in
> +     <q><tt>woods</tt></q> it will go there first.
> +   </li>

This <p> tag doesn't have an end tag. You should use two <br> tags instead>

> +   <li>
> +     To search for all text (normal text and link text), type
> +     <kbd>/</kbd> before your search string, for example,
> +     <q><kbd>/hello</kbd></q>.
> +   </li>

Change this:
"(normal text and link text)" => "(normal text and linked text)"
"before your search string, for example," => "before your search string. For
example:"

> +   <li>
> +     Use the backspace key to undo the last character typed
> +   </li>
> +   <li>
> +     To cancel a find, change focus or scroll, press Escape, or
> +     wait for the timeout
> +   </li>

Add a period to the end of the sentences in these two bullets.

@@ -635,20 +671,19 @@
     to define your search. 

>  <li><a name="search_options"></a>Choose from the following search options: 
> -</ol>
> -<ul>
> -<li>Choose &quot;title&quot; or &quot;location&quot; to choose where you would 
> +    <ul>
> +      <li>Choose &quot;title&quot; or &quot;location&quot; to choose where you would 
>  like to search. (The bookmarks window allows searching &quot;name,&quot; &quot;description,&quot; 
>  and &quot;keyword&quot;.) 
> -<li>Choose "contains," "starts with," or "ends with" if you know only part of 
> +      <li>Choose "contains," "starts with," or "ends with" if you know only part of 
>  the word or phrase for which you're searching. </li>
> -<li>Choose "is" if you know exactly what you're searching for. 
> -<li>Choose "is not" or "doesn't contain" to exclude pages.</li>
> -<li>Click in the field and type all or part of word or URL (web address) for 
> +      <li>Choose "is" if you know exactly what you're searching for. 
> +      <li>Choose "is not" or "doesn't contain" to exclude pages.</li>
> +      <li>Click in the field and type all or part of word or URL (web address) for 
>  the bookmarks or history listings that you want to find or exclude.</li>
> -</ul>
> -<ol start="5">
> -<li>Click Find. History listings that match your search criteria are displayed 
> +    </ul>
> +  </li>
> +  <li>Click Find. History listings that match your search criteria are displayed 
>      in the Search Results window. </li>
>  </ol>
>  <p>To use the search results:</p>

You got some whitespace problems here. Please correct.

> -<p>To customize how pages are printed in Mozilla, you can use Page Setup:</p>
> -<ul>
> -<li>
> -<p>From Navigator, open the File menu and choose Page Setup.</p>
> -</li>
> -</ul>
> +<p>To customize how pages are printed in Mozilla, you can use Page Setup.
> +From Navigator, open the File menu and choose Page Setup.</p>

I prefered the bullets as opposed to making it a paragraph.

> +      <li>
> +        <b>Orientation</b>: 
> +        Choose the orientation of the paper, either
> +        Portrait
> +        <img src="chrome://communicator/skin/icons/pg-portrait-small.gif" alt="portrait button">
> +        (normal position, with the shorter side facing up) or
> +        Landscape
> +        <img src="chrome://communicator/skin/icons/pg-landscape-small.gif" alt="landscape button">
> +        (sideway position, with the longer side facing up).
> +      </li>

Same as above, I prefer the bullets to the paragraph.

Comment 28

[R.J. Keller]

Comment on attachment 133654 [details] [diff] [review]
help-index1.rdf patch - add find-as-you-find to Index

> +<rdf:Description about="help-indexAZ.rdf#Find_As_You_Type">
>     <nc:subheadings>
>       <rdf:Seq><rdf:li>
> -       <rdf:Description ID="Find_Text_As_You_Type"
> -         nc:name="Find Text As You Type"
> -	 nc:link="cs_nav_prefs_advanced.html#Find_Text_As_You_TypeIDX"/>
> +       <rdf:Description ID="Find_As_You_Type_Pref"
> +         nc:name="Find As You Type - preferences"
> +	 nc:link="cs_nav_prefs_advanced.html#Find_Links_As_You_TypeIDX"/>
>       </rdf:li></rdf:Seq>
>     </nc:subheadings>
>  </rdf:Description>

Capitalize the p in "preferences"

> +<rdf:Description about="#Navigator">
> +   <nc:subheadings>
> +     <rdf:Seq><rdf:li>
> +       <rdf:Description ID="Navigator:controlling_popups"
> +         nc:name="controlling popups"
> +	 nc:link="nav_help.html#full_screen_mode"/>
> +     </rdf:li></rdf:Seq>
> +   </nc:subheadings>
> +</rdf:Description>

What does Pop-ups have to do with Full Screen Mode?

> +<rdf:Description about="help-indexAZ.rdf#Type_Ahead_Find">
> +   <nc:subheadings>
> +     <rdf:Seq><rdf:li>
> +       <rdf:Description ID="Type_Ahead_Find_Pref"
> +         nc:name="Type Ahead Find - preferences"
> +	 nc:link="cs_nav_prefs_advanced.html#Find_Links_As_You_TypeIDX"/>
>       </rdf:li></rdf:Seq>
>     </nc:subheadings>
>  </rdf:Description>

Same as above, capitalize the p in "preferences"

Comment 29

[Christopher Aillon (sabbatical, not receiving bugmail)]

N.B.: <p> is generally preferred above <br><br> especially when you really want
to denote a new paragraph as the case is here.  And, yes, <p> is legal in <li>.

Comment 30

[Daniel Wang]

Attachment: nav_help.html patch v2

(bug 153671) Fix many little mistakes. Update contents and simplify some
language. Add Mac OS shortcuts. Correct most markup errors. Use the new
stylesheet. Add contents on find-as-you-type. Readying file for xhtml
conversion.

>> +<p>&nbsp;</p>
>>  
>>  <hr>
>
> remove this.

okay.

>> +</div>
>> +
>>  <p>&nbsp;</p>
>> -<a NAME="Navigator:home_pageIDX"></a>
>
> remove

not okay. This patch is about fixing some errors and adding type-ahead-find
contents. Anything that deals with markup error in the original should be in
another bug.

>> +	<br><img src="images/browse-history-sidebar.png" alt="History sidebar">

>
> You should have a <br> tag at the end. I recommend having two <br> tags at
the
> beginning and two in the end.

I prefer <img class="screenshot"> and .screenshot { display: block; }. But this
is not the bug to discuss this.

Removing all tables because they cause visual problem with the new CSS.

Comment 31

[Daniel Wang]

Attachment: help-index1.rdf patch - v2

Comment 32

[R.J. Keller]

Comment on attachment 133791 [details] [diff] [review]
help-index1.rdf patch - v2

r=[e-mail].

Much better!

Comment 33

[R.J. Keller]

Comment on attachment 133788 [details] [diff] [review]
nav_help.html patch v2

> not okay. This patch is about fixing some errors and adding type-ahead-find
> contents. Anything that deals with markup error in the original should be in
> another bug.

The problem is that you're changing the CSS from the old stylesheet to the new
one. If you're going to do that, you need to remove the <hr> tags and <p> tags
because the stylesheet does that (instead of needing extra HTML).

> +    <br><img src="images/browse-history-sidebar.png" alt="History sidebar">

You never added the <br> after the image.

> +
> +<!-- XXXDaniel: the new style sheet cause visual problem with table. -->
> +<p>
> +<img src="images/reload.gif"
> +     alt="Navigation Buttons"> 
> +</p>
> +

Why is this not changed back to the table with the buttons labeled? If you are
having visual problems with the CSS, make a new class in the helpFileLayout.css
that won't cause the problems.

I stopped reviewing because I noticed that most of my previous comments aren't
in this patch.

Comment 34

[R.J. Keller]

Daniel, got any status on this? I'd really like this for 1.6b.

Comment 35

[Daniel Wang]

Attachment: nav_help.xhtml patch

patch, with limited bug scope. Keller, you need to fix help-index1.rdf
yourself.

Comment 36

[R.J. Keller]

Daniel, one question. Why are you modifying the nav_help.xhtml when we're using
the HTML? I don't see any conversions to XHTML (doctype, css, etc).

Comment 37

[Daniel Wang]

I was under the impression that .xhtml is being used (there was no nightly
build, so I couldn't know). No matter, you can change "nav_help.xhtml" to
"nav_help.html" and the patch will still apply happily :-)

Comment 38

[R.J. Keller]

Attachment: same as above, with typo fixed.

OK, daniel. This is the same patch with the XHTML changed to HTML.

Comment 39

[R.J. Keller]

Comment on attachment 135148 [details] [diff] [review]
nav_help.xhtml patch

r=rlk

Looks great! What ever happened to the new CSS stuff?

Comment 40

[R.J. Keller]

Fix checked in, but not sure if this fixes all of the bug or not, since the
patch looks much smaller than the previous one. Daniel, if it does, then resolve
the bug as FIXED.

Comment 41

[Daniel Wang]

-> fixed.
rest of previous patch can wait in a new bug.

Comment 42

[R.J. Keller]

VERIFIED