am 6e8d6bd0: Merge "docs: Update various SDK docs for GB platform and tools" into gingerbread

* commit '6e8d6bd09facabcc0f868960e6453b8f79cd9136':
  docs: Update various SDK docs for GB  platform and tools

docs/html/sdk/adding-components.jd

@@ -87,11 +87,11 @@ follow these steps to access the Android SDK and AVD Manager tool:</p>
 Manager</strong>.</li>
 </ol>
 
-<h4>Launching from the setup script (Windows only)</h4>
+<h4>Launching from the SDK Manager script (Windows only)</h4>
 
 <p>For Windows only, the SDK includes a script that invokes the Android SDK and
-AVD Manager. To launch the tool using the script, double-click "SDK
+AVD Manager. To launch the tool using the script, double-click {@code SDK
-Setup.exe" at the root of the the SDK directory.</p>
+Manager.exe} at the root of the the SDK directory.</p>
 
 <h4>Launching from a command line</h4>
 
@@ -107,9 +107,11 @@ and AVD Manager tool from the command line: </p>
 
 <h2 id="InstallingComponents">Installing SDK Components</h2>
 
-<p class="caution"><strong>Important:</strong> Before you install SDK components, 
+<p class="caution"><strong>Caution:</strong> Before you install SDK components,
-we recommend that you disable any antivirus programs that may be running on
+we recommend that you disable any antivirus software that may be running on
-your computer.</p>
+your computer. There are cases in which antivirus software on Windows is known to interfere with the
+installation process, so we suggest you disable your antivirus until installation is
+complete.</p>
 
 <p>Follow these steps to install new SDK components in your environment:</p>
 

docs/html/sdk/index.jd

@@ -1,27 +1,27 @@
 page.title=Android SDK
 sdk.redirect=0
 
-sdk.win_download=android-sdk_r07-windows.zip
+sdk.win_installer=installer_r08-windows.exe
-sdk.win_bytes=23669664
+sdk.win_installer_bytes=TODO
-sdk.win_checksum=69c40c2d2e408b623156934f9ae574f0
+sdk.win_installer_checksum=TODO
 
-sdk.mac_download=android-sdk_r07-mac_x86.zip
+sdk.win_download=android-sdk_r08-windows.zip
-sdk.mac_bytes=19229546
+sdk.win_bytes=TODO
-sdk.mac_checksum=0f330ed3ebb36786faf6dc72b8acf819
+sdk.win_checksum=TODO
 
-sdk.linux_download=android-sdk_r07-linux_x86.tgz
+sdk.mac_download=android-sdk_r08-mac_x86.zip
-sdk.linux_bytes=17114517
+sdk.mac_bytes=TODO
-sdk.linux_checksum=e10c75da3d1aa147ddd4a5c58bfc3646
+sdk.mac_checksum=TODO
+
+sdk.linux_download=android-sdk_r08-linux_x86.tgz
+sdk.linux_bytes=TODO
+sdk.linux_checksum=TODO
 
 @jd:body
 
 
 <h2 id="quickstart">Quick Start</h2>
 
-<p>The steps below provide an overview of how to get started with the Android
-SDK. For detailed instructions, start with the <a
-href="{@docRoot}sdk/installing.html">Installing the SDK</a> guide. </p>
-
 <p><strong>1. Prepare your development computer</strong></p>
 
 <p>Read the <a href="{@docRoot}sdk/requirements.html">System Requirements</a>
@@ -34,38 +34,37 @@ install the <a href="http://java.sun.com/javase/downloads/index.jsp">JDK</a>
 
 <p><strong>2. Download and install the SDK starter package</strong></p>
 
-<p>Select a starter package from the table at the top of this page and download
+<p>Download a starter package from the table above onto your development computer.
-it to your development computer. To install the SDK, simply unpack the starter
+If you're using Windows, we recommend that you download the installer (the {@code .exe} file),
-package to a safe location and then add the location to your PATH. </p>
+which will launch a Wizard to guide you through the installation and check your computer for
+required software. Otherwise, download the SDK starter package ({@code .zip} or {@code .tgz})
+appropriate for your system, unpack it to a safe location, then add the location to your PATH
+environment variable. </p>
 
 <p><strong>3. Install the ADT Plugin for Eclipse</strong></p>
 
-<p>If you are developing in Eclipse, set up a remote update site at
+<p>If you are developing in Eclipse, add a new remote update site with the URL
 <code>https://dl-ssl.google.com/android/eclipse/</code>. Install the Android
