Document the activeTab extension permission.

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

Index: chrome/common/extensions/docs/static/activeTab.html
diff --git a/chrome/common/extensions/docs/static/activeTab.html b/chrome/common/extensions/docs/static/activeTab.html
new file mode 100644
index 0000000000000000000000000000000000000000..c22d8ba2eae0ddc6cd8e83d0fd33a54f2b359070
--- /dev/null
+++ b/chrome/common/extensions/docs/static/activeTab.html
@@ -0,0 +1,25 @@
+<div id="pageData-name" class="pageData">The activeTab permission</div>
+
+<p>
+The <code>activeTab</code> permission is for extensions that perform an action on a tab in response to the user. For example, an extension with a browser action that changes the formatting of the current page when clicked, or has a context menu which acts on the word that was clicked on.

[Aaron Boodman, 2012/08/24 14:09:25]

More direct:

The _activeTab_ permission allows extensions to access the active tab in
response to user gestures like clicking an extension button or context menu
item.

[not at google - send to devlin, 2012/08/27 04:45:50]

Done.

+</p>
+
+<p>
+Traditionally such extensions would need to request both the <code>&lt;all_urls&gt;</code> permission and the <code>tabs</code> permission, requiring a scary install warning. With the <code>activeTab</code> permission, none of that is necessary.

[Aaron Boodman, 2012/08/24 14:09:25]

Maybe you could turn this into a story/example:

Many extensions only need access to a page in response to a user gesture on the
extension. For example, consider a web clipping extension that has a browser
action and context menu item. The extension doesn't need to run automatically on
all pages, it only needs to run when one of its UI surfaces is acted upon.

Without activeTab ...

[not at google - send to devlin, 2012/08/27 04:45:50]

Done.

+</p>
+
+</p>
+Formally, the <code>activeTab</code> permission allows an extension to use <a href="tabs.html#method-executeScript">tabs.executeScript</a> and <a href="tabs.html#method-insertCSS">tabs.insertCSS</a> on any tab the extension has been invoked on, including any frames with the same security origin. The permission lasts until the tab is navigated.
+</p>
+
+<p>
+The following qualify as invocations:

[Aaron Boodman, 2012/08/24 14:09:25]

Since this is likely to rot, let's weaken it slightly:

The activeTab permission is activated whenever a piece of extension UI is acted
upon by a user. At the time of writing, examples of such UI include:

...

But this list will grow over time as more types of extension  UI are added.

[not at google - send to devlin, 2012/08/27 04:45:50]

Done.

Is it "extension UI are..." or "extension UIs are..."?

+<ul>
+  <li>clicking on an extension’s browser action,
+  <li>clicking on an extension’s page action,
+  <li>clicking on an extension’s script badge,
+  <li>accepting a suggestion from an extension’s omnibox,
+  <li>invoking an action from an extension’s context menu, or
+  <li>executing a command configured for an extension.
+</ul>
+</p>