Cleanup. Also copyedited xhr.html and linked to it from the appropriate

places.

TBR=aa, rafaelw

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

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

11 files changed, 108 insertions, 94 deletions

diff --git a/chrome/common/extensions/docs/css/ApiRefStyles.css b/chrome/common/extensions/docs/css/ApiRefStyles.css
index 02ec55e..7b00b5b 100755
--- a/chrome/common/extensions/docs/css/ApiRefStyles.css
+++ b/chrome/common/extensions/docs/css/ApiRefStyles.css
@@ -1,12 +1,16 @@
-.pageData {
+.comment { /* while we're working on doc, comment out display */
+  color: rgb(255, 0, 0);
   display: none;
 }
- 
- .todo {
-  color: red;
-  display: none;
+
+.tbd { /* style for comments that should be visible to all devs */
+  color: rgb(125, 125, 125);
 }
 
+.pageData {
+  display: none;
+}
+ 
 body {
   font-family:Arial, Helvetica, sans-serif;
   font-size: 13px;
@@ -16,10 +20,6 @@ h2,h3 {
   margin-top: 2em;
 }
 
-.comment {
-  color: rgb(255, 0, 0);
-}
-
 div.summary .subdued {
   color: rgb(147, 180, 217);
 }
diff --git a/chrome/common/extensions/docs/static/api_other.html b/chrome/common/extensions/docs/static/api_other.html
index 260141c..278ae50 100755
--- a/chrome/common/extensions/docs/static/api_other.html
+++ b/chrome/common/extensions/docs/static/api_other.html
@@ -14,15 +14,19 @@ you can bundle additional API libraries into your extension.
 
 <dl>
 <dt><strong> Standard JavaScript APIs </strong></dt>
-<dd> <span class="comment">[PENDING: define, explain; link to complete list]</span> 
+<dd> These are the same core JavaScript and DOM APIs
+  that you can use in ordinary web apps.
+  <span class="comment">[PENDING: check! should link to complete list]</span> 
 <!-- Use onclick in your toolbar div to add click behavior.
 E.g. window.open(someUrl). --></dd>
 <dt><strong> XMLHttpRequest </strong></dt>
 <dd>
-  Lets the extension request data from one or more servers.
-  The manifest specifies 
-  which domains the extension can send requests to.
-  <span class="comment">[PENDING: link to doc]</span></dd>
+  Use <a href="xhr.html">XMLHttpRequest</a>
+  to request data from one or more servers.
+  The <a href="manifest.html#permissions">permissions</a> field
+  of the manifest specifies 
+  which hosts the extension can send requests to.
+  </dd>
 <dt><strong> WebKit APIs </strong></dt>
 <dd>
   Because Google Chrome is built upon WebKit,
@@ -41,10 +45,13 @@ E.g. window.open(someUrl). --></dd>
   <p class="comment">[PENDING: link to complete list of webkit apis]</p>
 </dd>
 <dt><strong> V8 APIs</strong>, such as<strong> JSON </strong></dt>
-<dd> JSON is in V8, so you don't need to include a JSON library to use JSON functions. <span class="comment">[PENDING: what other APIs are in v8? link to complete list]</span></dd>
-<dt> <strong>HTML5</strong> <strong>APIs</strong>, such as <strong>localStorage</strong> and <strong>Web Workers</strong></dt>
-<dd> HTML5 is still being defined and implemented, but one crucial feature it will provide is local storage... <!--
-localStorage.setItem(&quot;foo&quot;, &quot;bar&quot;); ... localStorage.getItem(&quot;foo&quot;); --> <span class="comment">[PENDING: mention Web Workers, too. Other important API? link to complete list]</span></dd>
+<dd> Because JSON is in V8, you don't need to include a JSON library to use JSON functions. <span class="comment">[PENDING: what other APIs are in v8? link to complete list]</span></dd>
+<dt> <strong>HTML5</strong> <strong>APIs</strong>, such as <strong>localStorage</strong></dt>
+<dd> HTML5 is still being defined and implemented,
+  but Google Chrome already supports local storage,
+  which extensions can use to store data.
+<!--
+localStorage.setItem(&quot;foo&quot;, &quot;bar&quot;); ... localStorage.getItem(&quot;foo&quot;); --> <span class="comment">[PENDING: Other important API? link to complete list]</span></dd>
 <dt><strong>APIs in bundled libraries</strong></dt>
 <dd> If you want to use a library that the browser doesn't provide
 (for example, jQuery),
diff --git a/chrome/common/extensions/docs/static/bookmarks.html b/chrome/common/extensions/docs/static/bookmarks.html
index 8034474..d5aef55 100755
--- a/chrome/common/extensions/docs/static/bookmarks.html
+++ b/chrome/common/extensions/docs/static/bookmarks.html
@@ -6,6 +6,18 @@ Use the <code>chrome.bookmarks</code> module to create, organize,
 and otherwise manipulate bookmarks.
 </p>
 
+<h2 id="manifest">Manifest</h2>
+<p>You must declare the "bookmarks" permission
+in your extension's manifest to use the bookmarks API.
+For example:</p>
+<pre>{
+  "name": "My extension that uses bookmarks",
+  "version": "0.1",
+<b>  "permissions": [
+    "bookmarks"
+  ]</b>
+}</pre>
+
 <h2 id="description">Description</h2>
 
 <p>
@@ -21,7 +33,7 @@ either a URL or a group of bookmarks, as you can see in the following figure.
   height="123"
   src="images/bookmarks.png"></a>
 <br />
-<span class="comment">
+<span class="tbd">
 [PENDING: this figure needs to be updated]
 </span>
 
@@ -119,22 +131,10 @@ Here's how those bookmarks might be represented with bookmark objects:</p>
 <p>
 Here's some code you could use to create that hierarchy:</p>
 
-<pre class="example comment">
+<pre class="example tbd">
 [PENDING: ...code goes here...]
 </pre>
 
-<h2 id="permissions">Permissions</h2>
-<p>You must declare the <var>bookmarks</var> permission
-in your extension's manifest to use the bookmarks API.</p>
-<p>Example:</p>
-<pre>{
-  "name": "My extension that uses bookmarks",
-  "version": "0.1",
-<b>  "permissions": [
-    "bookmarks"
-  ]</b>
-}</pre>
-
 
 <!-- PENDING: we could have links to source code and sample extensions. E.g.:
 <div class="exampleLink">
diff --git a/chrome/common/extensions/docs/static/devguide.html b/chrome/common/extensions/docs/static/devguide.html
index 122d170..e8000b2 100755
--- a/chrome/common/extensions/docs/static/devguide.html
+++ b/chrome/common/extensions/docs/static/devguide.html
@@ -25,8 +25,8 @@ but here's what we have, so far:
     <ul>
       <li><a href="background_pages.html">Background Pages</a></li>
       <li><a href="content_scripts.html">Content Scripts</a></li>
+      <li><a href="xhr.html">Cross-Origin XmlHttpRequest</a></li>
       <li><a href="npapi.html">NPAPI Plugins</a></li>
-      <li>XmlHttpRequest</li>
     </ul>
   </li>
   <li> Finishing and distributing your extension
diff --git a/chrome/common/extensions/docs/static/manifest.html b/chrome/common/extensions/docs/static/manifest.html
index 4a26258..6f19718 100755
--- a/chrome/common/extensions/docs/static/manifest.html
+++ b/chrome/common/extensions/docs/static/manifest.html
@@ -129,10 +129,9 @@ Here's an example of the permissions part of a manifest file:
 
 <p>
 For more information, see
-<a href="match_patterns.html">Match Patterns</a>.
-Note, however, that the match pattern in the <b>permissions</b> field
-specifies only the hosts &mdash;
-not the paths &mdash;
-to which the extension can make XMLHttpRequests.
+<a href="xhr.html">Cross-Origin XMLHttpRequest</a>,
+<a href="windows.html">Windows</a>,
+<a href="tabs.html">Tabs</a>, and
+<a href="bookmarks.html">Bookmarks</a>.
 </p>
 
diff --git a/chrome/common/extensions/docs/static/overview.html b/chrome/common/extensions/docs/static/overview.html
index 70c368c..7a56044 100755
--- a/chrome/common/extensions/docs/static/overview.html
+++ b/chrome/common/extensions/docs/static/overview.html
@@ -112,7 +112,7 @@ and the files shown in the following figure:
 </p>
 
 <pre>
-<span class="comment">[PENDING: convert this into a figure]</span>
+<span class="tbd">[PENDING: someday this will be a real figure]</span>
 toolstrip.html
 styles.css
 images:
@@ -166,7 +166,7 @@ no matter whether it's being used by
 </tr>
 </table>
 
-<p class="comment">
+<p class="tbd">
 [PENDING: Mention/reflect/link to
 <a href="http://dev.chromium.org/developers/design-documents/extensions/i18n">internationalization</a>]
 </p>
@@ -207,7 +207,7 @@ The first figure shows what an extension might look like
 when there's a single browser window.
 </p>
 
-<p class="comment"> [PENDING: image goes here] </p>
+<p class="tbd"> [PENDING: image goes here] </p>
 
 <p>
 The next figure shows that all the code in the extension's main HTML file
@@ -216,7 +216,7 @@ In other words, each window has its own widgets for the extension,
 which means each window adds another web page for that extension.
 </p>
 
-<p class="comment"> [PENDING: image goes here] </p>
+<p class="tbd"> [PENDING: image goes here] </p>
 
 <p>
 To more easily coordinate all these web pages and to avoid duplication,
@@ -227,9 +227,7 @@ is in a <em>background page</em>,
 as shown in the following figure.
 </p>
 
-<p class="comment">
-[PENDING: image goes here.]
-</p>
+<p class="tbd"> [PENDING: image goes here] </p>
 
 
 <h3 id="background">The background page</h3>
@@ -307,7 +305,7 @@ Two kinds of communication happen within an extension:
     Communication <b>between content scripts and the extension</b>.
     <br />
     For example,
-    <span class="comment">[PENDING: typical use case goes here]</span>.
+    <span class="tbd">[PENDING: typical use case goes here]</span>.
     See <a href="content_scripts.html">Content Scripts</a>
     for information about this type of communication.
   </li>
@@ -371,9 +369,9 @@ A good summary of communication mechanisms is at
 
 <h2> Summary </h2>
 
-<p>
+<p class="tbd">
 [
-PENDING: wrap it up. suggest where to go next. Probably:
+PENDING: summarize, suggest where to go next. Probably:
 <a href="getstarted.html">Getting Started</a>,
 <a href="tut_debugging.html">Debugging</a>,
 <a href="devguide.html">Developer's Guide</a>.
diff --git a/chrome/common/extensions/docs/static/tabs.html b/chrome/common/extensions/docs/static/tabs.html
index ba23898..3b9f896 100755
--- a/chrome/common/extensions/docs/static/tabs.html
+++ b/chrome/common/extensions/docs/static/tabs.html
@@ -8,9 +8,10 @@ You can use this module to
 create, modify, and rearrange tabs in the browser.
 </p>
 
-<h2 id="permissions">Permissions</h2>
-<p>You must declare the <var>tabs</var> permission in your extension's manifest to use the tabs API.</p>
-<p>Example:</p>
+<h2 id="manifest">Manifest</h2>
+<p>You must declare the "tabs" permission in your extension's manifest to use the tabs API.
+For example:
+</p>
 <pre>{
   "name": "My extension that uses tabs",
   "version": "0.1",
diff --git a/chrome/common/extensions/docs/static/tut_debugging.html b/chrome/common/extensions/docs/static/tut_debugging.html
index ff06bc9..26918d0 100644
--- a/chrome/common/extensions/docs/static/tut_debugging.html
+++ b/chrome/common/extensions/docs/static/tut_debugging.html
@@ -1,6 +1,6 @@
 <div id="pageData-title" class="pageData">Tutorial: Debugging</div>
 
-<p>
+<p class="tbd">
 [PENDING: intro goes here.
 This tutorial starts where
 <a href="getstarted.html">Getting Started</a> ends.
@@ -126,7 +126,7 @@ You now know how to debug an extension!</p>
 
 <h2 id="summary">What next?</h2>
 
-<p>
+<p class="tbd">
 [PENDING: Summarize what we did,
 what it means,
 and where to find more information.
diff --git a/chrome/common/extensions/docs/static/windows.html b/chrome/common/extensions/docs/static/windows.html
index e501b43..ca64ab0 100755
--- a/chrome/common/extensions/docs/static/windows.html
+++ b/chrome/common/extensions/docs/static/windows.html
@@ -8,12 +8,15 @@ You can use this module to
 create, modify, and rearrange windows in the browser.
 </p>
 
-<h2 id="permissions">Permissions</h2>
-<p>You must declare the <var>tabs</var> permission
-(no, that isn't a typo -- the window and tabs modules interact so closely we
-decided to just share one permission between them)
-in your extension's manifest to use the windows API.</p>
-<p>Example:</p>
+<h2 id="manifest">Manifest</h2>
+<p>
+You must declare the "tabs" permission
+in your extension's manifest to use the windows API.
+(No, that isn't a typo &mdash;
+the window and tabs modules interact so closely we
+decided to just share one permission between them.)
+For example:
+</p>
 <pre>{
   "name": "My extension that uses windows",
   "version": "0.1",
diff --git a/chrome/common/extensions/docs/static/xhr.html b/chrome/common/extensions/docs/static/xhr.html
index 8c55058..6902f2a 100755
--- a/chrome/common/extensions/docs/static/xhr.html
+++ b/chrome/common/extensions/docs/static/xhr.html
@@ -2,20 +2,21 @@
 
 <!-- BEGIN AUTHORED CONTENT -->
 <p id="classSummary">
-In regular web pages, the
+Regular web pages can use the
 <a href="http://www.w3.org/TR/XMLHttpRequest/">XMLHttpRequest</a>
-object can be used to  send and receive data from remote servers, but is
-constrained by the
+object to send and receive data from remote servers,
+but they're limited by the
 <a href="http://en.wikipedia.org/wiki/Same_origin_policy">same origin policy</a>.
-Extensions are allowed to access remote servers outside of their origin,
-but they must first declare their intent to do so.</p>
-
-<h2 id="extension-origin">Extension Origin</h2>
-<p>Each running extension exists within it's own seperate security origin. Without
-requesting additional priviliges, the extension can use
-the XMLHttpRequest to access resources within it's installation. For example, if
-the extension contains a JSON configuration file called <var>config.json</var>,
-in a <var>config_resources</var> folder, it could retrieve it's contents like
+Extensions aren't so limited.
+An extension can talk to remote servers outside of its origin,
+as long as it first requests cross-origin permissions.</p>
+
+<h2 id="extension-origin">Extension origin</h2>
+<p>Each running extension exists within its own separate security origin. Without
+requesting additional privileges, the extension can use
+XMLHttpRequest to get resources within its installation. For example, if
+an extension contains a JSON configuration file called <code>config.json</code>,
+in a <code>config_resources</code> folder, the extension can retrieve the file's contents like
 this:</p>
 
 <pre>
@@ -25,45 +26,49 @@ xhr.open("GET", chrome.extension.getURL('/config_resources/config.json'), true);
 xhr.send();
 </pre>
 
-<p>If the extension attempted to access a security origin other than itself,
-say</p>
+<p>If the extension attempts to use a security origin other than itself,
+say http://www.google.com,
+the browser disallows it
+unless the extension has requested the appropriate cross-origin permissions.
+</p>
 
-<pre>
-xhr.open("GET", "http://www.google.com", true);
-</pre>
-
-<p>The browser would disallow it.</p>
-
-<h2 id="requesting-permission">Requesting Cross-Origin Permissions</h2>
+<h2 id="requesting-permission">Requesting cross-origin permissions</h2>
 
-<p>By adding hosts and/or host match patterns to the
+<p>By adding hosts or host match patterns (or both) to the
 <a href="manifest.html#permissions">permissions<a> section of the 
 <a href="manifest.html">manifest</a> file, the extension can request access to 
-remote servers outside of it's origin.</p>
+remote servers outside of its origin.</p>
 
 <pre>"permissions": [
   "http://www.google.com/",
 ],
 </pre>
 
-<p>Cross-origin permission values can be either fully qualified host names,
-like</p>
+<p>Cross-origin permission values can be fully qualified host names,
+like these:</p>
 
-<pre>"http://www.google.com/" or
-"http://www.gmail.com/"</pre>
+<ul>
+  <li> "http://www.google.com/" </li>
+  <li> "http://www.gmail.com/" </li>
+</ul>
 
-<p>or match patterns, like</p>
+<p>Or they can be match patterns, like these:</p>
 
-<pre>"http://*.google.com/" or
-"http://*/"</pre>
+<ul>
+  <li> "http://*.google.com/" </li>
+  <li> "http://*/" </li>
+</ul>
 
-<p>which would allow http access to all reachable domains. Note that here,
+<p>
+A match pattern of "http://*/" allows HTTP access to all reachable domains.
+Note that here,
 match patterns are similar to <a href="match_patterns.html">content script
-match patterns</a>, but any path information following the host is ignored.</p>
+match patterns</a>,
+but any path information following the host is ignored.</p>
 
-<p>Also, note that access is granted both by host and scheme. If an extension
-wants secure and non-secure http access to a given host or set
-of hosts, it must declare the permissions seperately:</p>
+<p>Also note that access is granted both by host and by scheme. If an extension
+wants both secure and non-secure HTTP access to a given host or set
+of hosts, it must declare the permissions separately:</p>
 
 <pre>"permissions": [
   "http://www.google.com/",
diff --git a/chrome/common/extensions/docs/template/api_template.html b/chrome/common/extensions/docs/template/api_template.html
index 9d0de3d..bca16d1 100755
--- a/chrome/common/extensions/docs/template/api_template.html
+++ b/chrome/common/extensions/docs/template/api_template.html
@@ -41,6 +41,7 @@
               <li><a href="bookmarks.html">Bookmarks</a></li>
               <li><a href="themes.html">Themes</a></li>
               <li><a href="npapi.html">NPAPI Plugins</a></li>
+              <li><a href="xhr.html">Cross-Origin XHR</a></li>
               <li><a href="packaging.html">Packaging</a></li>
               <li>Autoupdate</li>
             </ul>