287203 - document new Options window, using_firefox.xhtml part

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Steffen Wilberg]

I'm filing a new bug since bug 279506 is already pretty long.

These sections of using_firefox.xhtml need an update:
- Plug-ins
- Helper Applications
- Making Firefox Your Default Browser
- Changing Cache Settings

Comment 1

[Steffen Wilberg]

Working on it.

Comment 2

[Steffen Wilberg]

Attachment: patch v1

Bleh, this was more work than expected. The part on plug-ins and helper
applications was a bit too technical. I also replaced "plug-ins" by "Plugins"
to be consistent with the UI, and "helper applications" by "external
applications" because that's clearer.
I need to make those changes in the glossary as well if you're ok with them.

Comment 3

[Jeff Walden (gone starting June 8)]

Comment on attachment 178706 [details] [diff] [review]
patch v1

>-<p>Welcome to &brandFullName;! &brandFullName; is an Internet browser that
>+<p>Welcome to &brandFullName;! &brandShortName; is an Internet browser that

I thought your proposed change was visually discontinuous when I was evaluating
it.  What do you think of it?

>+  that can handle those files. If &brandShortName; doesn't have the needed
>+  Plugin or doesn't know an application to open the file with, it can still

s/an application to open the file with/what application to use to open the
file/

>+<p>Plugins extend the functionality within &brandShortName; and run within it.

s/the functionality of &brandShortName;/&brandShortName;'s functionality/

>+  movies, animations, and games. A number of common Plugins you can install is
>+  listed at the <a href="https://pfs.mozilla.org/plugins/" target="_blank">
>+  Plugins page</a> at Mozilla Update.</p>

The last sentence is pretty awkward.  Instead of it, let's try, "You can find
common Plugins on the <a>Plugins page</a> at Mozilla Update."

>+<p>When files cannot be opened within &brandShortName;, you can choose to open
>+  them with applications outside of &brandShortName;. For example, to play MP3
>+  files, programs like Winamp can be used.</p>

How about, "For example, you can use your chosen media player to play MP3
files."?  This avoids excessive use of commas and is a more active sentence
than the original change.

>+<p>You can specify how &brandShortName; handles files it can't display out of
>+  the box in the <em>Download Actions</em> dialog. Click the <em>View &amp; Edit
>+  Actions...</em> button in the <em>Downloads</em> panel of &pref.menuPath; to

"out of the box" is unnecessary.  Also, rearrange this sentence so the menu
path is before the 

>-<p>The download dialog box has these choices:</p>
>+<p>When you click on a file and &brandShortName; doesn't know how to handle it,
>+  it displays a <em>Opening</em> dialog box, which offers these choices:</p>

The "it" is unclear here.  Perhaps you can be better at coming up with a fix
for this than I am right now.

>-<p>To make &brandShortName; your default web browser, select &pref.menuPath;.
>-  You can then click on the <em>Set Default Browser</em> button in the General
>-  panel of &pref.pluralCaps; to make &brandShortName; your default web browser.</p>
>+<p>To make &brandShortName; your default web browser, select &pref.menuPath;
>+  and click the <em>Check Now</em> button in the General panel.</p>

We wrap panels in <em/>, don't we?

>-<p>To set the size of the cache or to clear it (Windows and Unix only):</p>
>+<p>To set the size of the cache or to clear it:</p>

Why was the platform-specific reference there before, and how do we know it
doesn't still apply?

>-  <li>Under the <em>Privacy</em> category, click <em>Cache</em> to expand the
>-    list.</li>
>+  <li>Under the <em>Privacy</em> category, click <em>Cache</em> tab.</li>

How about instead, "Open the Privacy panel and click the Cache tab." (with
appropriate markup, naturally)?

>+<p>To reload a page at any time, click the <em>Reload</em> button in
>+    &brandShortName;'s <em>Navigation Toolbar</em>. The computer checks the
>+    Internet to make sure you have the latest version of the page.</p>

What do you think about replacing the second sentence with, "&brandShortName;
checks the Internet to make sure you have the latest version of the current
page and displays the newer version if it exists."?  "The computer" really
isn't very good, and we should replace it.

Anyway, pending response to these issues, particularly the ones where I had no
suggestions, r- for now.

Comment 4

