Documenting changes between `manifest_version` 1 and 2.

BUG=111917
TEST=

Review URL: https://chromiumcodereview.appspot.com/9104009

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

3 files changed, 212 insertions, 8 deletions

diff --git a/chrome/common/extensions/docs/static/contentSecurityPolicy.html b/chrome/common/extensions/docs/static/contentSecurityPolicy.html
index 5c06052..c67796f 100644
--- a/chrome/common/extensions/docs/static/contentSecurityPolicy.html
+++ b/chrome/common/extensions/docs/static/contentSecurityPolicy.html
@@ -45,8 +45,10 @@
 <h2>Default Policy Restrictions</h2>
 
 <p>
-  For packages using <a href="manifest.html#manifest_version">
-  <code>manifest_version</code></a> 2, Chrome defines a content security policy
+  Packages that do not define a <a href="manifestVersion.html">
+    <code>manifest_version</code>
+  </a> have no default content security policy. Those that select
+  <code>manifest_version</code></a> 2, have a default content security policy
   of:
 </p>
 
diff --git a/chrome/common/extensions/docs/static/manifest.html b/chrome/common/extensions/docs/static/manifest.html
index 2e58812..5898ab5 100644
--- a/chrome/common/extensions/docs/static/manifest.html
+++ b/chrome/common/extensions/docs/static/manifest.html
@@ -45,6 +45,7 @@ are <b>name</b> and <b>version</b>.
   "<a href="#incognito">incognito</a>": "spanning" <em>or</em> "split",
   "<a href="#key">key</a>": "<em>publicKey</em>",
   "<a href="#minimum_chrome_version">minimum_chrome_version</a>": "<em>versionString</em>",
+
   "<a href="#nacl_modules">nacl_modules</a>": [...],
   "<a href="#offline_enabled">offline_enabled</a>": true,
   "<a href="omnibox.html">omnibox</a>": { "keyword": "<em>aString</em>" },
@@ -52,7 +53,8 @@ are <b>name</b> and <b>version</b>.
   "<a href="#permissions">permissions</a>": [...],
   "<a href="npapi.html">plugins</a>": [...],
   "<a href="#requirements">requirements</a>": {...},
-  "<a href="autoupdate.html">update_url</a>": "http://<em>path/to/updateInfo</em>.xml"
+  "<a href="autoupdate.html">update_url</a>": "http://<em>path/to/updateInfo</em>.xml",
+  "<a href="#web_accessible_resources">web_accessible_resources</a>": [...]
 }
 </pre>
 
@@ -670,21 +672,82 @@ For example, 1.1.9.9999 is newer than 1.1.
 For more information, see
 <a href="autoupdate.html">Autoupdating</a>.
 </p>
+<!-- [PENDING: Possibly: point to the store/dashboard and make a big deal of the fact that autoupdating is free if you use them.] -->
 
 
 <h3 id="manifest_version">manifest_version</h3>
 
 <p>
-The version of the manifest format that this extension uses. Currently,
-extensions should use the value <code>2</code> (without quotes):
+One integer specifying the version of the manifest file format your package
+requires. As of Chrome 18, developers <em>should</em> specify <code>2</code>
+(without quotes) to use the format as described by this document:
 </p>
 
 <pre>"manifest_version": 2</pre>
 
 <p>
-Future breaking changes to the extension system may require a new version
-number.
+Consider manifest version 1 <em>deprecated</em> as of Chrome 18. Version 2 is
+not yet <em>required</em>, but we will, at some point in the not-too-distant
+future, stop supporting packages using deprecated manifest versions. Extensions,
+applications, and themes that aren't ready to make the jump to the new manifest
+version in Chrome 18 can either explicitly specify version <code>1</code>, or
+leave the key off entirely.
+</p>
+
+<p>
+The changes between version 1 and version 2 of the manifest file format are
+described in detail in <a href="manifestVersion.html">the
+<code>manifest_version</code> documentation.</a>
 </p>
 
+<h3 id="web_accessible_resources">web_accessible_resources</h3>
 
