Copyedit of pageAction.html. Also some bracket fixes to manifest.html.

TEST=none
BUG=none
TBR=aa

Review URL: http://codereview.chromium.org/300042

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@29715 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 80 insertions, 58 deletions

diff --git a/chrome/common/extensions/docs/pageAction.html b/chrome/common/extensions/docs/pageAction.html
index eb96f53..f1bf2c4 100644
--- a/chrome/common/extensions/docs/pageAction.html
+++ b/chrome/common/extensions/docs/pageAction.html
@@ -159,21 +159,21 @@
           <p>Contents</p>
           <ol>
             <li jsinstance="0">
-              <a href="#icons">Icons</a>
+              <a href="#manifest">Manifest</a>
               <ol>
                 <li jsinstance="*0" style="display: none; ">
                   <a>h3Name</a>
                 </li>
               </ol>
             </li><li jsinstance="1">
-              <a href="#H2-1">Style Guide</a>
+              <a href="#ui">Parts of the UI</a>
               <ol>
                 <li jsinstance="*0" style="display: none; ">
                   <a>h3Name</a>
                 </li>
               </ol>
             </li><li jsinstance="*2">
-              <a href="#manifest">Manifest</a>
+              <a href="#tips">Tips</a>
               <ol>
                 <li jsinstance="*0" style="display: none; ">
                   <a>h3Name</a>
@@ -239,10 +239,20 @@
         <div id="static"><div id="pageData-title" class="pageData">Page Actions</div>
 
 <!-- BEGIN AUTHORED CONTENT -->
-<p>Page actions are a simple way to represent actions that can be taken on a page ("Email this page", "Share with Facebook", etc).</p>
+<p>
+Use page actions to put icons inside the address bar.
+Page actions represent actions
+that can be taken on the current page,
+but that aren't applicable to all pages.
+Some examples:
+"Subscribe to this page's RSS feed",
+"Make a slideshow out of this page's photos".
+<span class="comment">
+[PENDING: check]
+</span>
+</p>
 
 <p>
-Page actions are displayed as icons on the right side of the OmniBox.
 The RSS icon in the following screenshot
 represents a page action
 that lets you subscribe to
@@ -251,48 +261,78 @@ the RSS feed for the current page.
 
 <img src="images/page-action.png" width="361" height="79">
 
-<h2 id="icons">Icons</h2>
+<p>
+If you want your icon to always be visible,
+use a <a href="browserAction.html">browser action</a> instead.
+</p>
+
+
+<h2 id="manifest">Manifest</h2>
+
+<p>
+Register your page action in the
+<a href="manifest.html">extension manifest</a>
+like this:
+</p>
+
+<pre>"page_action": {
+  "default_title": "Do action",   <em>// optional; shown in tooltip</em>
+  "default_icon": "icons/foo.png" <em>// optional</em>
+}</pre>
+
+<p><b>Note:</b> Even if you don't include
+  any of the values,
+  you must include an empty <b>page_action</b> entry
+  in your manifest so that the system
+  reserves space for your page action
+  in the address bar.</p>
+
+<h2 id="ui">Parts of the UI</h2>
 
-<p>Page action icons can be
-up to 19px square.
-Larger icons will be
-resized to fit,
-but for best results,
-using a 19px icon is recommended.</p>
+<p>
+Page actions have the same UI parts as browser actions —
+icon, tooltip, badge, and popup —
+with the addition that page actions can appear and disappear.
+For information about the common UI parts,
+read about the
+<a href="browserAction.html#ui">browser action UI</a>.
+</p>
 
-<p>Icons can be set two ways:
-using a static image
-or using the HTML5 <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html">canvas element</a>.
-Using static images is easier
-for simple applications,
-but you can do
-more dynamic UIs
-using the canvas element.
+<p>
+You make a page action appear and disappear using the
+<a href="#method-hide">hide()</a> and
+<a href="#method-show">show()</a> methods, respectively.
+</p>
+
+<div class="comment">
+[PENDING:
+We should discuss how tabs and page actions are related.
+All methods take a tab ID argument.
+How do you get that tab ID?
+What's the usual way of arranging the code that monitors pages?
+Point to examples.]
+</div>
 
-</p><p>Static images can be
-in any format WebKit can display.
-These include: png, bmp, ico, jpg, gif.</p>
 
-<a name="H2-1"></a><h2>Style Guide</h2>
+<h2 id="tips">Tips</h2>
 
 <p>For the best visual impact,
