Document the activeTab extension permission.

chrome/common/extensions/docs/server2/templates/articles/activeTab.html

Index: chrome/common/extensions/docs/server2/templates/articles/activeTab.html
diff --git a/chrome/common/extensions/docs/server2/templates/articles/activeTab.html b/chrome/common/extensions/docs/server2/templates/articles/activeTab.html
new file mode 100644
index 0000000000000000000000000000000000000000..b2c430cb3b40b4520ec1fa0c405bf96acd98058e
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/articles/activeTab.html
@@ -0,0 +1,30 @@
+<h1>The activeTab permission</h1>

[mkearney1, 2012/09/12 17:02:37]

General comment: I like the heading style in the original doc but I can
understand that it might seem too much for the content within-- it might be good
to have a couple of headings like:

'What activeTab allows'

'Invoking activeTab'

+
+<p>
+The <code>activeTab</code> permission allows extensions to access the active tab in response to user gestures like clicking an <a href="browserAction.html">extension button</a> or <a href="contextMenus.html">context menu item</a>.

[mkearney1, 2012/09/12 17:02:37]

I kind of like parts of the original active tab intro better, so i am going to
try a little combination here:

The activeTab permission allows an extension to access the currently active tab
in response to user gestures like ... 

+</p>
+
+<p>
+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.
+</p>
+
+<p>
+Without <code>activeTab</code> the extension would need to request both the <code>&lt;all_urls&gt;</code> and <code>tabs</code> permissions, showing a scary warning on installation. With <code>activeTab</code> none of that will be necessary.

[mkearney1, 2012/09/12 17:02:37]

Does a warning get displayed to the user at any time, say when the user first
clicks on the extension UI? This sort of implies there is no message, but surely
there is some sort of permission granting.

[mkearney1, 2012/09/12 17:02:37]

Nit, commas after 'Without activeTab' and 'With activeTab'.

+</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 <code>activeTab</code> 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:
+<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, and
+  <li>executing a command configured for an extension.
+</ul>

[mkearney1, 2012/09/12 17:02:37]

I'm a little bit curious about the last item here - executing a command
configured for an extension. Could we have an example of this?

+But this list will grow over time as more types of extension UIs are added.
+</p>