Added a note about disabling pushState in the "linking pages" section, cleaned up language.

Author: toddparker

docs/pages/page-links.html

@@ -39,7 +39,9 @@ <h2>Default link behavior: Ajax</h2>
 
 <h2>Linking without Ajax</h2>
 
-		<p>Links that point to other domains or that have <code>rel="external"</code>, <code>data-ajax="false"</code> or <code>target</code> attributes will not be loaded with Ajax. Instead, these links and will cause a full page refresh with no animated transition. Both attributes have the same effect, but different semanic meaning. <code>rel="external"</code> should be used when linking to another site or domain, while <code>data-ajax="false"</code> is useful for simply opting a page within your domain from being loaded via Ajax. Because of security restrictions, the framework always opts links to external domains out of the Ajax behavior.</p>
+		<p>Links that point to other domains or that have <code>rel="external"</code>, <code>data-ajax="false"</code> or <code>target</code> attributes will not be loaded with Ajax. Instead, these links and will cause a full page refresh with no animated transition. Both attributes have the same effect, but different semantic meaning: <code>rel="external"</code> should be used when linking to another site or domain, while <code>data-ajax="false"</code> is useful for simply opting a page within your domain from being loaded via Ajax. Because of security restrictions, the framework always opts links to external domains out of the Ajax behavior.</p>
+		
+		<p>Note: When building a jQuery Mobile application where the Ajax navigation system is disabled globally or frequently disabled on individual links, we  recommend disabling the <code>$.mobile.pushStateEnabled</code> global <a href="../api/globalconfig.html">configuration option</a> to avoid inconsistent navigation behavior in some browsers.</p>
 
 
 

docs/pages/page-navmodel.html

@@ -43,9 +43,9 @@ <h2>Hash and Ajax driven page navigation</h2>
 
 			<p>Once the referenced page is present in the DOM, the <code>$.mobile.changePage()</code> function applies a transition between the current active page and the new page. Page transitions happen through adding and removing classes that apply CSS animations. For example, in a slide-left transition, the exiting page is given the classes "slideleft" and "out", and the entering page is given the classes <code>"slideleft"</code> and <code>"in"</code>, as well as a class of <code>"ui-page-active"</code> to mark it as the new "active" page being viewed. When the animation is complete, the <code>"in"</code> and <code>"out"</code> classes are removed, and the exited page loses its <code>"ui-page-active"</code> class.</p>
 
-			<h2>replaceState plugin</h2>
+			<h2>pushState plugin</h2>
 
-			<p>For those browsers that support <code>history.replaceState</code>, an optional plugin is provided that will convert the hash change urls mentioned in the previous section into the full document path which is cleaner and makes the Ajax tracking transparent in the URL structure. This is built as an enhancement on top of the hash-based URL system for Ajax links. For browsers that do not support <code>history.replaceState</code>, or if this feature is disabled, hash-based URLs will be used instead. Note that this feature converts hash-based urls by using <code>history.replaceState</code> (not <code>history.pushState</code>) because this works more reliably across our target platforms. </p>
+			<p>There is an optional feature is converts the longer, hash-based URLs mentioned in the previous section into the full document path which is cleaner and makes the Ajax tracking transparent in the URL structure. This is built as an enhancement on top of the hash-based URL system for Ajax links. Note that despite the name, this feature technically converts hash-based urls by using <code>history.replaceState</code> (not <code>history.pushState</code>) in the current release because this works more reliably across our target platforms. For browsers that do not support <code>history.replaceState</code>, or if this feature is disabled, hash-based URLs will be used instead. </p>
 
 			<p>Since the plugin initializes when the DOM is fully loaded you can enable and disable it manually by setting <code>$.mobile.pushStateEnabled</code> global <a href="../api/globalconfig.html">configuration option</a> to <code>false</code> anytime before document ready.</p>
 
@@ -62,7 +62,7 @@ <h2>changePage</h2>
 
 			<h2>Base element</h2>
 
-			<p>Another key ingredient to jQuery Mobile's page navigation model is the <code>base</code> element, which is injected into the <code>head</code> and modified on every page change to ensure that any assets (css,images,js,etc) referenced on that page will be requested from a proper path. In browsers that don't support dynamic updates to the <code>base</code> element (such as Firefox 3.6), jQuery Mobile loops through all of the referenced assets on the page and prefixes their href and src attributes with the base path.</p>
+			<p>Another key ingredient to jQuery Mobile's page navigation model is the <code>base</code> element, which is injected into the <code>head</code> and modified on every page change to ensure that any assets (images, CSS, JS, etc.) referenced on that page will be requested from a proper path. In browsers that don't support dynamic updates to the <code>base</code> element (such as Firefox 3.6), jQuery Mobile loops through all of the referenced assets on the page and prefixes their href and src attributes with the base path.</p>
 
 
 			<h2>Developer explanation of base url management:</h2>
@@ -73,7 +73,7 @@ <h2>Developer explanation of base url management:</h2>
 
 			<h2>Data-url storage</h2>
 
-			<p>The nav model maintains a data-url attribute on all data-role=”page” elements. This data-url attribute is used to track the origin of the page element. Pages embedded within the main application document all have their data-url parameter set to the ID of the @data-role="page" element. The only exception to this is the first-page in the document. The first-page is special because it can be addressed by its @id if it has one, or by the document or base URL (with no hash fragment).</p>
+			<p>The nav model maintains a data-url attribute on all data-role="page" elements. This data-url attribute is used to track the origin of the page element. Pages embedded within the main application document all have their data-url parameter set to the ID of the @data-role="page" element. The only exception to this is the first-page in the document. The first-page is special because it can be addressed by its @id if it has one, or by the document or base URL (with no hash fragment).</p>
 
 			<p>Pages that are external to the application document get pulled in dynamically via ajax, their data-url is set to the site relative path to the external page. If you are running in an environment where loading an external page from a different domain is allowed, then the data-url is set to the absolute URL.</p>