-Development Tools (ADT) Plugin, restart Eclipse, and set the "Android" 
+Development Tools (ADT) Plugin from that site, restart Eclipse, and set the "Android"
-preferences in Eclipse to point to the SDK install location. For detailed
+preferences in Eclipse to point to the Android SDK directory (installed in the previous step). For
-instructions, see <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin 
+detailed instructions to setup Eclipse, see <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin
 for Eclipse</a>.</p>
 
 <p><strong>4. Add Android platforms and other components to your SDK</strong></p>
 
-<p>Use the Android SDK and AVD Manager, included in the SDK starter package, to
+<p>Launch the <em>Android SDK and AVD Manager</em> by executing {@code SDK Manager.exe} (Windows) or
-add one or more Android platforms (for example, Android 1.6 or Android 2.2) and
+{@code android} (Mac/Linux) from the SDK's {@code tools/} directory (if you used the Windows
-other components to your SDK. If you aren't sure what to add, see <a
+installer, this is launched for you when the Wizard is complete). Add some Android platforms
+(such as Android 1.6 and Android 2.3) and other components (such as documentation) to your SDK. If
+you aren't sure what to add, see <a
 href="installing.html#which">Which components do I need?</a></p>
 
-<p>To launch the Android SDK and AVD Manager on Windows, execute <code>SDK
-Setup.exe</code>, at the root of the SDK directory. On Mac OS X or Linux,
-execute the <code>android</code> tool in the <code>&lt;sdk&gt;/tools/</code>
-folder. For detailed instructions, see <a
-href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p>
-
 <p><strong>Done!</strong></p>
 
-<p>If you are new to Android, you can use the <a
+<p>To write your first Android application, see the <a
-href="{@docRoot}resources/tutorials/hello-world.html">Hello World</a> tutorial to
+href="{@docRoot}resources/tutorials/hello-world.html">Hello World</a> tutorial. Also see <a
-get started quickly. <a href="{@docRoot}sdk/installing.html#NextSteps">Next
+href="{@docRoot}sdk/installing.html#NextSteps">Next
-Steps</a> offers other suggestions of how to begin.</p>
+Steps</a> for other suggestions about how to get started.</p>
 
 <p>For a more detailed guide to installing and setting up the SDK, read <a
 href="installing.html">Installing the SDK</a>.</p>

docs/html/sdk/installing.jd

@@ -76,34 +76,40 @@ to install Eclipse, you can download it from this location: </p>
 <p>The first step in setting up your environment for developing Android applications
 is downloading the Android SDK starter package. The starter package is not a full
 development environment &mdash; it includes only the core SDK Tools, which you can
-use to download the rest of the SDK components. </p>
+use to download the rest of the SDK components (such as the platform system images). </p>
 
 <p>You can get the latest version of the SDK starter package from the <a
 href="{@docRoot}sdk/index.html">SDK download page</a>. Make sure to download the
 package that is appropriate for your development computer.</p>
 
-<p>After downloading, unpack the Android SDK archive to a safe location on your
+<p class="note"><strong>Note:</strong> If you're using Windows, we recommend that you download
-machine. By default, the SDK files are unpacked into a directory named
+the SDK installer (the {@code .exe} file from the download table). It will guide you through the
-<code>android-sdk-&lt;machine-platform&gt;</code>. Make a note of the name and
+installation process and check your computer for the required software.</p>
-location of the unpacked SDK directory on your system &mdash; you will need to
-refer to the SDK directory later, when setting up the ADT plugin or when using
-the SDK tools.</p>
 
-<p>Optionally, you may want to add the location of the SDK's primary
+<p>If you downloaded a {@code .zip} of {@code .tgz} (instead of using the SDK installer), unpack the
-<code>tools</code> directory to your system <code>PATH</code>. The primary
+Android SDK archive to a safe location on your machine. By default, the SDK files are unpacked into
-<code>tools/</code> directory is located at the root of the SDK folder. Adding
+a directory named <code>android-sdk-&lt;machine-platform&gt;</code>.</p>
-<code>tools</code> to your path lets you run Android Debug Bridge (adb) and the
+
-other command line <a
+<p>Make a note of the name and
+location of the unpacked SDK directory on your system &mdash; you will need to
+refer to the SDK directory later, when setting up the ADT plugin and when using
+the SDK tools from command line.</p>
+
+<p>Optionally, you might want to add the location of the SDK's primary
+<code>tools</code> directory and the additional {@code platform-tools/} directory  to your system
+<code>PATH</code>. Both tool directories are located at the root of the SDK folder. Adding
+<code>tools/</code> and {@code platform-tools/} to your path lets you run Android Debug Bridge (adb)
+and the other command line <a
 href="{@docRoot}guide/developing/tools/index.html">tools</a> without needing to