[Jeff Walden (gone starting June 8)]

(In reply to comment #2)
> I also replaced "plug-ins" by "Plugins" to be consistent with the UI, and
> "helper applications" by "external applications" because that's clearer.
> I need to make those changes in the glossary as well if you're ok with them.

Go ahead on this; it sounds like a good idea to me.

Comment 5

[Steffen Wilberg]

(In reply to comment #3)
> (From update of attachment 178706 [details] [diff] [review] [edit])
> >-<p>Welcome to &brandFullName;! &brandFullName; is an Internet browser that
> >+<p>Welcome to &brandFullName;! &brandShortName; is an Internet browser that
> 
> I thought your proposed change was visually discontinuous when I was evaluating
> it.  What do you think of it?
We don't need to repeat it. Like "This is my brother Ben. Ben is a quite nice
guy." You don't repeat that he's your brother in the second sentence.

> >+  that can handle those files. If &brandShortName; doesn't have the needed
> >+  Plugin or doesn't know an application to open the file with, it can still
> 
> s/an application to open the file with/what application to use to open the
> file/
> 
> >+<p>Plugins extend the functionality within &brandShortName; and run within it.
> 
> s/the functionality of &brandShortName;/&brandShortName;'s functionality/
> 
> >+  movies, animations, and games. A number of common Plugins you can install is
> >+  listed at the <a href="https://pfs.mozilla.org/plugins/" target="_blank">
> >+  Plugins page</a> at Mozilla Update.</p>
> 
> The last sentence is pretty awkward.  Instead of it, let's try, "You can find
> common Plugins on the <a>Plugins page</a> at Mozilla Update."
Fixed.


> >+<p>When files cannot be opened within &brandShortName;, you can choose to open
> >+  them with applications outside of &brandShortName;. For example, to play MP3
> >+  files, programs like Winamp can be used.</p>
> 
> How about, "For example, you can use your chosen media player to play MP3
> files."?  This avoids excessive use of commas and is a more active sentence
> than the original change.
Fixed with "the media player of your choice".


> >+<p>You can specify how &brandShortName; handles files it can't display out of
> >+  the box in the <em>Download Actions</em> dialog. Click the <em>View &amp; Edit
> >+  Actions...</em> button in the <em>Downloads</em> panel of &pref.menuPath; to
> 
> "out of the box" is unnecessary.  Also, rearrange this sentence so the menu
> path is before the 
Yeah, good suggestion.

> >-<p>The download dialog box has these choices:</p>
> >+<p>When you click on a file and &brandShortName; doesn't know how to handle it,
> >+  it displays a <em>Opening</em> dialog box, which offers these choices:</p>
> 
> The "it" is unclear here.  Perhaps you can be better at coming up with a fix
> for this than I am right now.
How's this:
<p>When you click on a file and &brandShortName; doesn't know how to handle it,
  a <em>Opening</em> dialog box is displayed, offering these choices:</p>


> >-<p>To make &brandShortName; your default web browser, select &pref.menuPath;.
> >-  You can then click on the <em>Set Default Browser</em> button in the General
> >-  panel of &pref.pluralCaps; to make &brandShortName; your default web
browser.</p>
> >+<p>To make &brandShortName; your default web browser, select &pref.menuPath;
> >+  and click the <em>Check Now</em> button in the General panel.</p>
> 
> We wrap panels in <em/>, don't we?
:-)

> >-<p>To set the size of the cache or to clear it (Windows and Unix only):</p>
> >+<p>To set the size of the cache or to clear it:</p>
> 
> Why was the platform-specific reference there before
Ask RJ. It was already in the first revision of this doc. It's bogus. There's
been a Clear button (part of the expander widget) at least since 2003-02-01:
http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/browser/components/prefwindow/content/pref-privacy.xul&rev=&cvsroot=/cvsroot&mark=145-146#145
No #ifdef here, neither in pref-privacy.js.

> and how do we know it doesn't still apply?
There's no #ifdef here:
http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/browser/components/preferences/privacy.xul&mark=256-259#256
The button can be disabled by setting the pref
pref.privacy.disable_button.clear_cache. But that's not the case.


> >-  <li>Under the <em>Privacy</em> category, click <em>Cache</em> to expand the
> >-    list.</li>
> >+  <li>Under the <em>Privacy</em> category, click <em>Cache</em> tab.</li>
> 
> How about instead, "Open the Privacy panel and click the Cache tab." (with
> appropriate markup, naturally)?
Fixed.


> >+<p>To reload a page at any time, click the <em>Reload</em> button in
> >+    &brandShortName;'s <em>Navigation Toolbar</em>. The computer checks the
> >+    Internet to make sure you have the latest version of the page.</p>
> 
> What do you think about replacing the second sentence with, "&brandShortName;
> checks the Internet to make sure you have the latest version of the current
> page and displays the newer version if it exists."?
No, it displays it anyway.

> "The computer" really isn't very good, and we should replace it.
Agreed. And there are pages which are not in the "Internet" but on your disk.
How about: "&brandShortName; then loads and displays the latest version of the
page."

Comment 6

[Steffen Wilberg]

Attachment: patch v2

I also tweaked index and glossary this time.
I removed the entry on helper applications from the glossary, since I've
removed that term from the doc.

Comment 7

[Jeff Walden (gone starting June 8)]

Comment on attachment 179974 [details] [diff] [review]
patch v2

(In reply to comment #5)
> > "out of the box" is unnecessary.  Also, rearrange this sentence so the menu
> > path is before the 

My communication skills in this "sentence" were apparently at less than par. 
That last sentence was supposed to communicate that I wanted the sentence
rearranged so that it was a logical progression, e.g. "Select &pref.menuPath;,
open the <em>Downloads</em> panel, and click the <em>View &amp; Edit
Actions...</em> button to [...]" or something similar.	You apparently grasped
some portion of what I meant because it *was* slightly rearranged, but you
didn't get all of it.

Also, you seem to have a doubled "the" in this paragraph which needs to be
removed.

> How's this:
> <p>When you click on a file and &brandShortName; doesn't know how to handle it,
>   a <em>Opening</em> dialog box is displayed, offering these choices:</p>

Looks good as long as you change "a" to "an" before "<em>Opening</em>".

Comment 8

[Steffen Wilberg]

Attachment: final patch

Final patch, r=jeff per comment 7.
Asa, do we need approval for help docs? We didn't need approval-aviary for
these before we shipped 1.0.

Comment 9

[Asa Dotzler [:asa]]

Comment on attachment 180268 [details] [diff] [review]
final patch

a=asa

Comment 10

[Steffen Wilberg]

Thanks Asa, but that doesn't answer my question (comment 8)...

Comment 11

[Steffen Wilberg]

Checking in mozilla/browser/components/help/locale/en-US/firebird-index1.rdf;
/cvsroot/mozilla/browser/components/help/locale/en-US/firebird-index1.rdf,v  <--
 firebird-index1.rdf
new revision: 1.19; previous revision: 1.18
done
Checking in mozilla/browser/components/help/locale/en-US/firefox_welcome.xhtml;
/cvsroot/mozilla/browser/components/help/locale/en-US/firefox_welcome.xhtml,v 
<--  firefox_welcome.xhtml
new revision: 1.13; previous revision: 1.12
done
Checking in mozilla/browser/components/help/locale/en-US/using_firebird.xhtml;
/cvsroot/mozilla/browser/components/help/locale/en-US/using_firebird.xhtml,v 
<--  using_firebird.xhtml
new revision: 1.22; previous revision: 1.21
done
Checking in
mozilla/toolkit/components/help/helpOnHelp/locale/en-US/firebird-glossary.rdf;
/cvsroot/mozilla/toolkit/components/help/helpOnHelp/locale/en-US/firebird-glossary.rdf,v
 <--  firebird-glossary.rdf
new revision: 1.7; previous revision: 1.6
done
Checking in mozilla/toolkit/components/help/helpOnHelp/locale/en-US/glossary.xhtml;
/cvsroot/mozilla/toolkit/components/help/helpOnHelp/locale/en-US/glossary.xhtml,v
 <--  glossary.xhtml
new revision: 1.8; previous revision: 1.7
done

Comment 12

[Asa Dotzler [:asa]]

Jeff, yes. You need approval. 

Comment 13

[Asa Dotzler [:asa]]

Oops, I mean Steffen. (too early in the morning here for me to be in bugzilla)