XDS debug configuration re-written

The "part-1/debug-configuration.md" file was re-written
for clarity and flow.

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

1 files changed, 81 insertions, 40 deletions

diff --git a/docs/part-1/debug-configuration.md b/docs/part-1/debug-configuration.md
index 8743bc1..af0d762 100644
--- a/docs/part-1/debug-configuration.md
+++ b/docs/part-1/debug-configuration.md
@@ -1,13 +1,20 @@
 # Configuration
 
- `xds-gdb` configuration is defined by variables (see listed below).
- These variables may be set using :
-
-- environment variables (inherited),
-- or a config file set with `XDS_CONFIG` environment variable, for example:
-  `XDS_CONFIG=/tmp/my_xds_gdb_config.env xds-gdb`
-- or by setting variables within a gdb ini file (see details below),
-- or a "user" config file located in following directory (first found is taken):
+Debug configuration (i.e. `xds-gdb`) is defined by variables.
+You can see the variables used further down in this section.
+
+You can set these variables using a number of methods:
+
+- Environment variables that are inherited.
+
+- Configuration file pointed to by the `XDS_CONFIG` environment variable
+  (e.g. `XDS_CONFIG=/tmp/my_xds_gdb_config.env xds-gdb`).
+
+- A GDB "init" command file.
+
+- A "user" configuration file located in one of the following
+  areas, which are order-dependent:
+
   1. $(CURRENT_DIRECTORY)/.xds-gdb.env
   1. $(CURRENT_DIRECTORY)/../xds-gdb.env
   1. $(CURRENT_DIRECTORY)/target/xds-gdb.env
@@ -15,60 +22,94 @@
 
 ## Configuration Variables
 
-`XDS_CONFIG` Config file defining `XDS_xxx` configuration variables.
+This section describes the `XDS_*` configuration variables.
+As previously mentioned, you can define these variables as
+described in the previous section.
 
-Variables of this file will overwrite inherited environment variables.
+- `XDS_LOGLEVEL`
 
-Variables definition may be  prefixed or not by "export" keyword.
+  Sets the logging level.
+  Levels include "panic", "fatal", "error", "warn", "info", and "debug".
 
-Here is an example of configuration file:
+- `XDS_LOGFILE`
 
-```bash
-# for example:
-# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
-cat > $MY_PROJECT_DIR/xds-gen3.conf << EOF
-export XDS_AGENT_URL=localhost:8800
-export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
-export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03
-EOF
-```
+  Sets the logging file.
+  The default is `/tmp/xds-gdb.log`.
+
+- `XDS_NATIVE_GDB`
 
-`XDS_LOGLEVEL`
+  Specifies to use native GDB mode rather than remote XDS mode.
 
-Set logging level (supported levels: panic, fatal, error, warn, info, debug)
+- `XDS_PROJECT_ID`  *(mandatory in XDS mode)*
 
-`XDS_LOGFILE`
+  The project ID you want to build.
 
-Set logging file, default `/tmp/xds-gdb.log`.
+- `XDS_RPATH`
 
-`XDS_NATIVE_GDB`
+  The relative path to the project.
 
-Use native gdb mode instead of remote XDS mode.
+- `XDS_SDK_ID`   *(mandatory in XDS mode)*
 
-`XDS_PROJECT_ID`  *(mandatory in XDS mode)*
+  Cross Sdk ID to use to build project
 
-Project ID you want to build
+- `XDS_AGENT_URL`
 
-`XDS_RPATH`
+  The local XDS agent URL.
+  The default is `http://localhost:8800`.
 
-Relative path into project
+## Configuration Using `XDS_CONFIG`
 
-`XDS_SDK_ID`   *(mandatory in XDS mode)*
+As mentioned, you can define configuration variables in
+a file you point to with the `XDS_CONFIG` variable.
+Here is an example:
+
+```bash
+XDS_CONFIG=/tmp/my_xds_gdb_config.env xds-gdb
+```
+
+Variables defined in this file overwrite any inherited
+environment variables.
+When you define a variable in the file, you can prefix the
+assignment with the "export" string.
+Doing so causes the variable to be exported to the environment.
+
+Following is an example of a configuration file pointed
+to by the `XDS_CONFIG` variable.
+These commands create the `xds-gen3.conf` configuration file
+in the `$MY_PROJECT_DIR` directory:
+
+```bash
+# MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
+cat > $MY_PROJECT_DIR/xds-gen3.conf << EOF
+export XDS_AGENT_URL=localhost:8800
+export XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b
+export XDS_SDK_ID=c226821b-b5c0-386d-94fe-19f807946d03
+EOF
+```
 
-Cross Sdk ID to use to build project
+## Configuration Using GDB Init
 
-`XDS_AGENT_URL`
+GDB is a versatile debugger and can be run with many options.
+One such option is to execute a GDB "init" file upon startup.
+You do this by using the "--command" or "-x" command-line options
+and providing the name of the init file.
 
-Local XDS agent url (default `http://localhost:8800`)
+<!-- section-note -->
+**NOTES:**
 
-## Configuration variables set within gdb init command file
+- For information on debugging with GDB, see
+  "[Debugging with GDB](https://www.sourceware.org/gdb/onlinedocs/gdb.html#index-_002d_002dcommand)".
 
-Above `XDS_xxx` variables may also be defined within gdb init command file
-(see --command or -x option of genuine Gdb).
+- For information on GDB init files, see
+  "[Command files](https://ftp.gnu.org/old-gnu/Manuals/gdb-5.1.1/html_node/gdb_190.html)".
+<!-- end-section-note -->
 
-You must respect the following syntax: commented line including `:XDS-ENV:` tag
+When you create an init file, it must conform to the following
+syntax (i.e. inclusion of what are normally commenting characters
+as well as use of the `:XDS-ENV:` tag).
 
-Example of gdb init file where we define project and sdk ID:
+Following is an example init file that defines the `XDS_PROJECT_ID`
+and `XDS_SDK_ID` variables:
 
 ```bash
      # :XDS-ENV: XDS_PROJECT_ID=4021617e-ced0-11e7-acd2-3c970e49ad9b