-we recommend observing
-the following guidelines:</p>
+follow these guidelines:</p>
 
 <ul>
   <li><b>Do</b> use page actions
-    for features that only make sense
-    for a few pages.
+    for features that make sense
+    for only a few pages.
   </li><li><b>Don't</b> use page actions
     for features that make sense
     for most pages.
     Use <a href="browserAction.html">browser actions</a> instead.
   </li><li><b>Do</b> use icons
-    that are slightly lighter-weight
-    than <a href="browserAction.html#icons">browser action icons</a>.
+    that are slightly lighter weight
+    than <a href="browserAction.html#icon">browser action icons</a>.
     Most icons that Chrome displays
     in the location bar
-    are smaller than 19px.
+    are smaller than 19 pixels.
     If the edge pixels are used,
     they are usually only used
     for a faint shadow.
@@ -300,24 +340,6 @@ the following guidelines:</p>
     That's just annoying.
 </li></ul>
 
-<h2 id="manifest">Manifest</h2>
-
-<p>Developers can declare page actions
-  in the manifest
-  using the following syntax:</p>
-
-<pre>"page_action": {
-  "default_title": "Do action",  // Optional, tooltip.
-  "default_icon": "icons/foo.png"  // Optional, icon.
-}</pre>
-
-<p><b>Note:</b> Even if you don't include
-  any of the values,
-  you must include an empty page_action entry
-  in your manifest so that the system knows
-  to reserve space for your action
-  in the omnibox.</p>
-
 <!-- END AUTHORED CONTENT -->
 </div>
 
@@ -361,7 +383,7 @@ the following guidelines:</p>
 
               <div class="description">
                 <p class="todo" style="display: none; ">Undocumented.</p>
-                <p>Hide the page action.</p>
+                <p>Hides the page action.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
@@ -573,7 +595,7 @@ the following guidelines:</p>
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>An array of four integers in the range [0,255] that make up the ARGB color for the text of the badge.</dd>
+          <dd>An array of four integers in the range [0,255] that make up the ARGB color of the badge. For example, opaque red is [255, 255, 0, 0].</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -634,7 +656,7 @@ the following guidelines:</p>
 
               <div class="description">
                 <p class="todo" style="display: none; ">Undocumented.</p>
-                <p>Sets the badge text for the page action. This is printed on top of the icon.</p>
+                <p>Sets the badge text for the page action. The badge is displayed on top of the icon.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
@@ -988,7 +1010,7 @@ the following guidelines:</p>
 
               <div class="description">
                 <p class="todo" style="display: none; ">Undocumented.</p>
-                <p>Sets the icon for the page action. The icon can be specified either as the index of one of the icons that was pre-specified in the manifest, or as the pixel data from a Canvas element. Either the path or the imageData property must be specified.</p>
+                <p>Sets the icon for the page action. The icon can be specified either as the path to an image file or as the pixel data from a canvas element. Either the <b>path</b> or the <b>imageData</b> property must be specified.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
@@ -1099,7 +1121,7 @@ the following guidelines:</p>
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>Pixel data for an image. Must be an ImageData object (eg from a <code>canvas</code> element).</dd>
+          <dd>Pixel data for an image. Must be an ImageData object (for example, from a canvas element).</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -1140,7 +1162,7 @@ the following guidelines:</p>
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd><b>Deprecated.</b> The zero-based index into the |icons| vector specified in the manifest.</dd>
+          <dd><b>Deprecated.</b> The zero-based index into the <b>icons</b> vector specified in the manifest.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -1201,7 +1223,7 @@ the following guidelines:</p>
 
               <div class="description">
                 <p class="todo" style="display: none; ">Undocumented.</p>
-                <p>Set the title of the page action. This is displayed in a tooltip over the page action.</p>
+                <p>Sets the title of the page action. This is displayed in a tooltip over the page action.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
@@ -1373,7 +1395,7 @@ the following guidelines:</p>
 
               <div class="description">
                 <p class="todo" style="display: none; ">Undocumented.</p>
-                <p>Show the page action. The page action is shown whenever the tab is selected.</p>
+                <p>Shows the page action. The page action is shown whenever the tab is selected.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
@@ -1474,7 +1496,7 @@ the following guidelines:</p>
 
               <div class="description">
                 <p class="todo" style="display: none; ">Undocumented.</p>
-                <p>Fired when a page action button is clicked.</p>
+                <p>Fired when a page action icon is clicked.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>