docs: provide overview of the web apps docs and revise images in the targeting doc

Change-Id: I7c7c5b1936bea0676a2cafa5020e2b997c0b8634

docs/html/guide/guide_toc.cs

@@ -515,18 +515,21 @@
     <h2><span class="en">Web Applications</span>
     </h2>
     <ul>
-      <li><a href="<?cs var:toroot ?>guide/webapps/targetting.html">
+      <li><a href="<?cs var:toroot ?>guide/webapps/index.html">
-            <span class="en">Targetting Android Devices</span>
+            <span class="en">Web Apps Overview</span>
-          </a> <span class="new">new!</span><!-- 10/8/10 --></li>
+          </a> <span class="new">new!</span><!-- 11/1/10 --></li>
+      <li><a href="<?cs var:toroot ?>guide/webapps/targeting.html">
+            <span class="en">Targeting Screens from Web Apps</span>
+          </a> <span class="new">new!</span><!-- 11/1/10 --></li>
       <li><a href="<?cs var:toroot ?>guide/webapps/webview.html">
             <span class="en">Building Web Apps in WebView</span>
-          </a> <span class="new">new!</span><!-- 10/8/10 --></li>
+          </a> <span class="new">new!</span><!-- 11/1/10 --></li>
       <li><a href="<?cs var:toroot ?>guide/webapps/debugging.html">
             <span class="en">Debugging Web Apps</span>
-          </a> <span class="new">new!</span><!-- 10/8/10 --></li>
+          </a> <span class="new">new!</span><!-- 11/1/10 --></li>
       <li><a href="<?cs var:toroot ?>guide/webapps/best-practices.html">
             <span class="en">Best Practices for Web Apps</span>
-          </a> <span class="new">new!</span><!-- 10/8/10 --></li>
+          </a> <span class="new">new!</span><!-- 11/1/10 --></li>
     </ul>
   </li>
 

docs/html/guide/webapps/best-practices.jd

@@ -58,7 +58,7 @@ target screen density.</p>
 &lt;meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no"&gt;
 </pre>
   <p>For more information about how to use viewport meta data for Android-powered devices, read <a
-href="{@docRoot}guide/webapps/targetting.html">Targetting Android Devices</a>.</p>
+href="{@docRoot}guide/webapps/targeting.html">Targeting Screens from Web Apps</a>.</p>
 </li>
 
 

docs/html/guide/webapps/debugging.jd

@@ -86,7 +86,7 @@ expect from other web browsers.</p>
 <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 targetting Android 2.1 (API Level 7) or higher, then you must
+"WebCore" logging tag. If you're targeting Android 2.1 (API Level 7) or higher, then 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>

docs/html/guide/webapps/index.jd

@@ -0,0 +1,71 @@
+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</strong>
+Apps</a></dt>
+  <dd>A list of practices you should follow, in order to provide an effective web application on
+Android-powered devices.</dd>
+</dl>
+

docs/html/guide/webapps/targeting.jd

@@ -1,4 +1,4 @@
-page.title=Targetting Android Devices
+page.title=Targeting Screens from Web Apps
 @jd:body
 
 <div id="qv-wrapper">
@@ -7,7 +7,8 @@ page.title=Targetting Android Devices
 <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</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>
@@ -19,8 +20,8 @@ JavaScript</li>
     <li><a href="#ViewportDensity">Defining the viewport target density</a></li>
   </ol>
 </li>
-<li><a href="#DensityCSS">Targetting Device Density with CSS</a></li>
+<li><a href="#DensityCSS">Targeting Device Density with CSS</a></li>
-<li><a href="#DensityJS">Targetting Device Density with JavaScript</a></li>
+<li><a href="#DensityJS">targeting Device Density with JavaScript</a></li>
 </ol>
 
 </div>
@@ -28,8 +29,18 @@ JavaScript</li>
 
 
 <p>If you're developing a web application for Android or redesigning one for mobile devices, you
