Clarify what content scripts can and can't do. Overview overhaul

(with further clarification) will be in a later CL.

TBR=aa

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

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

4 files changed, 168 insertions, 12 deletions

diff --git a/chrome/common/extensions/docs/content_scripts.html b/chrome/common/extensions/docs/content_scripts.html
index f38bf85..d4ed27c 100755
--- a/chrome/common/extensions/docs/content_scripts.html
+++ b/chrome/common/extensions/docs/content_scripts.html
@@ -149,7 +149,7 @@
                 </li>
               </ol>
             </li><li jsinstance="1">
-              <a href="#extecution-environment">Execution environment</a>
+              <a href="#execution-environment">Execution environment</a>
               <ol>
                 <li jsinstance="*0" style="display: none; ">
                   <a>h3Name</a>
@@ -224,16 +224,59 @@
         <div id="static"><div id="pageData-title" class="pageData">Content Scripts</div>
 <div id="pageData-showTOC" class="pageData">true</div>
 
-<p>Content Scripts are JavaScript files that run in the context of web pages. By using the standard <a href="http://www.w3.org/TR/DOM-Level-2-HTML/">Document Object Model</a> (DOM), they can read details of the web pages the browser visits, or make changes to them. 
+<p>
+Content Scripts are JavaScript files that run in the context of web pages.
+By using the standard
+<a href="http://www.w3.org/TR/DOM-Level-2-HTML/">Document
+Object Model</a> (DOM),
+they can read details of the web pages the browser visits,
+or make changes to them.
+</p>
 
-</p><p>Some examples of things that content scripts can do include:
+<p>
+Here are some examples of what content scripts can do:
+</p>
 
-</p><ul>
+<ul>
   <li>Find unlinked URLs in web pages and convert them into hyperlinks
   </li><li>Increase the font size to make text more legible
   </li><li>Find and process <a href="http://microformats.org/">microformat</a> data in the DOM
 </li></ul>
 
+<p>
+However, content scripts have some limitations.
+They <b>cannot use</b>:
+</p>
+
+<ul>
+  <li>
+    chrome.* APIs
+    (except for parts of
+    <a href="extension.html"><code>chrome.extension</code></a>)
+  </li>
+  <li>
+    variables or functions defined by their extension's pages
+  </li>
+  <li>
+    variables or functions defined by web pages or by other content scripts
+  </li>
+</ul>
+
+<p>
+These limitations aren't as bad as they sound.
+Content scripts can <em>indirectly</em> use the chrome.* APIs,
+get access to extension data,
+and request extension actions
+by exchanging <a href="#messaging">messages</a>
+with their parent extension.
+Content scripts can also
+<a href="#host-page-communication">communicate with web pages</a>
+using the shared DOM.
+For more insight into what content scripts can and can't do,
+learn about the
+<a href="#execution-environment">execution environment</a>.
+</p>
+
 <h2 id="registration">Manifest</h2>
 
 <p>Content scripts are registered in an extension's <a href="manifest.html">manifest.json</a> file, like so:
@@ -286,7 +329,7 @@
 </tbody></table>
 
 
-<h2 id="extecution-environment">Execution environment</h2>
+<h2 id="execution-environment">Execution environment</h2>
 
 <p>Content scripts execute in a special environment called an <em>isolated world</em>. They have access to the DOM of the page they are injected into, but not to any JavaScript variables or functions created by the page. It looks to each content script as if there is no other JavaScript executing on the page it is running on. The same is true in reverse: JavaScript running on the page cannot call any functions or access any variables defined by content scripts.
 
diff --git a/chrome/common/extensions/docs/extension.html b/chrome/common/extensions/docs/extension.html
index 3c3f07c..a8025d1 100755
--- a/chrome/common/extensions/docs/extension.html
+++ b/chrome/common/extensions/docs/extension.html
@@ -141,10 +141,10 @@
         <div id="toc">
           <p>Contents</p>
           <ol>
-            <li jsinstance="*0" style="display: none; ">
-              <a>h2Name</a>
+            <li jsinstance="*0">
+              <a href="#content scripts">Support for content scripts</a>
               <ol>
-                <li>
+                <li jsinstance="*0" style="display: none; ">
                   <a>h3Name</a>
                 </li>
               </ol>
@@ -203,7 +203,42 @@
         <!-- /TABLE OF CONTENTS -->
 
         <!-- STATIC CONTENT PLACEHOLDER -->
