Update contentSettings extension API docs.

chrome/common/extensions/docs/static/contentSettings.html

Index: chrome/common/extensions/docs/static/contentSettings.html
diff --git a/chrome/common/extensions/docs/static/contentSettings.html b/chrome/common/extensions/docs/static/contentSettings.html
new file mode 100644
index 0000000000000000000000000000000000000000..e00714a7c497fef697a83889a2344b182cde394d
--- /dev/null
+++ b/chrome/common/extensions/docs/static/contentSettings.html
@@ -0,0 +1,140 @@
+<div id="pageData-name" class="pageData">Content Settings</div>
+

[kathyw, 2011/12/13 02:47:32]

I see no methods in the staged version of this page. Do they have "nodoc" or
something? For example, there's no getResourceIdentifier() method.

+<!-- BEGIN AUTHORED CONTENT -->
+<p>
+The content settings module allows you to change settings that control whether
+websites can use features such as cookies, Javascript, and plug-ins.

[kathyw, 2011/12/13 02:47:32]

Javascript -> JavaScript

+More generally speaking, content settings allow you to customize Chrome's
+behavior on a per-site basis instead of globally.</p>
+<p>
+</p>
+
+<h2 id="manifest">Manifest</h2>
+<p>You must declare the "contentSettings" permission
+in your extension's manifest to use the API.
+For example:</p>
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "contentSettings"
+  ]</b>,
+  ...
+}</pre>
+
+
+<h2 id="patterns">Content Setting Patterns</h2>

[kathyw, 2011/12/13 02:47:32]

We use Sentence caps for sections (Title Caps for page names), so:

Content Setting Patterns -> Content setting patterns

+<p>
+Content settings are applied to specific websites via patterns that define which
+sites they apply to. <code>http://*.youtube.com/*</code> matches youtube.com and
+all its subdomains, for example. For further details, see the
+<a href="match_patterns.html">Match Pattern documentation</a>.</p>

[kathyw, 2011/12/13 02:47:32]

I like Mike's suggestion, but I'd tweak it a bit to avoid passive voice and make
the example a little clearer. Maybe:

You can use patterns to specify the websites that each content setting affects.
For example, 'http://*.youtube.com/'
specifies youtube.com and all of its subdomains.
The syntax for content setting patterns is the same as for
<a href="match_patterns.html">match patterns</a>,
with a few differences:

+<p>
+Note that there are some differences between patterns for content settings and

[kathyw, 2011/12/13 02:47:32]

No need for a separate paragraph, I think. The previous paragraph made me think
that content setting patterns *were* match patterns. I rewrote to make clearer
that there are some differences.

+match patterns:
+<ul><li>For <code>http</code>,
+<code>https</code>, and <code>ftp</code> URLs the path has to be a wildcard

[kathyw, 2011/12/13 02:47:32]

URLs the -> URLs, the
has to be -> must be

(use "must" whenever something's absolute -- it's clearer that way)

+(<code>/*</code>). For <code>file</code> URLs, the path has to be completely

[kathyw, 2011/12/13 02:47:32]

has to be -> must be

+specified and is <strong>not</strong> allowed to contain wildcards.</li>

[kathyw, 2011/12/13 02:47:32]

is not allowed to -> <strong>must not</strong.

+<li>In contrast to match patterns, content setting patterns can specify a port
+number. If a port number is specified, the pattern only matches websites with
+that port. If no port number is specified, the pattern matches all ports.
+</li>
+</ul>
+</p>
+
+<h3 id="pattern-precedence">Pattern Precedence</h3>

[kathyw, 2011/12/13 02:47:32]

Pattern Precedence -> Pattern precedence

+<p>
+When more than one content setting rule applies for a given site, the rule with
+the more specific pattern takes precedence.
+</p>
+<p>For example, the following patterns are ordered by precedence:

[kathyw, 2011/12/13 02:47:32]

Add </p> at the end

+<ul>

[kathyw, 2011/12/13 02:47:32]

Use a <ol> instead of <ul> here, since the order matters.

(bullets imply that order is unimportant)

+<li><code>http://www.example.com/*</code></li>
+<li><code>http://*.example.com/*</code> (matching
+example.com and all subdomains)</li>
+<li><code>&lt;all_urls&gt;</code> (matching every URL)</li>
+</ul>
+There are three ways in which one pattern can be more specific than another

[kathyw, 2011/12/13 02:47:32]

Add <p> tag; rewrite to be more precise and avoid "There are". Maybe:

<p>
Three kinds of wildcards affect how specific a pattern is:
</p>

+pattern:
+<ul>
+<li>Wildcards in the port (like <code>http://www.example.com:*/*</code>)</li>

[kathyw, 2011/12/13 02:47:32]

like -> for example,

(in this and the following 2 items)

