From 5342f65aa81005fa6ba310d0d35ec41f3d0bff00 Mon Sep 17 00:00:00 2001
From: Scott Main <smain@google.com>
Date: Tue, 10 Sep 2013 10:54:46 -0700
Subject: update web app docs to remove target-densitydpi, remove the overview
 page, remove a bunch of stuff from the doc about screens and refer to
 external docs instead, and add tips about debugging on 4.4 w/ dev tools.

Change-Id: I1fadb7cdf6fee469dc41a1f4e2dc2daf1fde52d1
---
 docs/html/guide/guide_toc.cs                       |   5 +-
 docs/html/guide/webapps/best-practices.jd          |  18 +
 docs/html/guide/webapps/debugging.jd               |  49 ++-
 docs/html/guide/webapps/index.jd                   |  52 ++-
 docs/html/guide/webapps/overview.jd                |  71 ----
 docs/html/guide/webapps/targeting.jd               | 378 ++++-----------------
 docs/html/guide/webapps/webview.jd                 |   1 -
 docs/html/images/webapps/web-viewport-320@2x.png   | Bin 0 -> 300241 bytes
 .../images/webapps/web-viewport-default@2x.png     | Bin 0 -> 264812 bytes
 .../images/webapps/web-viewport-devicewidth@2x.png | Bin 0 -> 318158 bytes
 10 files changed, 152 insertions(+), 422 deletions(-)
 delete mode 100644 docs/html/guide/webapps/overview.jd
 create mode 100644 docs/html/images/webapps/web-viewport-320@2x.png
 create mode 100644 docs/html/images/webapps/web-viewport-default@2x.png
 create mode 100644 docs/html/images/webapps/web-viewport-devicewidth@2x.png

(limited to 'docs/html')

diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index 84ffd05..8f2795a 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -490,11 +490,8 @@
     <span class="en">Web Apps</span>
     </a></div>
     <ul>
-      <li><a href="<?cs var:toroot ?>guide/webapps/overview.html">
-            <span class="en">Overview</span>
-          </a></li>
       <li><a href="<?cs var:toroot ?>guide/webapps/targeting.html">
-            <span class="en">Targeting Screens from Web Apps</span>
+            <span class="en">Supporting Different Screens in Web Apps</span>
           </a></li>
       <li><a href="<?cs var:toroot ?>guide/webapps/webview.html">
             <span class="en">Building Web Apps in WebView</span>
diff --git a/docs/html/guide/webapps/best-practices.jd b/docs/html/guide/webapps/best-practices.jd
index 1362990..a13c69d 100644
--- a/docs/html/guide/webapps/best-practices.jd
+++ b/docs/html/guide/webapps/best-practices.jd
@@ -1,6 +1,24 @@
 page.title=Best Practices for Web Apps
 @jd:body
 