-should account for some factors that affect the way the Android Browser renders your web page by
+should carefully consider how your web pages appear on different kinds of screens. Because
-default. There are two fundamental factors that you should account for:</p>
+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 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
+should account for:</p>
 
 <dl>
   <dt>The size of the viewport and scale of the web page</dt>
@@ -37,15 +48,19 @@ default. There are two fundamental factors that you should account for:</p>
 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.
+page, if at all. The user can also disable overview mode in the
-    <p>However, 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
-Browser settings, so you should not 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>
-should instead customize the viewport size and/or scale as appropriate for your page.</p></dd>
+    <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 compensates for variations in the screen
+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
@@ -56,20 +71,15 @@ your web page's target screen density and providing alternative graphics for dif
 densities, which you can apply to different screens using CSS or JavaScript.</p></dd>
 </dl>
 
-<p>The rest of this document describes how you can account for these effects, and how to target
+<p>The rest of this document describes how you can account for these effects and provide a good
-your web page for specific screen configurations.</p>
+design on multiple types of screens.</p>
-
-<p class="note"><strong>Note:</strong> The features described in this document are supported
-by the Android Browser application on Android 2.0 and greater. Third-party web browsers running on
-Android might not support these techniques for controlling the viewport size and targetting
-screen densities.</p>
 
 
 
 <h2 id="Metadata">Using Viewport Metadata</h2>
 
-<p>The viewport is the area in which the Android Browser
+<p>The viewport is the area in which your web page is drawn. Although the viewport's visible area
-draws a web page. Although the viewport's visible area matches the size of the screen,
+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,
@@ -116,34 +126,34 @@ 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 no viewport metadata and an
+  <p class="img-caption"><strong>Figure 1.</strong> A web page with an image that's 320 pixels
-image that's 320 pixels wide (the viewport is 800 pixels wide, by default).</p>
+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}
+  <p class="img-caption"><strong>Figure 2.</strong> A web page with viewport {@code width=400} and
-(the image in the web page is 320 pixels wide).</p>
+"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). By default, the
+viewport (the number of pixels available to the web page before it goes off screen).</p>
-Android Browser's minimum viewport width is 800 pixels, so if your web
-page specifies its size to be 320 pixels wide, then your page renders 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. So, you should explicitly define the
-viewport {@code width} to match the width for which you have designed your web page.</p>
 
-<p class="note"><strong>Note:</strong> Width values that are greater than 10,000 are ignored and
+<p>As mentioned in the introduction above, the Android Browser loads pages in "overview mode" by
-values less than (or equal to) 320 result in a value equal to the device-width. Height values that
+default (unless disable by the user), which sets the minimum viewport width to 800 pixels. So, if
-are greater then 10,000 or less than 200 are also ignored.</p>
+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 for the viewport width:</p>
+want to specify that size for the viewport width:</p>
 
 <pre>
 &lt;meta name="viewport" content="width=320" /&gt;
@@ -152,18 +162,22 @@ want to specify that for the viewport width:</p>
 <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
+your web page, figure 2 shows a web page that contains an image that's 320 pixels
-viewport width set to 400.</p>
+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 screen width does <em>not</em> match those dimensions, then the web page
+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 scales web pages to match the perceived size on a medium-density
+Android Browser and {@link android.webkit.WebView} scale web pages to match the perceived size on a
-screen, by default (as you can see in figure 2, when comparing the hdpi device to the mdpi device).
+medium-density screen, by default (as you can see in figure 2, when comparing the hdpi device to the
-Screen densities are discussed more in <a href="#ViewportDensity">Defining the viewport target
+mdpi device). Screen densities are discussed more in <a href="#ViewportDensity">Defining the
-density</a>.</p>
+viewport target density</a>.</p>
 
 
 <h4>Automatic sizing</h4>
@@ -254,11 +268,12 @@ 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. There are three screen
+<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 (mdpi). 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 targets a medium density 
+pixels per inch (compared to a medium density screen). The Android Browser and {@link
-screen by default.</p>
+android.webkit.WebView} target a medium density screen by default.</p>
 
 
 <div class="figure" style="width:300px">