+<li>Wildcards in the scheme (like <code>*://www.example.com:123/*</code>)</li>
+<li>Wildcards in the hostname (like
+  <code>http://*.example.com:123/*</code>)</li>
+</ul>
+If a pattern is more specific than another pattern in one part but less specific
+in another part, the different parts are checked in the following order:
+hostname, scheme, port. That means that for example the list of URLs above is

[kathyw, 2011/12/13 02:47:32]

That means that for example -> For example,

"the list of URLs above..." is imprecise -- I didn't know whether you means the
first list in the section or the second. Change the rest of the paragraph to be
more precise. Maybe:

For example, the following URLs are ordered by precedence:
<ol>
  <li> http://www.example.com:*/*
     <br>
     Specifies the hostname and scheme </li>
  <li> *:/www.example.com:123/*
    <br>
    Not as high, because although it specifies the hostname, it doesn't specify
the scheme </li>
  <li> http://*.example.com:123/*
    <br>
    Lower because although it specifies the port and scheme, it has a wildcard
in the hostname </li>

+ordered by precedence (the first pattern is more specific in the scheme than the
+second one, and the second one is more specific in the hostname than the third
+one).
+</p>
+
+<h2 id="primary-secondary">Primary and Secondary Patterns</h2>

[kathyw, 2011/12/13 02:47:32]

Primary and Secondary Patterns -> Primary and secondary patterns

+<p>
+The URL taken into account when deciding which content setting to apply depends
+on the content type. For example, for
+<a href="#property-notifications">notifications</a> settings are
+based on the URL shown in the omnibox. This URL is called the "primary" URL.</p>
+<p>
+Some content types also can take additional URLs into account. For example,

[kathyw, 2011/12/13 02:47:32]

delete "also" (redundant")

+whether a site is allowed to set a
+<a href="#property-cookies">cookie</a> is decided based on the URL
+of the HTTP request (which is the primary URL in this case) as well as the URL
+shown in the omnibox (which is called the "secondary" URL).
+</p>
+<p>
+If there are multiple rules with primary and secondary patterns, the rule with

[kathyw, 2011/12/13 02:47:32]

Rewrite to avoid "there are" and be clearer. Maybe:

If there are multiple rules with
->
If multiple rules have

+the more specific primary pattern takes precedence. If there are multiple rules

[kathyw, 2011/12/13 02:47:32]

If there are multiple rules with
 ->
If multiple rules have

+with the same primary pattern, the rule with the more specific secondary pattern
+takes precedence. For example, the following list of primary/secondary pattern
+pairs is ordered by precedence:

[kathyw, 2011/12/13 02:47:32]

Add </p> at the end of this paragraph.

+<table>

[kathyw, 2011/12/13 02:47:32]

Add a table header. Perhaps also add a column for the order, to match the <ol>s
above and make the precedence crystal clear:

<tr><th>Precedence</th><th>Primary pattern</th><th>Secondary pattern</th>
<tr><td>1</td><td>...

+<tr>
+  <td><code>http://www.moose.com/*</code>, </td>
+  <td><code>http://www.wombat.com/*</code></td>
+</tr><tr>
+  <td><code>http://www.moose.com/*</code>, </td>
+  <td><code>&lt;all_urls&gt;</code></td>
+</tr><tr>
+  <td><code>&lt;all_urls&gt;</code>, </td>
+  <td><code>http://www.wombat.com/*</code></td>
+</tr><tr>
+  <td><code>&lt;all_urls&gt;</code>, </td>
+  <td><code>&lt;all_urls&gt;</code></td>
+</tr>
+</table>
+</p>
+
+<h2 id="resource-identifiers">Resource Identifiers</h2>

[kathyw, 2011/12/13 02:47:32]

Resource Identifiers -> Resource identifiers

+<p>
+Resource identifiers allow you to specify content settings for specific
+sub-types of a content type. Currently, the only content type that supports

[kathyw, 2011/12/13 02:47:32]

GLOBAL: sub-type -> subtype

+resource identifiers is <a href="#property-plugins"><code>plugins</code></a>,
+where a resource identifier identifies a specific plug-in. When applying content
+settings, first the settings for the specific plug-in are checked. If there are
+no settings found for the specific plug-in, the general content settings for
+plug-ins are checked.
+</p>
+<p>
+For example, if there is a content setting rule with the resource identifier

[kathyw, 2011/12/13 02:47:32]

there is a content setting rule with the
->
a content setting rule has the

+<code>adobe-flash-player</code> and the pattern <code>&lt;all_urls&gt;</code>,
+it takes precedence over a rule without a resource identifier and the pattern
+<code>http://www.example.com/*</code>, even if that pattern is more specific.
+</p>
+<p>
+You can get a list of resource identifiers for a content type by calling the
+<a href=""><code>getResourceIdentifiers</code></a> method. The returned list can

[kathyw, 2011/12/13 02:47:32]

Add "()" after method names. E.g.:

<code>getResourceIdentifiers()</code>

[kathyw, 2011/12/13 02:47:32]

What should this link to?

+change with the set of installed plug-ins on the user's machine, but Chrome
+tries to keep the identifiers stable across plug-in updates.
+</p>
+
+<h2 id="examples">Examples</h2>
+

[kathyw, 2011/12/13 02:47:32]

It'd be nice to have a brief example of using the content settings API here, in
a <pre> section.

and actually... I can't find any examples in the Samples page. I mean, there are
3 samples that use contentSettings, but no .js files are listed there.

+<p>
+You can find samples of this API on the
+<a href="samples.html#contentSettings">sample page</a>.
+</p>
+
+<!-- END AUTHORED CONTENT -->