+<div id="qv-wrapper">
+<div id="qv">
+
+<h2>See also</h2>
+<ul>
+  <li><a href="https://developers.google.com/chrome/mobile/docs/webview/pixelperfect"
+  >Pixel-Perfect UI in the WebView</a></li>
+  <li><a href="http://www.html5rocks.com/en/mobile/responsivedesign/" class="external-link">Creating
+  a Mobile-First Responsive Web Design</a></li>
+  <li><a href="http://www.html5rocks.com/en/mobile/high-dpi/" class="external-link">High
+  DPI Images for Variable Pixel Densities</a></li>
+</ul>
+
+</div>
+</div>
+
+
+
 <style>
 .bold li {
   font-weight:bold;
diff --git a/docs/html/guide/webapps/debugging.jd b/docs/html/guide/webapps/debugging.jd
index 1eef1ae..3c95fc2 100644
--- a/docs/html/guide/webapps/debugging.jd
+++ b/docs/html/guide/webapps/debugging.jd
@@ -18,19 +18,29 @@ messages</li>
 
 <h2>See also</h2>
 <ol>
+  <li><a class="external-link"
+href="https://developers.google.com/chrome-developer-tools/docs/remote-debugging">Remote
+Debugging on Android</a></li>
   <li><a href="{@docRoot}tools/debugging/index.html">Debugging</a></li>
 </ol>
 
 </div>
 </div>
 
-<p>If you're developing a web application for Android, you can debug your JavaScript
-using the {@code console} JavaScript APIs, which output messages to logcat. If you're familiar with
+<p>If you are testing your web app with a device running Android 4.4 or higher,
+you can remotely debug your web pages in {@link android.webkit.WebView} with
+Chrome Developer Tools, while continuing to support older versions of Android.
+For more information, see <a class="external-link"
+href="https://developers.google.com/chrome-developer-tools/docs/remote-debugging">Remote
+Debugging on Android</a>.</p>
+
+<p>If you don't have a device running Android 4.4 or higher, you can debug your JavaScript using the
+{@code console} JavaScript APIs and view the output messages to logcat. If you're familiar with
 debugging web pages with Firebug or Web Inspector, then you're probably familiar
 with using {@code console} (such as {@code console.log()}). Android's WebKit framework supports most
 of the same APIs, so you can receive logs from your web page when debugging in Android's Browser
-or in your own {@link android.webkit.WebView}.</p>
-
+or in your own {@link android.webkit.WebView}. This document describes how to use the
+console APIs for debugging.</p>
 
 
 <h2 id="Browser">Using Console APIs in the Android Browser</h2>
@@ -83,28 +93,17 @@ expect from other web browsers.</p>
 
 <h2 id="WebView">Using Console APIs in WebView</h2>
 
-<p>If you've implemented a custom {@link android.webkit.WebView} in your application, all the
-same console APIs are supported when debugging your web page in WebView. On Android
-1.6 and lower, console messages are automatically sent to logcat with the
-"WebCore" logging tag. If you're targeting Android 2.1 (API Level 7) or higher, then you must
+<p>All the console APIs shown above are also
+supported when debugging in {@link android.webkit.WebView}. 
+If you're targeting Android 2.1 (API level 7) and higher, you must
 provide a {@link android.webkit.WebChromeClient}
 that implements the {@link android.webkit.WebChromeClient#onConsoleMessage(String,int,String)
-onConsoleMessage()} callback method, in order for console messages to appear in logcat.</p>
-
-<p>Additionally, the {@link
-android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} method introduced in API
-Level 7 has been deprecated in favor of {@link
-android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} in API Level 8.</p>
-
-<p>Whether you're developing for Android 2.1 (API Level 7) or Android 2.2 (API Level 8 or
-greater), you must implement {@link android.webkit.WebChromeClient} and override the appropriate
-{@link
-android.webkit.WebChromeClient#onConsoleMessage(String,int,String) onConsoleMessage()} callback
-method. Then, apply the {@link android.webkit.WebChromeClient} to your {@link
+onConsoleMessage()} method in order for console messages to appear in logcat.
+Then, apply the {@link android.webkit.WebChromeClient} to your {@link
 android.webkit.WebView} with {@link android.webkit.WebView#setWebChromeClient(WebChromeClient)
 setWebChromeClient()}.
 
-<p>Using API Level 7, this is how your code for {@link
+<p>For example, to support API level 7, this is how your code for {@link
 android.webkit.WebChromeClient#onConsoleMessage(String,int,String)} might look:</p>
 
 <pre>
@@ -118,8 +117,8 @@ myWebView.setWebChromeClient(new WebChromeClient() {
 });
 </pre>
 
-<p>With API Level 8 or greater, your code for {@link
-android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)} might look like this:</p>
+<p>However, if your lowest supported version is API level 8 or higher, you should instead
+implement {@link android.webkit.WebChromeClient#onConsoleMessage(ConsoleMessage)}. For example:</p>
 
 <pre>
 WebView myWebView = (WebView) findViewById(R.id.webview);
@@ -134,8 +133,8 @@ myWebView.setWebChromeClient(new WebChromeClient() {
 </pre>
 
 <p>The {@link android.webkit.ConsoleMessage} also includes a {@link
-android.webkit.ConsoleMessage.MessageLevel MessageLevel} to indicate the type of console message
-being delivered. You can query the message level with {@link
+android.webkit.ConsoleMessage.MessageLevel MessageLevel} object to indicate the type of console
+message being delivered. You can query the message level with {@link
 android.webkit.ConsoleMessage#messageLevel()} to determine the severity of the message, then
 use the appropriate {@link android.util.Log} method or take other appropriate actions.</p>
 
diff --git a/docs/html/guide/webapps/index.jd b/docs/html/guide/webapps/index.jd
index df7ddbe..a188d2b 100644
--- a/docs/html/guide/webapps/index.jd
+++ b/docs/html/guide/webapps/index.jd
@@ -1,16 +1,50 @@
 page.title=Web Apps
-page.landing=true
-page.landing.intro=Android has always been about connectivity and providing a great web browsing experience, so building your app with web technologies can be a great opportunity. Not only can you build an app on the web and still optimize your designs for Android's various screen sizes and densities, but you can also embed web-based content into your Android app using WebView.
-page.landing.image=
 
 @jd:body
 
-<div class="landing-docs">
+<div class="figure" style="width:327px">
+  <img src="{@docRoot}images/webapps/webapps.png" alt="" />
+  <p class="img-caption"><strong>Figure 1.</strong> You can make your web content available to
+users in two ways: in a traditional web browser and in an Android application, by
+including a WebView in the layout.</p>
+</div>
 
-  <div class="col-6">
-  </div>
+<p>There are essentially two ways to deliver an application on Android: as a
+client-side application (developed using the Android SDK and installed on user devices in an APK)
+or as a web application (developed using web standards and accessed through a web
+browser&mdash;there's nothing to install on user devices).</p>
 
-  <div class="col-6">
-  </div>
+<p>If you chose to provide a web-based app for Android-powered devices, you can rest
+assured that major web browsers for Android (and the {@link android.webkit.WebView} framework)
+allow you to specify viewport and style properties that make your web pages appear at the proper
+size and scale on all screen configurations.</p>
 
-</div>
\ No newline at end of file
+<p>Figure 1 illustrates how you can provide access to your web pages from either
+a web browser or your your own Android app. However, you shouldn't develop an Android
+app simply as a means to view your web site. Rather, the web pages you embed in your
+Android app should be designed especially for that environment. You can even define an
+interface between your Android application and your web pages that allows JavaScript in the web
+pages to call upon APIs in your Android application&mdash;providing Android APIs to your web-based
+application.</p>
+
+<p>To start developing web pages for Android-powered devices, see the following documents:</p>
+
+<dl>
+  <dt><a href="{@docRoot}guide/webapps/targeting.html"><strong>Supporting Different Screens from Web
+  Apps</strong></a></dt>
+  <dd>How to properly size your web app on Android-powered devices and support
+multiple screen densities. The information in this document is important if you're building a web
+application that you at least expect to be available on Android-powered devices (which you should
+assume for anything you publish on the web), but especially if you're targeting mobile devices
+or using {@link android.webkit.WebView}.</dd>
+  <dt><a href="{@docRoot}guide/webapps/webview.html"><strong>Building Web Apps in
+WebView</strong></a></dt>
+  <dd>How to embed web pages into your Android application using {@link
+  android.webkit.WebView} and bind JavaScript to Android APIs.</dd>
+  <dt><a href="{@docRoot}guide/webapps/debugging.html"><strong>Debugging Web Apps</strong></a></dt>
+  <dd>How to debug web apps using JavaScript Console APIs.</dd>
+  <dt><a href="{@docRoot}guide/webapps/best-practices.html"><strong>Best Practices for Web
+Apps</strong></a></dt>
+  <dd>A list of practices you should follow, in order to provide an effective web application on
+Android-powered devices.</dd>
+</dl>
\ No newline at end of file
diff --git a/docs/html/guide/webapps/overview.jd b/docs/html/guide/webapps/overview.jd
deleted file mode 100644
index 069290a..0000000
--- a/docs/html/guide/webapps/overview.jd
+++ /dev/null
@@ -1,71 +0,0 @@
-page.title=Web Apps Overview
-@jd:body
-
-<div class="figure" style="width:327px">
-  <img src="{@docRoot}images/webapps/webapps.png" alt="" />
-  <p class="img-caption"><strong>Figure 1.</strong> You can make your web content available to
-users in two ways: in a traditional web browser and in an Android application, by
-including a WebView in the layout.</p>
-</div>
-
-<p>There are essentially two ways to deliver an application on Android: as a
-client-side application (developed using the Android SDK and installed on user devices as an {@code
-.apk}) or as a web application (developed using web standards and accessed through a web
-browser&mdash;there's nothing to install on user devices).</p>
-
-<p>The approach you choose for your application could depend on several factors, but Android makes
-the decision to develop a web application easier by providing:</p>
-<ul>
-  <li>Support for viewport properties that allow you to properly size your web application
-based on the screen size</li>
-  <li>CSS and JavaScript features that allow you to provide different styles and images
-based on the screen's pixel density (screen resolution)</li>
-</ul>
-
-<p>Thus, your decision to develop a web application for Android can exclude consideration for
-screen support, because it's already easy to make your web pages look good on all types of screens
-powered by Android.</p>
-
-<p>Another great feature of Android is that you don't have to build your application purely on
-the client or purely on the web. You can mix the two together by developing a client-side Android
-application that embeds some web pages (using a {@link android.webkit.WebView} in your Android
-application layout). Figure 1 visualizes how you can provide access to your web pages from either
-a web browser or your Android application. However, you shouldn't develop an Android
-application simply as a means to launch your web site. Rather, the web pages you embed in your
-Android application should be designed especially for that environment. You can even define an
-interface between your Android application and your web pages that allows JavaScript in the web
-pages to call upon APIs in your Android application&mdash;providing Android APIs to your web-based
-application.</p>
-
-<p>Since Android 1.0, {@link android.webkit.WebView} has been available for Android
-applications to embed web content in their layout and bind JavaScript to Android APIs. After
-Android added support for more screen densities (adding support for high and low-density
-screens), Android 2.0 added features to the WebKit framework to allow web pages to specify
-viewport properties and query the screen density in order to modify styles
-and image assets, as mentioned above. Because these features are a part of Android's WebKit
-framework, both the Android Browser (the default web browser provided with the platform) and
-{@link android.webkit.WebView} support the same viewport and screen density features.</p>
-
-<p>To develop a web application for Android-powered devices, you should read the
-following documents:</p>
-
-<dl>
-  <dt><a href="{@docRoot}guide/webapps/targeting.html"><strong>Targeting Screens from Web
-Apps</strong></a></dt>
-  <dd>How to properly size your web app on Android-powered devices and support
-multiple screen densities. The information in this document is important if you're building a web
-application that you at least expect to be available on Android-powered devices (which you should
-assume for anything you publish on the web), but especially if you're targeting mobile devices
-or using {@link android.webkit.WebView}.</dd>
-  <dt><a href="{@docRoot}guide/webapps/webview.html"><strong>Building Web Apps in
-WebView</strong></a></dt>
-  <dd>How to embed web pages into your Android application using {@link android.webkit.WebView} and
-bind JavaScript to Android APIs.</dd>
-  <dt><a href="{@docRoot}guide/webapps/debugging.html"><strong>Debugging Web Apps</strong></a></dt>
-  <dd>How to debug web apps using JavaScript Console APIs.</dd>
-  <dt><a href="{@docRoot}guide/webapps/best-practices.html"><strong>Best Practices for Web
-Apps</strong></a></dt>
-  <dd>A list of practices you should follow, in order to provide an effective web application on
-Android-powered devices.</dd>
-</dl>
-
diff --git a/docs/html/guide/webapps/targeting.jd b/docs/html/guide/webapps/targeting.jd
index 7410202..7e02340 100644
--- a/docs/html/guide/webapps/targeting.jd
+++ b/docs/html/guide/webapps/targeting.jd
@@ -1,16 +1,8 @@
-page.title=Targeting Screens from Web Apps
+page.title=Supporting Different Screens in Web Apps
 @jd:body
 
 <div id="qv-wrapper">
 <div id="qv">
-<h2>Quickview</h2>
-<ul>
-  <li>You can target your web page for different screens using viewport metadata, CSS, and
-JavaScript</li>
-  <li>Techniques in this document work for Android 2.0 and greater, and for web pages rendered
-in the default Android Browser and in a {@link android.webkit.WebView}</li>
-</ul>
-
 <h2>In this document</h2>
 <ol>
 <li><a href="#Metadata">Using Viewport Metadata</a>
@@ -24,315 +16,107 @@ in the default Android Browser and in a {@link android.webkit.WebView}</li>
 <li><a href="#DensityJS">targeting Device Density with JavaScript</a></li>
 </ol>
 
+<h2>See also</h2>
+<ul>
+  <li><a href="https://developers.google.com/chrome/mobile/docs/webview/pixelperfect"
+  >Pixel-Perfect UI in the WebView</a></li>
+  <li><a href="http://www.html5rocks.com/en/mobile/responsivedesign/" class="external-link">Creating
+  a Mobile-First Responsive Web Design</a></li>
+  <li><a href="http://www.html5rocks.com/en/mobile/high-dpi/" class="external-link">High
+  DPI Images for Variable Pixel Densities</a></li>
+</ul>
+
 </div>
 </div>
 
 
-<p>If you're developing a web application for Android or redesigning one for mobile devices, you
-should carefully consider how your web pages appear on different kinds of screens. Because
-Android is available on devices with different types of screens, you should account for some factors
-that affect the way your web pages appear on Android devices.</p>
+<p>Because Android is available on devices with a variety of screen sizes and pixel densities, you
+should account for these factors in your web design so your web pages always appear at the
+appropriate size.</p>
 
-<p class="note"><strong>Note:</strong> The features described in this document are supported
-by the Android Browser application (provided with the default Android platform) and {@link
-android.webkit.WebView} (the framework view widget for displaying web pages), on Android 2.0 and
-greater. Third-party web browsers running on Android might not support these features for
-controlling the viewport size and screen densities.</p>
 
-<p>When targeting your web pages for Android devices, there are two fundamental factors that you
+<p>When targeting your web pages for Android devices, there are two major factors that you
 should account for:</p>
 
 <dl>
-  <dt>The size of the viewport and scale of the web page</dt>
-    <dd>When the Android Browser loads a web page, the default behavior is to load the
-page in "overview mode," which provides a zoomed-out perspective of the web page. You can override
-this behavior for your web page by defining the default dimensions of the viewport or the initial
-scale of the viewport. You can also control how much the user can zoom in and out of your web
-page, if at all. The user can also disable overview mode in the
-Browser settings, so you should never assume that your page will load in overview mode. You
-should instead customize the viewport size and/or scale as appropriate for your page.</p>
-    <p>However, when your page is rendered in a {@link android.webkit.WebView}, the page loads at
-full zoom (not in "overview mode"). That is, it appears at the default size for the page,
-instead of zoomed out. (This is also how the page appears if the user disables overview
-mode.)</p></dd>
-
-  <dt>The device's screen density</dt>
-    <dd>The screen density (the number of pixels per inch) on an Android-powered device affects
-the resolution and size at which a web page is displayed. (There are three screen density
-categories: low, medium, and high.) The Android Browser and {@link android.webkit.WebView}
-compensate for variations in the screen
-density by scaling a web page so that all devices display the web page at the same perceivable size
-as a medium-density screen. If graphics are an important element of your web design, you
-should pay close attention to the scaling that occurs on different densities, because image scaling
-can produce artifacts (blurring and pixelation).
-      <p>To provide the best visual representation on all
-screen densities, you should control how scaling occurs by providing viewport metadata about
-your web page's target screen density and providing alternative graphics for different screen
-densities, which you can apply to different screens using CSS or JavaScript.</p></dd>
+  <dt><a href="#Viewport">The viewport</a></dt>
+    <dd>The viewport is the rectangular area that provides a drawable region for your web page.
+    You can specify several viewport properties, such as its size and initial scale. Most important
+    is the view port width, which defines the total number of horizontal pixels available from the web page's point of
+    view (the number of CSS pixels available).
+   </dd>
+
+  <dt><a href="#DensityCSS">The screen density</a></dt>
+<dd>The {@link android.webkit.WebView} class and most web browsers on Android convert your CSS
+pixel values to density-independent pixel values, so your web page appears at the same perceivable
+size as a medium-density screen (about 160dpi). However, if graphics are an important element of
+your web design, you should pay close attention to the scaling that occurs on different densities,
+because a 300px-wide image on a 320dpi screen will be scaled up (using more physical pixels per CSS
+pixel), which can produce artifacts (blurring and pixelation).</dd>
+
 </dl>
 
-<p>The rest of this document describes how you can account for these effects and provide a good
-design on multiple types of screens.</p>
 
 
 
-<h2 id="Metadata">Using Viewport Metadata</h2>
 
-<p>The viewport is the area in which your web page is drawn. Although the viewport's visible area
-matches the size of the screen,
-the viewport has its own dimensions that determine the number of pixels available to a web page.
-That is, the number of pixels available to a web page before it exceeds the screen area is
-defined by the dimensions of the viewport,
-not the dimensions of the device screen. For example, although a device screen might have a width of
-480 pixels, the viewport can have a width of 800 pixels, so that a web page designed to be 800
-pixels wide is completely visible on the screen.</p>
+<h2 id="Viewport">Specifying Viewport Properties</h2>
 
-<p>You can define properties of the viewport for your web page using the {@code "viewport"}
-property in an HTML {@code &lt;meta&gt;} tag (which must
-be placed in your document {@code &lt;head&gt;}). You can define multiple viewport properties in the
-{@code &lt;meta&gt;} tag's {@code content} attribute. For example, you can define the height and
-width of the viewport, the initial scale of the page, and the target screen density.
-Each viewport property in the {@code content} attribute must be separated by a comma.</p>
+<p>The viewport is the area in which your web page is drawn. Although the viewport's total visible
+area matches the size of the screen when zoomed all the way out, the viewport has its own pixel
+dimensions that it makes available to a web page. For example, although a device screen might
+have physical a width
+of 480 pixels, the viewport can have a width of 800 pixels. This allows a web page designed at 800
+pixels wide to be completely visible on the screen when the viewport scale is 1.0. Most web browsers on
+Android (including Chrome) set the viewport to a large size by default (known as "wide viewport
+mode" at about 980px wide). Many browsers also zoom out as far as possible, by default, to
+show the full viewport width (known as "overview mode").</p>
 
-<p>For example, the following snippet from an HTML document specifies that the viewport width
-should exactly match the device screen width and that the ability to zoom should be disabled:</p>
+<p class="note"><strong>Note:</strong>
+When your page is rendered in a {@link android.webkit.WebView}, it does not use wide viewport mode
+(the page appears at full zoom) by default. You can enable wide viewport mode
+with {@link android.webkit.WebSettings#setUseWideViewPort setUseWideViewPort()}.</p>
 
-<pre>
-&lt;head&gt;
-    &lt;title&gt;Example&lt;/title&gt;
-    &lt;meta name="viewport" content="width=device-width, user-scalable=no" /&gt;
-&lt;/head&gt;
-</pre>
+<p>You can define properties of the viewport for your web page, such as the width and initial zoom
+level, using the {@code &lt;meta name="viewport" ...>} tag in your document
+{@code &lt;head&gt;}.</p>
 
-<p>That's an example of just two viewport properties. The following syntax shows all of the
-supported viewport properties and the general types of values accepted by each one:</p>
+<p>The following syntax shows all of the
+supported viewport properties and the types of values accepted by each one:</p>
 
 <pre>
 &lt;meta name="viewport"
       content="
-          <b>height</b> = [<em>pixel_value</em> | device-height] ,
-          <b>width</b> = [<em>pixel_value</em> | device-width ] ,
+          <b>height</b> = [<em>pixel_value</em> | "device-height"] ,
+          <b>width</b> = [<em>pixel_value</em> | "device-width"] ,
           <b>initial-scale</b> = <em>float_value</em> ,
           <b>minimum-scale</b> = <em>float_value</em> ,
           <b>maximum-scale</b> = <em>float_value</em> ,
-          <b>user-scalable</b> = [yes | no] ,
-          <b>target-densitydpi</b> = [<em>dpi_value</em> | device-dpi |
-                               high-dpi | medium-dpi | low-dpi]
+          <b>user-scalable</b> = ["yes" | "no"]
           " /&gt;
 </pre>
 
-<p>The following sections discuss how to use each of these viewport properties and exactly what the
-accepted values are.</p>
-
-<div class="figure" style="width:300px">
-  <img src="{@docRoot}images/webapps/compare-default.png" alt="" height="300" />
-  <p class="img-caption"><strong>Figure 1.</strong> A web page with an image that's 320 pixels
-wide, in the Android Browser when there is no viewport metadata set (with "overview mode"
-enabled, the viewport is 800 pixels wide, by default).</p>
-</div>
-
-
-<div class="figure" style="width:300px">
-  <img src="{@docRoot}images/webapps/compare-width400.png" alt="" height="300" />
-  <p class="img-caption"><strong>Figure 2.</strong> A web page with viewport {@code width=400} and
-"overview mode" enabled (the image in the web page is 320 pixels wide).</p>
-</div>
-
-
-<h3 id="ViewportSize">Defining the viewport size</h3>
-
-<p>Viewport's {@code height} and {@code width} properties allow you to specify the size of the
-viewport (the number of pixels available to the web page before it goes off screen).</p>
-
-<p>As mentioned in the introduction above, the Android Browser loads pages in "overview mode" by
-default (unless disable by the user), which sets the minimum viewport width to 800 pixels. So, if
-your web page specifies its size to be 320 pixels wide, then your page appears smaller than the
-visible screen (even if the physical screen is 320 pixels wide, because the viewport simulates a
-drawable area that's 800 pixels wide), as shown in figure 1. To avoid this effect, you should
-explicitly define the viewport {@code width} to match the width for which you have designed your web
-page.</p>
-
-<p>For example, if your web page is designed to be exactly 320 pixels wide, then you might
-want to specify that size for the viewport width:</p>
-
-<pre>
-&lt;meta name="viewport" content="width=320" /&gt;
-</pre>
-
-<p>In this case, your web page exactly fits the screen width, because the web page width and
-viewport width are the same.</p>
-
-<p class="note"><strong>Note:</strong> Width values that are greater than 10,000 are ignored and
-values less than (or equal to) 320 result in a value equal to the device-width (discussed below).
-Height values that are greater then 10,000 or less than 200 are also ignored.</p>
-
-<p>To demonstrate how this property affects the size of
-your web page, figure 2 shows a web page that contains an image that's 320 pixels
-wide, but with the viewport width set to 400.</p>
-
-
-<p class="note"><strong>Note:</strong> If you set the viewport width to match your web page width
-and the device's screen width does <em>not</em> match those dimensions, then the web page
-still fits the screen even if the device has a high or low-density screen, because the
-Android Browser and {@link android.webkit.WebView} scale web pages to match the perceived size on a
-medium-density screen, by default (as you can see in figure 2, when comparing the hdpi device to the
-mdpi device). Screen densities are discussed more in <a href="#ViewportDensity">Defining the
-viewport target density</a>.</p>
-
-
-<h4>Automatic sizing</h4>
-
-<p>As an alternative to specifying the viewport dimensions with exact pixels, you can set the
-viewport size to always match the dimensions of the device screen, by defining the
-viewport properties {@code height}
-and {@code width} with the values {@code device-height} and {@code device-width}, respectively. This
-is appropriate when you're developing a web application that has a fluid width (not fixed width),
-but you want it to appear as if it's fixed (to perfectly fit every screen as
-if the web page width is set to match each screen). For example:</p>
-
-<pre>
-&lt;meta name="viewport" content="width=device-width" /&gt;
-</pre>
-
-<p>This results in the viewport width matching whatever the current screen width is, as shown in
-figure 3. It's important to notice that, this results in images being scaled to fit the screen
-when the current device does not match the <a href="#ViewportDensity">target
-density</a>, which is medium-density if you don't specify otherwise. As a result, the image
-displayed on the high-density device in figure 3 is scaled up in order to match the width
-of a screen with a medium-density screen.</p>
-
-<div class="figure" style="width:300px">
-  <img src="{@docRoot}images/webapps/compare-initialscale.png" alt="" height="300" />
-  <p class="img-caption"><strong>Figure 3.</strong> A web page with viewport {@code
-width=device-width} <em>or</em> {@code initial-scale=1.0}.</p>
-</div>
-
-<p class="note"><strong>Note:</strong> If you instead want {@code
-device-width} and {@code device-height} to match the physical screen pixels for every device,
-instead of scaling your web page to match the target density, then you must also include
-the {@code target-densitydpi} property with a value of {@code device-dpi}. This is discussed more in
-the section about <a href="#ViewportDensity">Defining the viewport density</a>. Otherwise, simply
-using {@code device-height} and {@code device-width} to define the viewport size makes your web page
-fit every device screen, but scaling occurs on your images in order to adjust for different screen
-densities.</p>
-
-
-
-<h3 id="ViewportScale">Defining the viewport scale</h3>
-
-<p>The scale of the viewport defines the level of zoom applied to the web page. Viewport
-properties allow you to specify the scale of your web page in the following ways:</p>
-<dl>
-  <dt>{@code initial-scale}</dt>
-  <dd>The initial scale of the page. The value is a float that indicates a multiplier for your web
-page size, relative to the screen size. For example, if you set the initial scale to "1.0" then the
-web page is displayed to match the resolution of the <a href="#ViewportDensity">target
-density</a> 1-to-1. If set to "2.0", then the page is enlarged (zoomed in) by a factor of 2.
-    <p>The default initial scale is calculated to fit the web page in the viewport size.
-Because the default viewport width is 800 pixels, if the device screen resolution is less than
-800 pixels wide, the initial scale is something less than 1.0, by default, in order to fit the
-800-pixel-wide page on the screen.</p></dd>
-
-  <dt>{@code minimum-scale}</dt>
-  <dd>The minimum scale to allow. The value is a float that indicates the minimum multiplier for
-your web page size, relative to the screen size. For example, if you set this to "1.0", then the
-page can't zoom out because the minimum size is 1-to-1 with the <a href="#ViewportDensity">target
-density</a>.</dd>
-
-  <dt>{@code maximum-scale}</dt>
-  <dd>The maximum scale to allow for the page. The value is a float that indicates the
-maximum multiplier for your web page size,
-relative to the screen size. For example, if you set this to "2.0", then the page can't
-zoom in more than 2 times the target size.</dd>
-
-  <dt>{@code user-scalable}</dt>
-  <dd>Whether the user can change the scale of the page at all (zoom in and out). Set to {@code yes}
-to allow scaling and {@code no} to disallow scaling. The default is {@code yes}. If you set
-this to {@code no}, then the {@code minimum-scale} and {@code maximum-scale} are ignored,
-because scaling is not possible.</dd>
-</dl>
-
-<p>All scale values must be within the range 0.01&ndash;10.</p>
-
-<p>For example:</p>
+<p>For example, the following {@code &lt;meta&gt;} tag specifies that the viewport width
+should exactly match the device screen's width and that the ability to zoom should be disabled:</p>
 
 <pre>
-&lt;meta name="viewport" content="initial-scale=1.0" /&gt;
+&lt;head&gt;
+    &lt;title&gt;Example&lt;/title&gt;
+    &lt;meta name="viewport" content="width=device-width, user-scalable=no" /&gt;
+&lt;/head&gt;
 </pre>
 
-<p>This metadata sets the initial scale to be full sized, relative to the viewport's target
-density.</p>
-
-
-
-
-<h3 id="ViewportDensity">Defining the viewport target density</h3>
-
-<p>The density of a device's screen is based on the screen resolution, as defined by the number of
-dots per inch (dpi). There are three screen
-density categories supported by Android: low (ldpi), medium (mdpi), and high (hdpi). A screen
-with low density has fewer available pixels per inch, whereas a screen with high density has more
-pixels per inch (compared to a medium density screen). The Android Browser and {@link
-android.webkit.WebView} target a medium density screen by default.</p>
 
+<p>When optimizing your site for mobile devices, you should usually set the width to
+{@code "device-width"} so the size fits exactly on all devices, then use CSS media queries to 
+flexibly adapt layouts to suit different screen sizes.
 
-<div class="figure" style="width:300px">
-  <img src="{@docRoot}images/webapps/compare-initialscale-devicedpi.png" alt="" height="300" />
-  <p class="img-caption"><strong>Figure 4.</strong> A web page with viewport {@code
-width=device-width} and {@code target-densitydpi=device-dpi}.</p>
-</div>
-
-
-<p>Because the default target density is medium, when users have a device with a low or high density
-screen, the Android Browser and {@link android.webkit.WebView} scale web pages (effectively zoom
-the pages) so they display at a
-size that matches the perceived appearance on a medium density screen. More specifically, the
-Android Browser and {@link android.webkit.WebView} apply approximately 1.5x scaling to web pages
-on a high density screen (because its screen pixels are smaller) and approximately 0.75x scaling to
-pages on a low density screen (because its screen pixels are bigger).</p>
+<p class="note"><strong>Note:</strong> You should disable user scaling only when you're certain
+that your web page layout is flexible and the content will fit the width of small screens.</p>
 
-<p>Due to this default scaling, figures 1, 2, and 3 show the example web page at the same physical
-size on both the high and medium density device (the high-density device shows the
-web page with a default scale factor that is 1.5 times larger than the actual pixel resolution, to
-match the target density). This can introduce some undesirable artifacts in your images.
-For example, although an image appears the same size on a medium and high-density device, the image
-on the high-density device appears more blurry, because the image is designed to be 320 pixels
-wide, but is drawn with 480 pixels.</p>
 
-<p>You can change the target screen density for your web page using the {@code target-densitydpi}
-viewport property. It accepts the following values:</p>
-
-<ul>
-<li><code>device-dpi</code> - Use the device's native dpi as the target dpi. Default scaling never
-occurs.</li>
-<li><code>high-dpi</code> - Use hdpi as the target dpi. Medium and low density screens scale down
-as appropriate.</li>
-<li><code>medium-dpi</code> - Use mdpi as the target dpi. High density screens scale up and low
-density screens scale down. This is the default target density.</li>
-<li><code>low-dpi</code> - Use ldpi as the target dpi. Medium and high density screens scale up
-as appropriate.</li>
-<li><em><code>&lt;value&gt;</code></em> - Specify a dpi value to use as the target dpi. Values must
-be within the range 70&ndash;400.</li>
-</ul></p>
-
-<p>For example, to prevent the Android Browser and {@link android.webkit.WebView} from scaling
-your web page for different screen densities, set
-the {@code target-densitydpi} viewport property to {@code device-dpi}. When you do, the page is
-not scaled. Instead, the page is displayed at a size that matches the current screen's
-density. In this case, you should also define the viewport width to match the device width, so your
-web page naturally fits the screen size. For example:</p>
 
-<pre>
-&lt;meta name="viewport" content="target-densitydpi=device-dpi, width=device-width" /&gt;
-</pre>
 
-<p>Figure 4 shows a web page using these viewport settings&mdash;the high-density device
-now displays the page smaller because its physical pixels are smaller than those on the
-medium-density device, so no scaling occurs and the 320-pixel-wide image is drawn using exactly 320
-pixels on both screens. (This is how you should define your viewport if
-you want to customize your web page based on screen density and provide different image assets for
-different densities, <a href="#DensityCSS">with CSS</a> or
-<a href="#DensityJS">with JavaScript</a>.)</p>
 
 
 <h2 id="DensityCSS">Targeting Device Density with CSS</h2>
@@ -349,17 +133,9 @@ or high density screens, respectively.</p>
 <pre>
 &lt;link rel="stylesheet" media="screen and (-webkit-device-pixel-ratio: 1.5)" href="hdpi.css" /&gt;
 &lt;link rel="stylesheet" media="screen and (-webkit-device-pixel-ratio: 1.0)" href="mdpi.css" /&gt;
-&lt;link rel="stylesheet" media="screen and (-webkit-device-pixel-ratio: 0.75)" href="ldpi.css" /&gt;
 </pre>
 
 
-<div class="figure" style="width:300px">
-  <img src="{@docRoot}images/webapps/compare-width-devicedpi-css.png" alt="" height="300" />
-  <p class="img-caption"><strong>Figure 5.</strong> A web page with CSS that's targetted to
-specific screen densities using the {@code -webkit-device-pixel-ratio} media feature. Notice
-that the hdpi device shows a different image that's applied in CSS.</p>
-</div>
-
 <p>Or, specify the different styles in one stylesheet:</p>
 
 <pre class="no-pretty-print">
@@ -382,27 +158,10 @@ that the hdpi device shows a different image that's applied in CSS.</p>
 }
 </pre>
 
-<p class="note"><strong>Note:</strong> The default style for {@code #header} applies the image
-designed for medium-density devices in order to support devices running a version of Android less
-than 2.0, which do not support the {@code -webkit-device-pixel-ratio} media feature.</p>
-
-<p>The types of styles you might want to adjust based on the screen density depend on how you've
-defined your viewport properties. To provide fully-customized styles that tailor your web page for
-each of the supported densities, you should set your viewport properties so the viewport width and
-density match the device. That is:</p>
-
-<pre>
-&lt;meta name="viewport" content="target-densitydpi=device-dpi, width=device-width" /&gt;
-</pre>
-
-<p>This way, the Android Browser and {@link android.webkit.WebView} do not perform scaling on your
-web page and the viewport width
-matches the screen width exactly. On their own, these viewport properties create results shown in
-figure 4. However, by adding some custom CSS using the {@code -webkit-device-pixel-ratio} media
-feature, you can apply different styles. For example, figure 5 shows a web page with these viewport
-properties and also some CSS added that applies a high-resolution image for high-density
-screens.</p>
 
+<p>For more information about handling different screen densities, especially images, see
+<a href="http://www.html5rocks.com/en/mobile/high-dpi/" class="external-link">High
+  DPI Images for Variable Pixel Densities</a>.</li>
 
 
 <h2 id="DensityJS">Targeting Device Density with JavaScript</h2>
@@ -432,8 +191,3 @@ if (window.devicePixelRatio == 1.5) {
 </pre>
 
 
-
-
-
-
-
diff --git a/docs/html/guide/webapps/webview.jd b/docs/html/guide/webapps/webview.jd
index c87be06..9b46b5b 100644
--- a/docs/html/guide/webapps/webview.jd
+++ b/docs/html/guide/webapps/webview.jd
@@ -136,7 +136,6 @@ custom user agent string with {@link android.webkit.WebSettings#setUserAgentStri
 setUserAgentString()}, then query the custom user agent in your web page to verify that the
 client requesting your web page is actually your Android application.</p>
 
-from your Android SDK {@code tools/} directory
 <h3 id="BindingJavaScript">Binding JavaScript code to Android code</h3>
 
 <p>When developing a web application that's designed specifically for the {@link
diff --git a/docs/html/images/webapps/web-viewport-320@2x.png b/docs/html/images/webapps/web-viewport-320@2x.png
new file mode 100644
index 0000000..f6b2bac
Binary files /dev/null and b/docs/html/images/webapps/web-viewport-320@2x.png differ
diff --git a/docs/html/images/webapps/web-viewport-default@2x.png b/docs/html/images/webapps/web-viewport-default@2x.png
new file mode 100644
index 0000000..a3f8d53
Binary files /dev/null and b/docs/html/images/webapps/web-viewport-default@2x.png differ
diff --git a/docs/html/images/webapps/web-viewport-devicewidth@2x.png b/docs/html/images/webapps/web-viewport-devicewidth@2x.png
new file mode 100644
index 0000000..3832f4c
Binary files /dev/null and b/docs/html/images/webapps/web-viewport-devicewidth@2x.png differ
-- 
cgit v1.1