More work on browser actions doc.

BUG=none
TEST=none

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

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

3 files changed, 281 insertions, 145 deletions

diff --git a/chrome/common/extensions/api/extension_api.json b/chrome/common/extensions/api/extension_api.json
index 2a60f66..161fde1 100755
--- a/chrome/common/extensions/api/extension_api.json
+++ b/chrome/common/extensions/api/extension_api.json
@@ -790,8 +790,8 @@
             "properties": {
               "tabId": {"type": "integer", "minimum": 0, "description": "The id of the tab for which you want to enable the page action."},
               "url": {"type": "string", "description": "The URL of the page you want the page action to apply to. If the URL specified does not match the currently navigated URL (user has navigated to another page) then no action is taken."},
-              "title": {"type": "string", "optional": true, "description": "Specifying |title| allows you to change the tooltip that appears when you hover over the page action icon in the OmniBox. This parameter is optional and if omitted then the page action |name| property declared in the manifest is used."},
-              "iconId": {"type": "integer", "minimum": 0, "optional": true, "description": "A zero-based index into the |icons| vector specified in the manifest. This parameter is optional and if omitted then the first icon in the |icons| vector of the page action is used. This id is useful to represent different page action states. Example: An RSS feed icon could have a 'subscribe now' icon and an 'already subscribed' icon."}
+              "title": {"type": "string", "optional": true, "description": "Specifying <b>title</b> allows you to change the tooltip that appears when you hover over the page action icon in the OmniBox. This parameter is optional and if omitted then the page action <b>name</b> property declared in the manifest is used."},
+              "iconId": {"type": "integer", "minimum": 0, "optional": true, "description": "A zero-based index into the <b>icons</b> vector specified in the manifest. This parameter is optional and if omitted then the first icon in the <b>icons</b> vector of the page action is used. This id is useful to represent different page action states. Example: An RSS feed icon could have a 'subscribe now' icon and an 'already subscribed' icon."}
             },
             "optional": false
           }