-supply the full path to the tools directory. </p> 
+supply the full path to the tool directories. </p>
 
 <ul>
     <li>On Linux, edit your <code>~/.bash_profile</code> or <code>~/.bashrc</code> file. Look
     for a line that sets the PATH environment variable and add the
-    full path to the <code>tools/</code> directory to it. If you don't 
+    full path to the <code>tools/</code> and {@code platform-tools/} directories to it. If you don't
     see a line setting the path, you can add one:</li>
 
-    <ul><code>export PATH=${PATH}:<em>&lt;your_sdk_dir&gt;</em>/tools</code></ul>
+    <ul><code>export PATH=${PATH}:&lt;your_sdk_dir&gt;/tools:&lt;your_sdk_dir&gt;/platform-tools</code></ul>
 
     <li>On a Mac OS X, look in your home directory for <code>.bash_profile</code> and
     proceed as for Linux. You can create the <code>.bash_profile</code> if
@@ -112,7 +118,7 @@ supply the full path to the tools directory. </p>
     <li>On Windows, right-click on My Computer, and select Properties.
   Under the Advanced tab, hit the Environment Variables button, and in the
   dialog that comes up, double-click on Path (under System Variables). Add the full path to the
-  <code>tools/</code> directory to the path. </li>
+  <code>tools/</code> and {@code platform-tools/} directories to the path. </li>
   </ul>
 
 <p>If you will be using the Eclipse IDE as your development environment, the
@@ -257,8 +263,8 @@ recommended or full development environment: </p>
 <td style="font-size:.9em;background-color:#FFE;color:gray">SDK Tools</td>
 <td style="font-size:.9em;background-color:#FFE;color:gray">If you've installed
 the SDK starter package, then you already have this component preinstalled. The
-SDK Tools component is required &mdash; you can't develop or build an application 
+SDK Tools and the SDK Platform-tools components are required &mdash; you can't develop or build an
-without it. </td>
+application without these. Make sure you keep these up to date.</td>
 </tr>
 
 <tr>
@@ -355,6 +361,15 @@ API Reference, and other information. To read the documentation, load the
 file <code>offline.html</code> in a web browser.</td>
 </tr>
 <tr>
+<td colspan="3"><code>platform-tools/</code></td>
+<td>Contains development tools that may be updated with each platform release (from the <em>Android
+SDK Platform-tools</em> component). Tools in here include {@code adb}, {@code dexdump}, and others
+others that you don't typically use directly. These tools are separate from the generic development
+tools in the {@code tools/} directory, because these tools may be updated in order to support new
+features in the latest Android platform, whereas the other tools have no dependencies on the
+platform version.</td>
+</tr>
+<tr>
 <td colspan="3"><code>platforms/</code></td>
 <td>Contains a set of Android platform versions that you can develop
 applications against, each in a separate directory.  </td>
@@ -397,7 +412,8 @@ designed for a specific screen resolution.</td>
 <td style="width:2em;border-bottom-color:white;"></td>
 <td style="width:2em;border-bottom-color:white;"></td>
 <td><code>tools/</code></td>
-<td>Any development tools that are specific to the platform version.</td>
+<td>This directory is used only by SDK Tools r7 and below for development tools that are specific to
+this platform version&mdash;it's not used by SDK Tools r8 and above.</td>
 </tr>
 <tr>
 <td style="width:2em;"></td>
@@ -411,8 +427,11 @@ version.</td>
 <td>Sample code and apps that are specific to platform version.</td>
 </tr>
 <td colspan="3"><code>tools/</code></td>
-<td>Contains the set of development and profiling tools available to you, such
+<td>Contains the set of development and profiling tools that are platform-independent, such
-as the emulator, the <code>android</code> tool, adb, ddms, and more.</td>
+as the emulator, the AVD and SDK Manager, adb, ddms, hierarchyviewer and more. The tools in
+this directory may be updated at any time (from the <em>Android SDK Tools</em> component),
+independent of platform releases, whereas the tools in {@code platform-tools/} may be updated based
+on the latest platform release.</td>
 </tr>
 <tr>
 <td colspan="3"><code>SDK Readme.txt</code></td>
@@ -421,7 +440,7 @@ including how to launch the Android SDK and AVD Manager tool on all
 platforms</td>
 </tr>
 <tr>
-<td colspan="3"><code>SDK Setup.exe</code></td>
+<td colspan="3"><code>SDK Manager.exe</code></td>
 <td>Windows SDK only. A shortcut that launches the Android SDK and AVD
 Manager tool, which you use to add components to your SDK. </td>
 </tr>