XDS debug command line re-written

I re-wrote the topic for debugging in XDS using the command
line.

Change-Id: I5ebf8f0a4f4ff92b3f53894a0caeb1fa662a2825
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>

1 files changed, 68 insertions, 26 deletions

diff --git a/docs/part-1/debug-cmd-line.md b/docs/part-1/debug-cmd-line.md
index 2c25517..f279c7b 100644
--- a/docs/part-1/debug-cmd-line.md
+++ b/docs/part-1/debug-cmd-line.md
@@ -1,48 +1,76 @@
-# Debug using xds-gdb from command line
+# Using the XDS Command Line
 
-## XDS remote debugging mode
+You can debug your AGL application using the XDS command line
+in XDS remote mode or in native mode.
 
-First the project you want to debug must be declared on an xds-server and this
-project may also has been built using using XDS (see [Create your first AGL application](../../../#create-your-first-agl-application) for more details).
+## XDS Remote Mode
 
-So to debug it you need to have the XDS agent - server chain in place and
-you also need the project and sdk unique id.
+XDS remote debugging is the default mode for using XDS to debug your
+application.
 
-You can find these IDs in project page of XDS dashboard or you can get them from command line using the `--list` option.
 
-This option lists all existing projects ID:
+Follow this procedure to use XDS remotely to debug your application:
 
-```bash
-xds-gdb --list
-```
+1. Declare to the `xds-server` the project you want to debug.
+   The project can also have been built using XDS.
+   See the "[Create your first AGL application](../../../#create-your-first-agl-application)"
+   section for more details.
+
+2. Be sure you have the XDS agent and XDS server chain in place.
+   You can find more information on this chain in the
+   "[Overview](../../../#xds-overview)" section.
+
+3. Determine the unique project and sdk ID values.
+   Two methods exist for you to locate these ID values:
+
+   - Use the "Project" page of XDS dashboard.
+
+   - Use the `xds-gdb --list` command from the XDS command line.
+     This command returns the list of all existing project and SDK
+     IDs:
 
-Now to refer your project, just set `XDS_PROJECT_ID` and `XDS_SDK_ID` variables.
+     ```bash
+     xds-gdb --list
+     ```
 
-You are now ready to use `xds-gdb` to for example cross debug your project.
+4. Define the `XDS_PROJECT_ID` and `XDS_SDK_ID` variables.
+   Defining these variables refers the project to the
+   `xds-server`.
+   Once you refer the project, you are ready to use `xds-gdb`
+   (e.g. cross debug your project).
 
-Here is an example to build and debug a project based on CMakefile and
+5. Build and debug the project.
+
+**Example**
+
+Following is an example that builds and debugs a project
+based on a CMakefile and the
 [cmake-apps-module](https://git.automotivelinux.org/src/cmake-apps-module/):
 
 ```bash
-# Go into your project directory (for example helloworld-native-application)
+# Go into your project directory (e.g. helloworld-native-application)
 cd ~/xds-workspace
+# Clone the project files into your local directory.
 git clone https://github.com/iotbzh/helloworld-native-application.git
+# Go to the local project's directory.
 cd helloworld-service
 
 # Declare your project on xds-server
-# <for now, you can only do this step using xds HTML dashboard (see xds-server doc)>
+# For now, you can only do this step using the XDS Dashboard.
+# See the "Build Using the XDS Dashboard" topic in the "Create Your
+# First Application" section.
 
-# Define XDS config
+# Define XDS configuration variables by creating a "xds-config.env" file.
 cat <<EOF >./xds-config.env
 #optional if not default value: XDS_AGENT_URL=http://localhost:8800
 XDS_PROJECT_ID=IW7B4EE-DBY4Z74_myProject
 XDS_SDK_ID=poky-agl_aarch64_4.0.1
 EOF
 
-# Tell to xds-cli and xds-gdb which is your config file
+# Tell the xds-cli and xds-gdb what configuration file to use.
 export XDS_CONFIG=../xds-gen3.conf
 
-# Create a new build directory
+# Create a new build directory.
 mkdir build && cd build
 
 # Start remote cross build
@@ -55,15 +83,29 @@ xds-gdb -x target/gdb-on-root@myTarget.ini
 ```
 
 <!-- section-note -->
-**Note:** : [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application) project is an AGL
-project based on [cmake-apps-module](https://git.automotivelinux.org/src/cmake-apps-module/)
-(refer to install cmake module [instructions](../../cmakeafbtemplates/dev_guide/installing-cmake.html)). This CMake templating, used to develop application
-with the AGL Application Framework, will automatically generate makefile rules
-(eg. `remote-target-populate`) or scripts (eg. `build/target/xxx` scripts).
+**NOTE:**
+
+The [helloworld-native-application](https://github.com/iotbzh/helloworld-native-application)
+project is an AGL project based on the
+[cmake-apps-module](https://git.automotivelinux.org/src/cmake-apps-module/).
+For information on installing this module, see the
+"[Installing the CMAKE Templates](../../cmakeafbtemplates/dev_guide/installing-cmake.html))"
+section.
 
-For more info about app-template, please refer to [this documentation](../../../#using-the-cmake-applications-module).
+The CMake templates, used to develop applications with the AGL Application
+Framework, automatically generates Makefile rules
+(e.g. `remote-target-populate`) or scripts (e.g. `build/target/*`).
+
+For more info about the CMake templates, see the
+"[Using the Cmake Applications Module](../../../#using-the-cmake-applications-module).
 <!-- end-section-note -->
 
 ## Native debugging
 
-To enable native debugging mode, you need to define `XDS_NATIVE_GDB` variable.
+Native debugging using GDB directly.
+
+To enable native debugging mode, set the `XDS_NATIVE_GDB` variable.
+
+For information on debugging with GDB, see the
+"[Debugging with GDB](https://www.sourceware.org/gdb/onlinedocs/gdb.html#index-_002d_002dcommand)"
+section.