Extensions Docs Server: Doc conversion script

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

Index: chrome/common/extensions/docs/server2/templates/articles/faq.html
diff --git a/chrome/common/extensions/docs/server2/templates/articles/faq.html b/chrome/common/extensions/docs/server2/templates/articles/faq.html
new file mode 100644
index 0000000000000000000000000000000000000000..9cec4d9c130a1d672baaba961c6f9a1695b18909
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/articles/faq.html
@@ -0,0 +1,486 @@
+<h1>Frequently Asked Questions</h1>
+
+
+<!--  -->
+
+<p>
+If you don't find an answer to your question here,
+try the
+<a href="http://code.google.com/chrome/webstore/faq.html">Chrome Web Store FAQ</a>, the
+<a href="http://stackoverflow.com/questions/tagged/google-chrome-extension">[google-chrome-extension] tag on Stack Overflow</a>, the
+<a href="http://groups.google.com/a/chromium.org/group/chromium-extensions">group</a>, or the
+<a href="http://www.google.com/support/chrome_webstore/">store help</a>.
+</p>
+
+<div id="faq-TOC">
+  <h4>General</h4>
+  <ul>
+    <li><a href="#faq-gen-01">What are Google Chrome Extensions?</a></li>
+    <li><a href="#faq-dev-01">How can I set up Chrome for extension development?</a></li>
+    <li><a href="#faq-gen-02">What technologies are used to write extensions for Chrome?</a></li>
+    <li><a href="#faq-gen-03">Are extensions fetched from the web every time the browser is loaded?</a></li>
+    <li><a href="#faq-dev-14">How do I determine which version of Chrome is deployed to which channel?</a></li>
+  </ul>
+  <h4>Capabilities</h4>
+  <ul>
+    <li><a href="#faq-dev-02">Can extensions make cross-domain Ajax requests?</a></li>
+    <li><a href="#faq-dev-03">Can extensions use 3rd party web services?</a></li>
+    <li><a href="#faq-dev-07">Can extensions encode/decode JSON data?</a></li>
+    <li><a href="#faq-dev-08">Can extensions store data locally?</a></li>
+    <li><a href="#faq-dev-04">Can extensions use OAuth?</a></li>
+    <li><a href="#faq-dev-06">Can extensions load DLLs?</a></li>
+    <li><a href="#faq-dev-05">Can extensions create UI outside of the rendered web page?</a></li>
+    <li><a href="#faq-interact-chrome">Can extensions listen to clicks on Chrome tabs and navigation buttons?</a>
+    <li><a href="#faq-dev-11">Can two extensions communicate with each other?</a></li>
+    <li><a href="#faq-dev-13">Can extensions use Google Analytics?</a></li>
+    <li><a href="#faq-dev-15">Can extensions modify chrome:// URLs?</a></li>
+    <li><a href="#faq-open-popups">Can extensions open browser/page action popups without user interaction?</a></li>
+    <li><a href="#faq-persist-popups">Can extensions keep popups open after the user clicks away from them?</a></li>
+    <li><a href="#faq-lifecycle-events">Can extensions be notified when they are installed/uninstalled?</a></li>
+  </ul>
+  <h4>Development</h4>
+  <ul>
+    <li><a href="#faq-building-ui">How do I build a UI for my extension?</a>
+    <li><a href="#faq-dev-09">How much data can I store in localStorage?</a></li>
+    <li><a href="#faq-dev-10">How do I create an options menu for my application?</a></li>
+    <li><a href="#faq-dev-12">What debugging tools are available to extension developers?</a></li>
+    <li><a href="#faq-dev-16">Why do wildcard matches not work for top level domains (TLDs)?</a></li>
+    <li><a href="#faq-management">Why does the management API not fire events when my extension is installed/uninstalled?</a></li>
+    <li><a href="#faq-firstrun">How can an extension determine whether it is running for the first time?</a></li>
+  </ul>
+  <h4>Features and bugs</h4>
+  <ul>
+    <li><a href="#faq-fea-01">I think I've found a bug! How do I make sure it gets fixed?</a></li>
+    <li><a href="#faq-fea-02">I have a feature request! How can I report it?</a></li>
+  </ul>
+</div>
+
+<h2>General</h2>
+
+<h3 id="faq-gen-01">What are Google Chrome Extensions?</h3>
+<p>
+  Google Chrome Extensions are applications that run inside the
+  Chrome browser and provide additional functionality, integration with third
+  party websites or services, and customized browsing experiences.
+</p>
+
+<h3 id="faq-dev-01">How can I set up Chrome for extension development?</h3>
+<p>
+  As long as you are using a version of Chrome that supports
+  extensions, you already have everything you need to start writing an
+  extension of your own.
+  You can start by turning on Developer mode.
+  </p>
+
+  <p>
+  Click the wrench icon
+  <img src="{{static}}/images/toolsmenu.gif" height="29" width="29" alt=""
+    class="nomargin" />
+  and select <b>Extensions</b> from the <b>Tools</b> menu.
+  If there's a "+" next to "Developer mode",
+  click the "+" so it turns into a "-".
+  Now you can reload extensions,
+  load an unpacked directory of files as if it were a packaged extension,
+  and more. For a complete tutorial, see
+  <a href="http://code.google.com/chrome/extensions/getstarted.html">Getting Started</a>.
+</p>
+
+<h3 id="faq-gen-02">What technologies are used to write extensions for Chrome?</h3>
+<p>
+  Extensions are written using the same standard web
+  technologies that developers use to create websites. HTML is used as a
+  content markup language, CSS is used for styling, and JavaScript for
+  scripting. Because Chrome supports HTML5 and CSS3, developers can
+  use the latest open web technologies such as canvas and CSS animations in
+  their extensions. Extensions also have access to several
+  <a href="http://code.google.com/chrome/extensions/api_other.html">JavaScript APIs</a>
+  that help perform functions like JSON encoding and interacting with the
+  browser.
+</p>
+
+
+<h3 id="faq-gen-03">Are extensions fetched from the web every time the browser is loaded?</h3>
+<p>
+  Extensions are downloaded by the Chrome browser upon install, and
+  are subsequently run off of the local disk in order to speed up
+  performance. However, if a new version of the extension is pushed online,
+  it will be automatically downloaded in the background to any users who
+  have the extension installed. Extensions may also make requests for remote
+  content at any time, in order to interact with a web service or pull new
+  content from the web.
+</p>
+
+<h3 id="faq-dev-14">How do I determine which version of Chrome is deployed to which channel?</h3>
+<p>
+  To determine which version of Chrome is currently available on each
+  of the different platforms, visit
+  <a href="http://omahaproxy.appspot.com">omahaproxy.appspot.com</a>.  On that
+  site you will see data in a format similar to:
+</p>
+
+<pre>cf,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+cf,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+cf,stable,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+linux,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+linux,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+linux,stable,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+mac,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+mac,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+mac,stable,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+win,canary,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+win,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+win,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+win,stable,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+cros,dev,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####
+cros,beta,#.#.###.#,#.#.###.#,mm/dd/yy,mm/dd/yy,#####,#####,#####</pre>
+
+<p>
+  Each line represents information about a different platform and channel
+  combination. The
+  listed platforms are <code>cf</code> (Google Chrome Frame),
+  <code>linux</code>, <code>mac</code>, <code>win</code>, and
+  <code>cros</code> (Google Chrome OS).  The listed
+  channels are <code>canary</code>, <code>dev</code>, <code>beta</code>,
+  and <code>stable</code>.
+  The two four-part numbers after the channel represent the current and previous
+  versions of Chrome deployed to that platform-channel
+  combination.  The rest of the information is metadata about when the releases
+  were first pushed, as well as revision numbers associated with each build.
+</p>
+
+
+<h2>Capabilities</h2>
+
+<h3 id="faq-dev-02">Can extensions make cross-domain Ajax requests?</h3>
+<p>
+  Yes. Extensions can make cross-domain requests.  See
+  <a href="http://code.google.com/chrome/extensions/xhr.html">this page</a>
+  for more information.
+</p>
+
+<h3 id="faq-dev-03">Can extensions use 3rd party web services?</h3>
+<p>
+  Yes. Extensions are capable of making cross-domain Ajax
+  requests, so they can call remote APIs directly. APIs that provide data
+  in JSON format are particularly easy to use.
+</p>
+
+<h3 id="faq-dev-07">Can extensions encode/decode JSON data?</h3>
+<p>
+  Yes, because V8 (Chrome's JavaScript engine) supports
+  JSON.stringify and JSON.parse natively, you may use these functions in your
+  extensions
+  <a href="http://json.org/js.html">as described here</a> without including
+  any additional JSON libraries in your code.
+</p>
+
+<h3 id="faq-dev-08">Can extensions store data locally?</h3>
+<p>
+  Yes, extensions can use <a href="http://dev.w3.org/html5/webstorage/">localStorage</a>
+  to store string data permanently. Using Chrome's built-in JSON
+  functions, you can store complex data structures in localStorage.  For
+  extensions that need to execute SQL queries on their stored data,
+  Chrome implements
+  <a href="http://dev.w3.org/html5/webdatabase/">client side SQL databases</a>,
+  which may be used as well.
+</p>
+
+<h3 id="faq-dev-04">Can extensions use OAuth?</h3>
+<p>
+  Yes, there are extensions that use OAuth to access remote data
+  APIs. Most developers find it convenient to use a
+  <a href="http://unitedheroes.net/OAuthSimple/js/OAuthSimple.js">JavaScript OAuth library</a>
+  in order to simplify the process of signing OAuth requests.
+</p>
+
+<h3 id="faq-dev-06">Can extensions load DLLs?</h3>
+<p>
+  Yes, using the <a href="npapi.html">NPAPI interface</a>.
+  Because of the possibility for abuse, though, we will review your extension
+  before hosting it in the Chrome Web Store.
+</p>
+
+<h3 id="faq-dev-05">Can extensions create UI outside of the rendered web page?</h3>
+<p>
+  Yes, your extension may add buttons to the Chrome browser's user interface.
+  See <a href="browserAction.html">browser actions</a> and
+  <a href="pageAction.html">page actions</a> for more information.
+</p>
+<p>
+  An extension may also create popup notifications, which exist outside of the
+  browser window.  See the <a href="notifications.html">desktop
+    notifications</a> documentation for more details.
+</p>
+
+<h3 id="faq-interact-chrome">Can extensions listen to clicks on Chrome tabs and
+  navigation buttons?</h3>
+<p>
+  No.  Extensions are limited to listening to the events described in the <a
+    href="api_index.html">API documentation</a>.
+</p>
+
+<h3 id="faq-dev-11">Can two extensions communicate with each other?</h3>
+<p>
+  Yes, extensions may pass messages to other extensions. See the
+  <a href="messaging.html#external">message passing documentation</a>
+  for more information.
+</p>
+
+<h3 id="faq-dev-13">Can extensions use Google Analytics?</h3>
+<p>
+  Yes, since extensions are built just like websites, they can use
+  <a href="http://www.google.com/analytics/">Google Analytics</a> to track
+  usage.  However, we strongly advise you to modify the tracking code to pull
+  an HTTPS version of the Google Analytics library.  See
+  <a href="tut_analytics.html">this tutorial</a> for more information on doing
+  this.
+</p>
+
+<h3 id="faq-dev-15">Can extensions modify chrome:// URLs?</h3>
+<p>
+  No. The extensions APIs have been designed to minimize backwards
+  compatibility issues that can arise when new versions of the browser are
+  pushed. Allowing content scripts on <code>chrome://</code>
+  URLs would mean that developers would begin to rely on the DOM, CSS, and
+  JavaScript of these pages to stay the same.  In the best case, these pages
+  could not be updated as quickly as they are being updated right now.
+  In the worst case, it could mean that an update to one
+  of these pages could cause an extension to break, causing key parts of the
+  browser to stop working for users of that extension.
+</p>
+
+<p>
+  The reason that <a href="override.html">replacing the content</a>
+  hosted at these URLs entirely is
+  allowed is because it forces an extension developer to implement all of the
+  functionality they want without depending on the browser's internal implementation
+  to stay the same.
+</p>
+
+<h3 id="faq-open-popups">Can extensions open browser/page action popups without
+  user interaction?</h3>
+<p>
+  No, popups can only be opened if the user clicks on the corresponding page or
+  browser action.  An extension cannot open its popup programatically.
+</p>
+
+<h3 id="faq-persist-popups">Can extensions keep popups open after the user
+  clicks away from them?</h3>
+<p>
+  No, popups automatically close when the user focuses on some portion of the
+  browser outside of the popup.  There is no way to keep the popup open after
+  the user has clicked away.
+</p>
+
+<h3 id="faq-lifecycle-events">Can extensions be notified when they are
+  installed/uninstalled?</h3>
+<p>
+  No, there are no events an extension can listen to in order to determine
+  whether it has been installed or uninstalled.  However, an extension can
+  determine when it has been run for the first time.  See <a
+    href="#faq-firstrun">this FAQ entry</a> for information.
+</p>
+
+
+<h2>Development</h2>
+
+
+<h3 id="faq-building-ui">How do I build a UI for my extension?</h3>
+<p>
+  Extensions use HTML and CSS to define their user interfaces, so you can use
+  standard form controls to build your UI, or style the interface with CSS,
+  as you would a web page.  Additionally, extensions can add
+  <a href="#faq-dev-05">some limited UI elements to Chrome itself.</a>
+</p>
+
+<h3 id="faq-dev-09">How much data can I store in localStorage?</h3>
+<p>
+  Extensions can store up to 5MB of data in localStorage.
+</p>
+
+<h3 id="faq-dev-10">How do I create an options menu for my application?</h3>
+<p>
+  You can let users set options for your extension by creating an
+  <a href="http://code.google.com/chrome/extensions/trunk/options.html">options page</a>,
+  which is a simple HTML page that will be loaded when a user clicks the
+  "options" button for your extension. This page can read and write settings
+  to localStorage, or even send options to a web server so that they can be
+  persisted across browsers.
+</p>
+
+<h3 id="faq-dev-12">What debugging tools are available to extension developers?</h3>
+<p>
+  Chrome's built-in developer tools can be used to debug extensions
+  as well as web pages. See this
+  <a href="http://code.google.com/chrome/extensions/tut_debugging.html ">tutorial on debugging extensions</a>
+  for more information.
+</p>
+
+<h3 id="faq-dev-16">Why do wildcard matches not work for top level domains
+  (TLDs)?</h3>
+<p>
+  You cannot use wildcard match patterns like <code>http://google.*/*</code>
+  to match TLDs (like <code>http://google.es</code> and
+  <code>http://google.fr</code>) due to the
+  complexity of actually restricting such a match to only the desired domains.
+</p>
+<p>
+  For the example of <code>http://google.*/*</code>, the Google domains would
+  be matched, but so would <code>http://google.someotherdomain.com</code>.
+  Additionally, many sites do not own all of the TLDs for their
+  domain.  For an example, assume you want to use
+  <code>http://example.*/*</code> to match <code>http://example.com</code> and
+  <code>http://example.es</code>, but <code>http://example.net</code> is a
+  hostile site.  If your extension has a bug, the hostile site could potentially
+  attack your extension in order to get access to your extension's increased
+  privileges.
+</p>
+<p>
+  You should explicitly enumerate the TLDs that you wish to run
+  your extension on.
+</p>
+
+<h3 id="faq-management">Why does the management API not fire events when my
+  extension is installed/uninstalled?</h3>
+<p>
+  The <a href="management.html">management API</a> was intended to help create
+  new tab page replacement extensions.  It was not intended to fire
+  install/uninstall events for the current extension.
+</p>
+
+<h3 id="faq-firstrun">How can an extension determine whether it is running for
+  the first time?</h3>
+<p>
+  An extension can check to see whether it is running for the first time by
+  checking for the presence of a value in localStorage, and writing the value if
+  it does not exist. For example:
+</p>
+
+<pre>var firstRun = (localStorage['firstRun'] == 'true');
+if (!firstRun) {
+  localStorage['firstRun'] = 'true';
+}</pre>
+
+<p>
+  Note that this check should be run in a background page, not a content script.
+</p>
+
+
+<h2>Features and bugs</h2>
+
+
+<h3 id="faq-fea-01">I think I've found a bug! How do I make sure it gets
+  fixed?</h3>
+<p>
+  While developing an extension, you may find behavior that does not
+  match the extensions documentation and may be the result of a bug in
+  Chrome.  The best thing to do is to make sure an appropriate issue
+  report is filed, and the Chromium team has enough information to reproduce
+  the behavior.
+</p>
+
+<p>The steps you should follow to ensure this are:</p>
+
+<ol>
+  <li>
+    Come up with a <em>minimal</em> test extension that demonstrates the issue
+    you wish to report.  This extension should have as little code as possible
+    to demonstrate the bug&mdash;generally this should be 100 lines of
+    code or less.  Many times, developers find that they cannot reproduce their
+    issues this way, which is a good indicator that the bug is in their own
+    code.
+  </li>
+  <li>
+    Search the issue tracker at
+    <a href="http://www.crbug.com">http://www.crbug.com</a> to see whether
+    someone has reported a similar issue.  Most issues related to
+    extensions are filed under <strong>Feature=Extensions</strong>, so to
+    look for an extension bug related to the
+    chrome.tabs.executeScript function (for example), search for
+    "<code>Feature=Extensions Type=Bug chrome.tabs.executeScript</code>",
+    which will give you
+    <a href="http://code.google.com/p/chromium/issues/list?can=2&q=Feature%3DExtensions+Type%3DBug+chrome.tabs.executeScript&colspec=ID+Stars+Pri+Area+Feature+Type+Status+Summary+Modified+Owner+Mstone+OS&x=mstone&y=area&cells=tiles">
+    this list of results</a>.
+  </li>
+  <li>
+    If you find a bug that describes your issue, click the star icon to be
+    notified when the bug receives an update.  <em>Do not respond to the
+    bug to say "me too" or ask "when will this be fixed?"</em>; such updates
+    can cause hundreds of emails to be sent.  Add a comment only if you have
+    information (such as a better test case or a suggested fix) that is likely
+    to be helpful.
+  </li>
+  <li>
+    If you found no appropriate bug to star, file a new issue report at
+    <a href="http://new.crbug.com">http://new.crbug.com</a>.  Be as explicit
+    as possible when filling out this form: choose a descriptive title,
+    explain the steps to reproduce the bug, and describe the expected and
+    actual behavior.  Attach your test example to the report and add
+    screenshots if appropriate.  The easier your report makes it for others
+    to reproduce your issue, the greater chance that your bug will be fixed
+    promptly.
+  </li>
+  <li>
+    Wait for the bug to be updated.  Most new bugs are triaged within a week,
+    although it can sometimes take longer for an update.  <em>Do not reply
+    to the bug to ask when the issue will be fixed.</em>  If your bug has not
+    been modified after two weeks, please post a message to the
+    <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions/topics">
+    discussion group</a> with a link back to your bug.
+  </li>
+  <li>
+    If you originally reported your bug on the discussion group and were
+    directed to this FAQ entry, reply to your original thread with a link
+    to the bug you starred or reported.  This will make it easier for others
+    experiencing the same issue to find the correct bug.
+  </li>
+</ol>
+
+<h3 id="faq-fea-02">I have a feature request! How can I report it?</h3>
+
+<p>If you identify a feature (especially if it's related to an experimental
+  API) that could be added to improve the extension development experience,
+  make sure an appropriate request is filed in the issue tracker.</p>
+
+<p>The steps you should follow to ensure this are:</p>
+
+<ol>
+  <li>
+    Search the issue tracker at
+    <a href="http://www.crbug.com">http://www.crbug.com</a> to see whether
+    someone has requested a similar feature.  Most requests related to
+    extensions are filed under <strong>Feature=Extensions</strong>, so to
+    look for an extension feature request related to keyboard shortcuts
+    (for example), search
+    for "<code>Feature=Extensions Type=Feature shortcuts</code>",
+    which will give you
+    <a href="http://code.google.com/p/chromium/issues/list?can=2&q=Feature%3DExtensions+Type%3DFeature+shortcuts&colspec=ID+Stars+Pri+Area+Feature+Type+Status+Summary+Modified+Owner+Mstone+OS&x=mstone&y=area&cells=tiles">
+    this list of results</a>.
+  </li>
+  <li>
+    If you find a ticket that matches your request, click the star icon to be
+    notified when the bug receives an update.  <em>Do not respond to the
+    bug to say "me too" or ask "when will this be implemented?"</em>; such
+    updates can cause hundreds of emails to be sent.
+  </li>
+  <li>
+    If you found no appropriate ticket to star, file a new request at
+    <a href="http://new.crbug.com">http://new.crbug.com</a>.  Be as detailed
+    as possible when filling out this form: choose a descriptive title
+    and explain exactly what feature you would like and how you plan to use it.
+  </li>
+  <li>
+    Wait for the ticket to be updated.  Most new requests are triaged within a
+    week, although it can sometimes take longer for an update.  <em>Do not reply
+    to the ticket to ask when the feature will be added.</em>  If your
+    ticket has not been modified after two weeks, please post a message to the
+    <a href="http://groups.google.com/a/chromium.org/group/chromium-extensions/topics">
+    discussion group</a> with a link back to your request.
+  </li>
+  <li>
+    If you originally reported your request on the discussion group and were
+    directed to this FAQ entry, reply to your original thread with a link
+    to the ticket you starred or opened.  This will make it easier for others
+    with the same request to find the correct ticket.
+  </li>
+</ol>