-<!-- [PENDING: Possibly: point to the store/dashboard and make a big deal of the fact that autoupdating is free if you use them.] -->
+<p>
+An array of strings specifying the paths (relative to the package root) of
+packaged resources that are expected to be usable in the context of a web page.
+For example, an extension that injects a content script with the intention of
+building up some custom interface for <code>example.com</code> would whitelist
+any resources that interface requires (images, icons, stylesheets, scripts,
+etc.) as follows:
+</p>
+
+<pre>{
+  ...
+  "web_accessible_resources": [
+    "images/my-awesome-image1.png",
+    "images/my-amazing-icon1.png",
+    "style/double-rainbow.css",
+    "script/double-rainbow.js"
+  ],
+  ...
+}</pre>
+
+<p>
+These resources would then be available in a webpage via the URL
+<code>chrome-extension://[PACKAGE ID]/[PATH]</code>, which can be generated with
+the <a href="extension.html#method-getURL">
+  <code>chrome.extension.getURL</code>
+</a> method. Whitelisted resources are served with appropriate
+<a href="http://www.w3.org/TR/cors/">CORS</a> headers, so they're available via
+mechanisms like XHR.
+</p>
+
+<p>
+Injected content scripts themselves do not need to be whitelisted.
+</p>
+
+<h4>Default Availablility</h4>
+
+<p>
+Resources inside of packages using <a href="#manifest_version">
+  <code>manifest_version</code>
+</a> 2 or above are <strong>blocked by default</strong>, and must be whitelisted
+for use via this property.
+</p>
+
+<p>
+Resources inside of packages using <code>manifest_version</code> 1 are available
+by default, but <em>if</em> you do set this property, then it will be treated as
+a complete list of all whitelisted resources. Resources not listed will be
+blocked.
+</p>
diff --git a/chrome/common/extensions/docs/static/manifestVersion.html b/chrome/common/extensions/docs/static/manifestVersion.html
new file mode 100644
index 0000000..0ce6ac1
--- /dev/null
+++ b/chrome/common/extensions/docs/static/manifestVersion.html
@@ -0,0 +1,139 @@
+<div id="pageData-name" class="pageData">Manifest Version</div>
+
+<p>
+  Extensions, themes, and applications are simply bundles of resources, wrapped
+  up with a <a href="manifest.html"><code>manifest.json</code></a> file that
+  describes the package's contents. The format of this file is generally stable,
+  but occasionally breaking changes must be made to address specific issues.
+  Developers should specify which version of the manifest specification their
+  package targets by setting a <code>manifest_version</code> key in their
+  manifests.
+</p>
+
+<h2>Current Version</h2>
+
+<p>
+  When targeting Chrome 18 and above, developers should specify
+  <strong><code>'manifest_version': 2</code></strong>:
+</p>
+
+<pre>{
+  ...,
+  "manifest_version": 2,
+  ...
+}</pre>
+
+<p>
+  Manifest version 1 is <em>deprecated</em> in Chrome 18 and above, but version
+  2 is not yet <em>required</em>. Extensions, applications, and themes that
+  aren't ready to make the jump to the new manifest version in Chrome 18 can
+  either explicitly specify version <code>1</code>, or leave the key off
+  entirely.
+</p>
+
+<p>
+  At some point in the future, support for manifest version 1 will be removed.
+  Ample warning will be provided, beginning with warnings when loading unpacked
+  version 1 extensions, and escalating from there over time.
+</p>
+
+<h2>Changes between version 1 and 2</h2>
+
+<ul>
+  <li>
+    <p>
+      A content security policy is set to <code>`script-src 'self'; object-src
+      'self'</code> by default. This has a variety of impacts on developers,
+      described at length in the <a href="contentSecurityPolicy.html">
+      <code>content_security_policy</code></a> documentation.
+    </p>
+  </li>
+  <li>
+    <p>
+      A package's resources are no longer available by default to external
+      websites (as the <code>src</code> of an image, or a <code>script</code>
+      tag). If you want a website to be able to load a resource contained in
+      your package, you'll need to explicitly whitelist it via the
+      <a href="manifest.html#web_accessible_resources">
+        <code>web_accessible_resources</code>
+      </a> manifest attribute. This is particularly relevant for extensions that
+      build up an interface on a website via injected content scripts.
+    </p>
+  </li>
+  <li>
+    <p>
+      The <code>background_page</code> property has been replaced with a
+      <code>background</code> property that contains <em>either</em> a
+      <code>scripts</code> or <code>page</code> property. Details are available
+      in the <a href="background_pages.html">Background Pages</a> documentation.
+    </p>
+  </li>
+  <li>
+    <p>
+      A variety of previously deprecated features have been removed entirely:
+    </p>
+    <ul>
+      <li>
+        <p>
+          The <code>page_actions</code> key in the manifest, and the
+          <code>chrome.pageActions</code> API are gone. Use the singular
+          <a href="pageAction.html">
+            <code>page_action</code> and <code>chrome.pageAction</code>
+          </a> instead.
+        </p>
+      </li>
+      <li>
+        <p>
+          <code>chrome.extension.getTabContentses</code> (!!!) and
+          <code>chrome.extension.getExtensionTabs</code> are gone. Use
+          <a href="extension.html#method-getViews">
+            <code>chrome.extension.getViews({ "type": "tab" })</code>
+          </a> instead.
+        </p>
+      </li>
+      <li>
+        <p>
+          <code>Port.tab</code> is gone. Use
+          <a href="extension.html#type-Port"><code>Port.sender</code></a>
+          instead.
+        </p>
+      </li>
+      <li>
+        <p>
+          The <code>icons</code> property of <code>page_action</code> has been
+          removed. Use <a href="pageAction.html#manifest">
+            the <code>default_icon</code> property
+          </a> or <a href="pageAction.html#method-setIcon">
+            <code>chrome.pageAction.setIcon</code>
+          </a> instead.
+        </p>
+      </li>
+      <li>
+        <p>
+          The <code>name</code> property of <code>page_action</code> has been
+          removed. Use <a href="pageAction.html#manifest">
+            the <code>default_title</code> property
+          </a> or <a href="pageAction.html#method-setTitle">
+            <code>chrome.pageAction.setTitle</code>
+          </a> instead.
+        </p>
+      </li>
+      <li>
+        <p>
+          The <code>popup</code> property of <code>page_action</code> has been
+          removed. Use <a href="pageAction.html#manifest">
+            the <code>default_popup</code> property
+          </a> or <a href="pageAction.html#method-setPopup">
+            <code>chrome.pageAction.setPopup</code>
+          </a> instead.
+        </p>
+      </li>
+      <li>
+        <p>
+          The <code>default_popup</code> property of <code>page_action</code>
+          can no longer be specified as an object. It must be a string.
+        </p>
+      </li>
+    </ul>
+  </li>
+</ul>