-        <div id="static"></div>
+        <div id="static"><!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+The <code>chrome.extension</code> module
+has utilities that can be used by any extension page.
+</p>
+
+<h2 id="content scripts">Support for content scripts</h2>
+<p>
+Unlike the other chrome.* APIs,
+parts of <code>chrome.extension</code>
+can be used by content scripts:
+</p>
+
+<dl>
+  <dt>
+    <a href="#method-connect"><code>connect()</code></a> and
+    <a href="#event-onConnect"><code>onConnect</code></a>
+  </dt>
+  <dd>
+    Communication with extension pages
+  </dd>
+  <dt>
+    <a href="#method-getURL"><code>getURL()</code></a>
+  </dt>
+  <dd>
+    Access to extension resources such as image files
+  </dd>
+</dl>
+
+<p>
+For details, see
+<a href="content_scripts.html">Content Scripts</a>.
+</p>
+
+<!-- END AUTHORED CONTENT -->
+</div>
 
         <!-- API PAGE -->
         <div class="apiPage">
diff --git a/chrome/common/extensions/docs/static/content_scripts.html b/chrome/common/extensions/docs/static/content_scripts.html
index 120709f..dc5a9ba 100644
--- a/chrome/common/extensions/docs/static/content_scripts.html
+++ b/chrome/common/extensions/docs/static/content_scripts.html
@@ -1,9 +1,18 @@
 <div id="pageData-title" class="pageData">Content Scripts</div>
 <div id="pageData-showTOC" class="pageData">true</div>
 
-<p>Content Scripts are JavaScript files that run in the context of web pages. By using the standard <a href="http://www.w3.org/TR/DOM-Level-2-HTML/">Document Object Model</a> (DOM), they can read details of the web pages the browser visits, or make changes to them. 
+<p>
+Content Scripts are JavaScript files that run in the context of web pages.
+By using the standard
+<a href="http://www.w3.org/TR/DOM-Level-2-HTML/">Document
+Object Model</a> (DOM),
+they can read details of the web pages the browser visits,
+or make changes to them.
+</p>
 
-<p>Some examples of things that content scripts can do include:
+<p>
+Here are some examples of what content scripts can do:
+</p>
 
 <ul>
   <li>Find unlinked URLs in web pages and convert them into hyperlinks
@@ -11,6 +20,40 @@
   <li>Find and process <a href="http://microformats.org/">microformat</a> data in the DOM
 </ul>
 
+<p>
+However, content scripts have some limitations.
+They <b>cannot use</b>:
+</p>
+
+<ul>
+  <li>
+    chrome.* APIs
+    (except for parts of
+    <a href="extension.html"><code>chrome.extension</code></a>)
+  </li>
+  <li>
+    variables or functions defined by their extension's pages
+  </li>
+  <li>
+    variables or functions defined by web pages or by other content scripts
+  </li>
+</ul>
+
+<p>
+These limitations aren't as bad as they sound.
+Content scripts can <em>indirectly</em> use the chrome.* APIs,
+get access to extension data,
+and request extension actions
+by exchanging <a href="#messaging">messages</a>
+with their parent extension.
+Content scripts can also
+<a href="#host-page-communication">communicate with web pages</a>
+using the shared DOM.
+For more insight into what content scripts can and can't do,
+learn about the
+<a href="#execution-environment">execution environment</a>.
+</p>
+
 <h2 id="registration">Manifest</h2>
 
 <p>Content scripts are registered in an extension's <a href="manifest.html">manifest.json</a> file, like so:
@@ -63,7 +106,7 @@
 </table>
 
 
-<h2 id="extecution-environment">Execution environment</h2>
+<h2 id="execution-environment">Execution environment</h2>
 
 <p>Content scripts execute in a special environment called an <em>isolated world</em>. They have access to the DOM of the page they are injected into, but not to any JavaScript variables or functions created by the page. It looks to each content script as if there is no other JavaScript executing on the page it is running on. The same is true in reverse: JavaScript running on the page cannot call any functions or access any variables defined by content scripts.
 
diff --git a/chrome/common/extensions/docs/static/extension.html b/chrome/common/extensions/docs/static/extension.html
new file mode 100755
index 0000000..70afe31
--- /dev/null
+++ b/chrome/common/extensions/docs/static/extension.html
@@ -0,0 +1,35 @@
+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+The <code>chrome.extension</code> module
+has utilities that can be used by any extension page.
+</p>
+
+<h2 id="content scripts">Support for content scripts</h2>
+<p>
+Unlike the other chrome.* APIs,
+parts of <code>chrome.extension</code>
+can be used by content scripts:
+</p>
+
+<dl>
+  <dt>
+    <a href="#method-connect"><code>connect()</code></a> and
+    <a href="#event-onConnect"><code>onConnect</code></a>
+  </dt>
+  <dd>
+    Communication with extension pages
+  </dd>
+  <dt>
+    <a href="#method-getURL"><code>getURL()</code></a>
+  </dt>
+  <dd>
+    Access to extension resources such as image files
+  </dd>
+</dl>
+
+<p>
+For details, see
+<a href="content_scripts.html">Content Scripts</a>.
+</p>
+
+<!-- END AUTHORED CONTENT -->