@@ -269,11 +284,12 @@ width=device-width} and {@code target-densitydpi=device-dpi}.</p>
 
 
 <p>Because the default target density is medium, when users have a device with a low or high density
-screen, the Android Browser scales web pages (effectively zooms the pages) so they display at a
+screen, the Android Browser and {@link android.webkit.WebView} scale web pages (effectively zoom
-size that matches the perceived appearance on a medium density screen. Specifically, the Android
+the pages) so they display at a
-Browser applies approximately 1.5x scaling to web pages on a high density screen
+size that matches the perceived appearance on a medium density screen. More specifically, the
-(because its screen pixels are smaller) and approximately 0.75x scaling to pages on a low density
+Android Browser and {@link android.webkit.WebView} apply approximately 1.5x scaling to web pages
-screen (because its screen pixels are bigger).</p>
+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>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
@@ -299,10 +315,10 @@ as appropriate.</li>
 be within the range 70&ndash;400.</li>
 </ul></p>
 
-<p>For example, to prevent the Android Browser from scaling of your web page for different screen
+<p>For example, to prevent the Android Browser and {@link android.webkit.WebView} from scaling
-densities, set
+your web page for different screen densities, set
-the {@code target-densitydpi} viewport property to {@code device-dpi}. When you do, the Android
+the {@code target-densitydpi} viewport property to {@code device-dpi}. When you do, the page is
-Browser does not scale the page and, instead, displays your web page to match the current screen
+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>
 
@@ -319,9 +335,10 @@ different densities, <a href="#DensityCSS">with CSS</a> or
 <a href="#DensityJS">with JavaScript</a>.)</p>
 
 
-<h2 id="DensityCSS">Targetting Device Density with CSS</h2>
+<h2 id="DensityCSS">Targeting Device Density with CSS</h2>
 
-<p>The Android Browser supports a CSS media feature that allows you to create styles for specific
+<p>The Android Browser and {@link android.webkit.WebView} support a CSS media feature that allows
+you to create styles for specific
 screen densities&mdash;the <code>-webkit-device-pixel-ratio</code> CSS media feature. The
 value you apply to this feature should be either
 "0.75", "1", or "1.5", to indicate that the styles are for devices with low density, medium density,
@@ -378,8 +395,9 @@ density match the device. That is:</p>
 &lt;meta name="viewport" content="target-densitydpi=device-dpi, width=device-width" /&gt;
 </pre>
 
-<p>This way, the Android Browser does not perform scaling on your web page and the viewport width
+<p>This way, the Android Browser and {@link android.webkit.WebView} do not perform scaling on your
-matches the screen width exactly. On its own, these viewport properties create results shown in
+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
@@ -387,16 +405,18 @@ screens.</p>
 
 
 
-<h2 id="DensityJS">Targetting Device Density with JavaScript</h2>
+<h2 id="DensityJS">Targeting Device Density with JavaScript</h2>
 
-<p>The Android Browser supports a DOM property that allows you to query the density of the current
+<p>The Android Browser and {@link android.webkit.WebView} support a DOM property that allows you to
+query the density of the current
 device&mdash;the <code>window.devicePixelRatio</code> DOM property. The value of this property
 specifies the scaling factor used for the current device. For example, if the value
 of <code>window.devicePixelRatio</code> is "1.0", then the device is considered a medium density
 device and no scaling is applied by default; if the value is "1.5", then the device is
 considered a high density device and the page is scaled 1.5x by default; if the value
 is "0.75", then the device is considered a low density device and the page is scaled
-0.75x by default. Of course, the scaling that the Android Browser applies is based on the web page's
+0.75x by default. Of course, the scaling that the Android Browser and {@link android.webkit.WebView}
+apply is based on the web page's
 target density&mdash;as described in the section about <a href="#ViewportDensity">Defining the
 viewport target density</a>, the default target is medium-density, but you can change the
 target to affect how your web page is scaled for different screen densities.</p>