@@ -826,7 +826,7 @@
       {
         "name": "show",
         "type": "function",
-        "description": "Show the page action. The page action is shown whenever the tab is selected.",
+        "description": "Shows the page action. The page action is shown whenever the tab is selected.",
         "parameters": [
           {"type": "integer", "name": "tabId", "minimum": 0, "description": "The id of the tab for which you want to modify the page action."}
         ]
@@ -834,7 +834,7 @@
       {
         "name": "hide",
         "type": "function",
-        "description": "Hide the page action.",
+        "description": "Hides the page action.",
         "parameters": [
           {"type": "integer", "name": "tabId", "minimum": 0, "description": "The id of the tab for which you want to modify the page action."}
         ]
@@ -842,7 +842,7 @@
       {
         "name": "setTitle",
         "type": "function",
-        "description": "Set the title of the page action. This is displayed in a tooltip over the page action.",
+        "description": "Sets the title of the page action. This is displayed in a tooltip over the page action.",
         "parameters": [
           {
             "name": "details",
@@ -857,7 +857,7 @@
       {
         "name": "setIcon",
         "type": "function",
-        "description": "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.",
+        "description": "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.",
         "parameters": [
           {
             "name": "details",
@@ -866,13 +866,13 @@
               "tabId": {"type": "integer", "minimum": 0, "description": "The id of the tab for which you want to modify the page action."},
               "imageData": {
                 "type": "any",
-                "description": "Pixel data for an image. Must be an ImageData object (eg from a <code>canvas</code> element).",
+                "description": "Pixel data for an image. Must be an ImageData object (for example, from a canvas element).",
                 "optional": true
               },
               "iconIndex": {
                 "type": "integer",
                 "minimum": 0,
-                "description": "<b>Deprecated.</b> The zero-based index into the |icons| vector specified in the manifest.",
+                "description": "<b>Deprecated.</b> The zero-based index into the <b>icons</b> vector specified in the manifest.",
                 "optional": true
               }
             }
@@ -882,7 +882,7 @@
       {
         "name": "setBadgeText",
         "type": "function",
-        "description": "Sets the badge text for the page action. This is printed on top of the icon.",
+        "description": "Sets the badge text for the page action. The badge is displayed on top of the icon.",
         "parameters": [
           {
             "name": "details",
@@ -931,7 +931,7 @@
               "tabId": {"type": "integer", "minimum": 0, "description": "The id of the tab for which you want to modify the page action."},
               "color": {
                 "type": "array",
-                "description": "An array of four integers in the range [0,255] that make up the ARGB color for the text of the badge.",
+                "description": "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].",
                 "items": {
                   "type": "integer",
                   "minimum": 0,
@@ -949,7 +949,7 @@
       {
         "name": "onClicked",
         "type": "function",
-        "description": "Fired when a page action button is clicked.",
+        "description": "Fired when a page action icon is clicked.",
         "parameters": [
           {
             "name": "tab",
@@ -966,7 +966,7 @@
       {
         "name": "setTitle",
         "type": "function",
-        "description": "Sets the title of the browser action. Shows up in the tooltip if the browser action is visible, and in the menu item.",
+        "description": "Sets the title of the browser action. This shows up in the tooltip.",
         "parameters": [
           {
             "name": "details",
@@ -983,7 +983,7 @@
       {
         "name": "setIcon",
         "type": "function",
-        "description": "Sets the icon for the browser 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.",
+        "description": "Sets the icon for the browser 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.",
         "parameters": [
           {
             "name": "details",
@@ -991,13 +991,13 @@
             "properties": {
               "imageData": {
                 "type": "any",
-                "description": "Pixel data for an image. Must be an ImageData object (eg from a <code>canvas</code> element).",
+                "description": "Pixel data for an image. Must be an ImageData object (for example, from a <code>canvas</code> element).",
                 "optional": true
               },
               "iconIndex": {
                 "type": "integer",
                 "minimum": 0,
-                "description": "<b>Deprecated.</b> The zero-based index into the |icons| vector specified in the manifest.",
+                "description": "<b>Deprecated.</b> The zero-based index into the <b>icons</b> vector specified in the manifest.",
                 "optional": true
               },
               "path": {
@@ -1012,7 +1012,7 @@
       {
         "name": "setBadgeText",
         "type": "function",
-        "description": "Sets the badge text for the browser action. This is printed on top of the icon.",
+        "description": "Sets the badge text for the browser action. The badge is displayed on top of the icon.",
         "parameters": [
           {
             "name": "details",
@@ -1037,7 +1037,7 @@
             "properties": {
               "color": {
                 "type": "array",
-                "description": "An array of four integers in the range [0,255] that make up the ARGB color for the bakground of the badge.",
+                "description": "An array of four integers in the range [0,255] that make up the ARGB color of the badge. For example, opaque red is <code>[255, 255, 0, 0]</code>.",
                 "items": {
                   "type": "integer",
                   "minimum": 0,
@@ -1055,7 +1055,7 @@
       {
         "name": "onClicked",
         "type": "function",
-        "description": "Fired when a page action button is clicked.",
+        "description": "Fired when a browser action icon is clicked.",
         "parameters": [
           {
             "name": "tab",
diff --git a/chrome/common/extensions/docs/browserAction.html b/chrome/common/extensions/docs/browserAction.html
index 72ecb3c..36a53e9 100644
--- a/chrome/common/extensions/docs/browserAction.html
+++ b/chrome/common/extensions/docs/browserAction.html
@@ -159,35 +159,27 @@
           <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="#badges">Badges</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="#popups">Popups</a>
-              <ol>
-                <li jsinstance="*0" style="display: none; ">
-                  <a>h3Name</a>
-                </li>
-              </ol>
-            </li><li jsinstance="3">
-              <a href="#H2-3">Style Guide</a>
-              <ol>
-                <li jsinstance="*0" style="display: none; ">
-                  <a>h3Name</a>
+                <li jsinstance="0">
+                  <a href="#icon">Icon</a>
+                </li><li jsinstance="1">
+                  <a href="#tooltip">Tooltip</a>
+                </li><li jsinstance="2">
+                  <a href="#badge">Badge</a>
+                </li><li jsinstance="*3">
+                  <a href="#popups">Popup</a>
                 </li>
               </ol>
-            </li><li jsinstance="*4">
-              <a href="#manifest">Manifest</a>
+            </li><li jsinstance="*2">
+              <a href="#H2-6">Tips</a>
               <ol>
                 <li jsinstance="*0" style="display: none; ">
                   <a>h3Name</a>
@@ -247,94 +239,166 @@
         <div id="static"><div id="pageData-title" class="pageData">Browser Actions</div>
 
 <!-- BEGIN AUTHORED CONTENT -->
-<p>Browser actions are buttons
-  that are displayed in the main Chrome toolbar
-  to the right of the omnibox.</p>
+<p>Use browser actions to put icons
+  in the main Google Chrome toolbar,
+  to the right of the address bar.
+  In addition to its <a href="#icon">icon</a>,
+  a browser action can also have
+  a <a href="#tooltip">tooltip</a>,
+  a <a href="#badge">badge</a>,
+  and a <a href="#popup">popup</a>.
+  </p>
+
+<p>
+In the following figure,
+the multicolored square
+to the right of the address bar
+is the icon for a browser action.
+A popup is below the icon.
+</p>
 
 <img src="images/browser-action.png" width="363" height="226">
 
-<h2 id="icons">Icons</h2>
+<p>
+If you want to create an icon that isn't always visible,
+use a <a href="pageAction.html">page action</a>
+instead of a browser action.
+</p>
+
+<p class="comment">
+[PENDING: We should show tooltips and badges, as well.]
+</p>
+
+<h2 id="manifest">Manifest</h2>
+
+<p>
+Register your browser action in the
+<a href="manifest.html">extension manifest</a>
+like this:
+</p>
 
-<p>Browser 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>
+<pre>"browser_action": {
+  "default_title": "Google Mail",      <em>// optional; shown in tooltip</em>
+  "default_icon": "images/icon19.png", <em>// optional</em>
+  "popup": "popup.html"                <em>// optional</em>
+}</pre>
+
+<p><b>Note:</b> Even if you don't include
+  any of the values, you must include an empty
+  <b>browser_action</b> entry in the manifest
+  so that the system reserves space
+  for your browser action in the toolbar.</p>
 
-<p>Icons can be set two ways:
+<h2 id="ui">Parts of the UI</h2>
+
+<p>
+A browser action must have an <a href="#icon">icon</a>.
+It can also have
+a <a href="#tooltip">tooltip</a>,
+a <a href="#badge">badge</a>,
+and a <a href="#popup">popup</a>.
+</p>
+
+<h3 id="icon">Icon</h3>
+
+<p>Browser action icons can be up to 19 pixels wide and high.
+  Larger icons are resized to fit, but for best results,
+  use a 19-pixel square icon.</p>
+
+<p>You can set the icon in 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
+  but you can create more dynamic UIs —
+  such as smooth animation —
   using the canvas element.
+  </p>
+
+<p>Static images can be in any format WebKit can display,
+  including BMP, GIF, ICO, JPEG, or PNG.
+  </p>
 
-</p><p>Static images can be in any format WebKit can display.
-  These include: png, bmp, ico, jpg, gif.</p>
+<p>To set the icon,
+use the <b>default_icon</b> field of <b>browser_action</b>
+in the <a href="#manifest">manifest</a>,
+or call the <a href="#method-setIcon">setIcon()</a> method.
 
-<h2 id="badges">Badges</h2>
 
-<p>Browser actions can optionally display a badge,
-  which is a bit of text that is layered over the icon.
+</p><h3 id="tooltip">Tooltip</h3>
+
+<p>
+To set the tooltip,
+use the <b>default_title</b> field of <b>browser_action</b>
+in the <a href="#manifest">manifest</a>,
+or call the <a href="#method-setTitle">setTitle()</a> method.
+</p>
+
+<h3 id="badge">Badge</h3>
+
+<p>Browser actions can optionally display a <em>badge</em> —
+  a bit of text that is layered over the icon.
   Badges make it easy to update the browser action
   to display a small amount of information
   about the state of the extension.</p>
 
-<p>The badge APIs allow any length of text,
-  but limiting badges to a max of four characters
-  is recommended.</p>
+<p>Because the badge has limited space,
+   it should have 4 characters or less.
+  </p>
+
+<p>
+Set the text and color of the badge using
+<a href="#method-setBadgeText">setBadgeText()</a> and
+<a href="#method-setBadgeBackgroundColor">setBadgeBackgroundColor()</a>,
+respectively.
+<span class="comment">[PENDING:
+if you have a color but no text, will anything display?]</span>
+</p>
 
-<h2 id="popups">Popups</h2>
 
-<p>Popups allow browser actions to show additional UI
-  when the user activates them.
-  Popups contents are implemented using HTML
-  and the popup is automatically sized
-  to the content size.</p>
+<h3 id="popups">Popup</h3>
 
-<a name="H2-3"></a><h2>Style Guide</h2>
+<p>If a browser action has a popup,
+  the popup appears when the user clicks the icon.
+  The popup can contain any HTML contents that you like,
+  and it's automatically sized to fit its contents.
+  </p>
+
+<p>
+To add a popup to your browser action,
+create an HTML file with the popup's contents.
+Then specify the HTML file in
+the <a href="#manifest">manifest</a>,
+using the <b>popup</b> field of <b>browser_action</b>.
+</p>
+
+<a name="H2-6"></a><h2>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 browser actions for features
     that make sense on most pages.
   </li><li><b>Don't</b> use browser actions for features
-    that only make sense for a few pages.
+    that make sense for only a few pages.
     Use <a href="pageAction.html">page actions</a> instead.
-  </li><li><b>Do</b> use big, colorful icons that fully utilize
-    the 19px square space.
+  </li><li><b>Do</b> use big, colorful icons that make the most of
+    the 19x19-pixel space.
     Browser action icons should seem a little bigger
     and heavier than page action icons.
   </li><li><b>Don't</b> attempt to mimic
-    Chrome's monochrome "wrench" and "page" icons.
-    This won't work well with themes, and anyway,
+    Google Chrome's monochrome "wrench" and "page" icons.
+    That doesn't work well with themes, and anyway,
     extensions should stand out a little.
   </li><li><b>Do</b> use alpha transparency
     to add soft edges to your icon.
-    Remember: many users theme Chrome,
-    so your icon should look nice
+    Because many people use themes,
+    your icon should look nice
     on a variety of background colors.
   </li><li><b>Don't</b> constantly animate your icon.
     That's just annoying.
 </li></ul>
 
-<h2 id="manifest">Manifest</h2>
-
-<p>Developers declare their browser action
-  using the following syntax:</p>
-
-<pre>"browser_action": {
-  "default_title": "Google Mail",  // Optional. Shown in tooltip.
-  "default_icon": "images/icon19.png",  // Optional.
-  "popup": "popup.html"  // Optional
-}</pre>
-
-<p><b>Note:</b> Even if you don't include
-  any of the values, you must include an empty
-  browser_action entry in your manifest
-  so that the system knows to reserve space
-  for your browser action in the toolbar.</p>
-
 <!-- END AUTHORED CONTENT -->
 </div>
 
@@ -458,7 +522,7 @@
           <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 bakground 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 <code>[255, 255, 0, 0]</code>.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -519,7 +583,7 @@
 
               <div class="description">
                 <p class="todo" style="display: none; ">Undocumented.</p>
-                <p>Sets the badge text for the browser action. This is printed on top of the icon.</p>
+                <p>Sets the badge text for the browser action. The badge is displayed on top of the icon.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
@@ -650,7 +714,7 @@
 
               <div class="description">
                 <p class="todo" style="display: none; ">Undocumented.</p>
-                <p>Sets the icon for the browser 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 browser 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>
@@ -720,7 +784,7 @@
           <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 <code>canvas</code> element).</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -761,7 +825,7 @@
           <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; ">
@@ -863,7 +927,7 @@
 
               <div class="description">
                 <p class="todo" style="display: none; ">Undocumented.</p>
-                <p>Sets the title of the browser action. Shows up in the tooltip if the browser action is visible, and in the menu item.</p>
+                <p>Sets the title of the browser action. This shows up in the tooltip.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
@@ -1004,7 +1068,7 @@
 
               <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 browser action icon is clicked.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
diff --git a/chrome/common/extensions/docs/static/browserAction.html b/chrome/common/extensions/docs/static/browserAction.html
index 310fbeb..514f760 100644
--- a/chrome/common/extensions/docs/static/browserAction.html
+++ b/chrome/common/extensions/docs/static/browserAction.html
@@ -1,93 +1,165 @@
 <div id="pageData-title" class="pageData">Browser Actions</div>
 
 <!-- BEGIN AUTHORED CONTENT -->
-<p>Browser actions are buttons
-  that are displayed in the main Chrome toolbar
-  to the right of the omnibox.</p>
+<p>Use browser actions to put icons
+  in the main Google Chrome toolbar,
+  to the right of the address bar.
+  In addition to its <a href="#icon">icon</a>,
+  a browser action can also have
+  a <a href="#tooltip">tooltip</a>,
+  a <a href="#badge">badge</a>,
+  and a <a href="#popup">popup</a>.
+  </p>
+
+<p>
+In the following figure,
+the multicolored square
+to the right of the address bar
+is the icon for a browser action.
+A popup is below the icon.
+</p>
 
 <img src="images/browser-action.png"
   width="363" height="226" />
 
-<h2 id="icons">Icons</h2>
+<p>
+If you want to create an icon that isn't always visible,
+use a <a href="pageAction.html">page action</a>
+instead of a browser action.
+</p>
 
-<p>Browser 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 class="comment">
+[PENDING: We should show tooltips and badges, as well.]
+</p>
 
-<p>Icons can be set two ways:
+<h2 id="manifest">Manifest</h2>
+
+<p>
+Register your browser action in the
+<a href="manifest.html">extension manifest</a>
+like this:
+</p>
+
+<pre>"browser_action": {
+  "default_title": "Google Mail",      <em>// optional; shown in tooltip</em>
+  "default_icon": "images/icon19.png", <em>// optional</em>
+  "popup": "popup.html"                <em>// optional</em>
+}</pre>
+
+<p><b>Note:</b> Even if you don't include
+  any of the values, you must include an empty
+  <b>browser_action</b> entry in the manifest
+  so that the system reserves space
+  for your browser action in the toolbar.</p>
+
+<h2 id="ui">Parts of the UI</h2>
+
+<p>
+A browser action must have an <a href="#icon">icon</a>.
+It can also have
+a <a href="#tooltip">tooltip</a>,
+a <a href="#badge">badge</a>,
+and a <a href="#popup">popup</a>.
+</p>
+
+<h3 id="icon">Icon</h3>
+
+<p>Browser action icons can be up to 19 pixels wide and high.
+  Larger icons are resized to fit, but for best results,
+  use a 19-pixel square icon.</p>
+
+<p>You can set the icon in 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
+  but you can create more dynamic UIs &mdash;
+  such as smooth animation &mdash;
   using the canvas element.
+  </p>
+
+<p>Static images can be in any format WebKit can display,
+  including BMP, GIF, ICO, JPEG, or PNG.
+  </p>
+
+<p>To set the icon,
+use the <b>default_icon</b> field of <b>browser_action</b>
+in the <a href="#manifest">manifest</a>,
+or call the <a href="#method-setIcon">setIcon()</a> method.
 
-<p>Static images can be in any format WebKit can display.
-  These include: png, bmp, ico, jpg, gif.</p>
 
-<h2 id="badges">Badges</h2>
+<h3 id="tooltip">Tooltip</h3>
 
-<p>Browser actions can optionally display a badge,
-  which is a bit of text that is layered over the icon.
+<p>
+To set the tooltip,
+use the <b>default_title</b> field of <b>browser_action</b>
+in the <a href="#manifest">manifest</a>,
+or call the <a href="#method-setTitle">setTitle()</a> method.
+</p>
+
+<h3 id="badge">Badge</h3>
+
+<p>Browser actions can optionally display a <em>badge</em> &mdash;
+  a bit of text that is layered over the icon.
   Badges make it easy to update the browser action
   to display a small amount of information
   about the state of the extension.</p>
 
-<p>The badge APIs allow any length of text,
-  but limiting badges to a max of four characters
-  is recommended.</p>
+<p>Because the badge has limited space,
+   it should have 4 characters or less.
+  </p>
+
+<p>
+Set the text and color of the badge using
+<a href="#method-setBadgeText">setBadgeText()</a> and
+<a href="#method-setBadgeBackgroundColor">setBadgeBackgroundColor()</a>,
+respectively.
+<span class="comment">[PENDING:
+if you have a color but no text, will anything display?]</span>
+</p>
+
 
-<h2 id="popups">Popups</h2>
+<h3 id="popups">Popup</h3>
 
-<p>Popups allow browser actions to show additional UI
-  when the user activates them.
-  Popups contents are implemented using HTML
-  and the popup is automatically sized
-  to the content size.</p>
+<p>If a browser action has a popup,
+  the popup appears when the user clicks the icon.
+  The popup can contain any HTML contents that you like,
+  and it's automatically sized to fit its contents.
+  </p>
 
-<h2>Style Guide</h2>
+<p>
+To add a popup to your browser action,
+create an HTML file with the popup's contents.
+Then specify the HTML file in
+the <a href="#manifest">manifest</a>,
+using the <b>popup</b> field of <b>browser_action</b>.
+</p>
+
+<h2>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 browser actions for features
     that make sense on most pages.
   <li><b>Don't</b> use browser actions for features
-    that only make sense for a few pages.
+    that make sense for only a few pages.
     Use <a href="pageAction.html">page actions</a> instead.
-  <li><b>Do</b> use big, colorful icons that fully utilize
-    the 19px square space.
+  <li><b>Do</b> use big, colorful icons that make the most of
+    the 19x19-pixel space.
     Browser action icons should seem a little bigger
     and heavier than page action icons.
   <li><b>Don't</b> attempt to mimic
-    Chrome's monochrome "wrench" and "page" icons.
-    This won't work well with themes, and anyway,
+    Google Chrome's monochrome "wrench" and "page" icons.
+    That doesn't work well with themes, and anyway,
     extensions should stand out a little.
   <li><b>Do</b> use alpha transparency
     to add soft edges to your icon.
-    Remember: many users theme Chrome,
-    so your icon should look nice
+    Because many people use themes,
+    your icon should look nice
     on a variety of background colors.
   <li><b>Don't</b> constantly animate your icon.
     That's just annoying.
 </ul>
 
-<h2 id="manifest">Manifest</h2>
-
-<p>Developers declare their browser action
-  using the following syntax:</p>
-
-<pre>"browser_action": {
-  "default_title": "Google Mail",  // Optional. Shown in tooltip.
-  "default_icon": "images/icon19.png",  // Optional.
-  "popup": "popup.html"  // Optional
-}</pre>
-
-<p><b>Note:</b> Even if you don't include
-  any of the values, you must include an empty
-  browser_action entry in your manifest
-  so that the system knows to reserve space
-  for your browser action in the toolbar.</p>
-
 <!-- END AUTHORED CONTENT -->