Extensions Docs Server: Doc conversion script

chrome/common/extensions/docs/server2/templates/intros/web_navigation.html

-<!-- BEGIN AUTHORED CONTENT -->
+
+
+
 <p id="classSummary">
 Use the <code>chrome.webNavigation</code> module to receive
 notifications about the status of navigations requests in-flight.
 </p>
+
 <h2>Manifest</h2>
 <p>
 All <code>chrome.webNavigation</code> methods and events require you to declare
 the "webNavigation" permission in the <a href="manifest.html">extension
 manifest</a>.
 For example:
 </p>
+
 <pre>{
   "name": "My extension",
   ...
   <b>"permissions": [
     "webNavigation"
   ]</b>,
   ...
 }</pre>
+
+
 <h2>Examples</h2>
+
 <p>
 You can find simple examples of using the tabs module in the
 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/webNavigation/">examples/api/webNavigation</a>
 directory.
 For other examples and for help in viewing the source code, see
 <a href="samples.html">Samples</a>.
 </p>
+
 <h2>Event order</h2>
 <p>
 For a navigation that is successfully completed, events are fired in the
 following order:
 <pre>
 onBeforeNavigate -&gt; onCommitted -&gt; onDOMContentLoaded -&gt; onCompleted
 </pre>
 </p>
 <p>
 Any error that occurs during the process results in an
 <code>onErrorOccurred</code> event. For a specific navigation, there are no
 further events fired after <code>onErrorOccurred</code>.
 </p>
 <p>
 If a navigating frame contains subframes, its <code>onCommitted</code> is fired
 before any of its children's <code>onBeforeNavigate</code>; while
 <code>onCompleted</code> is fired after all of its children's
 <code>onCompleted</code>.
 </p>
 <p>
 If the reference fragment of a frame is changed, a
 <code>onReferenceFragmentUpdated</code> event is fired. This event can fire any
 time after <code>onDOMContentLoaded</code>, even after
 <code>onCompleted</code>.
 </p>
+<p>
+If the history API is used to modify the state of a frame (e.g. using
+<code>history.pushState()</code>, a <code>onHistoryStateUpdated</code> event is
+fired. This event can fire any time after <code>onDOMContentLoaded</code>.
+</p>
+<p>
+If a navigation was triggered via <a
+href="https://support.google.com/chrome/bin/answer.py?answer=177873">Chrome
+Instant</a> or <a
+href="https://support.google.com/chrome/bin/answer.py?answer=1385029">Instant
+Pages</a>, a completely loaded page is swapped into the current tab. In that
+case, an <code>onTabReplaced</code> event is fired.
+</p>
+
 <h2>Relation to webRequest events</h2>
 <p>
 There is no defined ordering between events of the <a
 href="webRequest.html">webRequest API</a> and the events of the
 webNavigation API. It is possible that webRequest events are still received for
 frames that already started a new navigation, or that a navigation only
 proceeds after the network resources are already fully loaded.
 </p>
 <p>
 In general, the webNavigation events are closely related to the navigation
 state that is displayed in the UI, while the webRequest events correspond to
 the state of the network stack which is generally opaque to the user.
 </p>
+
+<h2>A note about tab IDs</h2>
+<p>
+Not all navigating tabs correspond to actual tabs in Chrome's UI, e.g., a tab
+that is being pre-rendered. Such tabs are not accessible via the
+<a href="tabs.html">tabs API</a> nor can you request information about them via
+<code>webNavigation.getFrame</code> or <code>webNavigation.getAllFrames</code>.
+Once such a tab is swapped in, an <code>onTabReplaced</code> event is fired and
+they become accessible via these APIs.
+</p>
+
 <h2>A note about timestamps</h2>
 <p>
 It's important to note that some technical oddities in the OS's handling
 of distinct Chrome processes can cause the clock to be skewed between the
 browser itself and extension processes. That means that WebNavigation's events'
 <code>timeStamp</code> property is only guaranteed to be <i>internally</i>
 consistent. Comparing one event to another event will give you the correct
 offset between them, but comparing them to the current time inside the
 extension (via <code>(new Date()).getTime()</code>, for instance) might give
 unexpected results.
 </p>
+
+<h2>A note about frame and process IDs</h2>
+<p>
+Due to the multi-process nature of Chrome, a tab might use different processes
+to render the source and destination of a web page. Therefore, if a navigation
+takes place in a new process, you might receive events both from the new and
+the old page until the new navigation is committed (i.e. the
+<code>onCommitted</code> event is send for the new main frame). Because frame
+IDs are only unique for a given process, the webNavigation events include a
+process ID, so you can still determine which frame a navigation came from.
+</p>
+<p>
+Also note that during a provisional load the process might be switched several
+times. This happens when the load is redirected to a different site. In this
+case, you will receive repeated <code>onBeforeNavigate</code> and
+<code>onErrorOccurred</code> events, until you receive the final
+<code>onCommitted</code> event.
+</p>
+
 <h2>Transition types and qualifiers</h2>
 <p>
 The webNavigation API's <code>onCommitted</code> event has a
 <code>transitionType</code> and a <code>transitionQualifiers</code> property.
 The <em>transition type</em> is the same as used in the <a
 href="history.html#transition_types">history API</a> describing how the browser
 navigated to this particular URL. In addition, several <em>transition
 qualifiers</em> can be returned that further define the navigation.
 </p>
 <p>
@@ skipping 23 matching lines @@
     The user used the Forward or Back button to initiate the navigation.
   </td>
 </tr>
 <tr>
   <td>"from_address_bar"</td>
   <td>
     The user initiated the navigation from the address bar (aka Omnibox).
   </td>
 </tr>
 </table>
-<!-- END AUTHORED CONTENT -->
+
+