Bug 389527: Update DSF-GDB preference page help

Change-Id: Ie0fb6937ff73f15525db2bdd178464b6bdc9a2d7
Reviewed-on: https://git.eclipse.org/r/7766
Reviewed-by: John Cortell <john.cortell@freescale.com>
IP-Clean: John Cortell <john.cortell@freescale.com>
Tested-by: John Cortell <john.cortell@freescale.com>
Reviewed-by: Marc Khouzam <marc.khouzam@ericsson.com>
IP-Clean: Marc Khouzam <marc.khouzam@ericsson.com>
Tested-by: Marc Khouzam <marc.khouzam@ericsson.com>

5 files changed, 107 insertions, 19 deletions

diff --git a/doc/org.eclipse.cdt.doc.user/META-INF/MANIFEST.MF b/doc/org.eclipse.cdt.doc.user/META-INF/MANIFEST.MF
index 59a8c62e03d..6b17a68264b 100644
--- a/doc/org.eclipse.cdt.doc.user/META-INF/MANIFEST.MF
+++ b/doc/org.eclipse.cdt.doc.user/META-INF/MANIFEST.MF
@@ -2,7 +2,7 @@ Manifest-Version: 1.0
 Bundle-ManifestVersion: 2
 Bundle-Name: %pluginName
 Bundle-SymbolicName: org.eclipse.cdt.doc.user; singleton:=true
-Bundle-Version: 5.2.0.qualifier
+Bundle-Version: 5.3.0.qualifier
 Bundle-Vendor: %providerName
 Bundle-Localization: plugin
 Bundle-ActivationPolicy: lazy
diff --git a/doc/org.eclipse.cdt.doc.user/contexts_CDT_DEBUGGER_DSFGDB.xml b/doc/org.eclipse.cdt.doc.user/contexts_CDT_DEBUGGER_DSFGDB.xml
index f5fe3e23822..1130ab9c6a6 100644
--- a/doc/org.eclipse.cdt.doc.user/contexts_CDT_DEBUGGER_DSFGDB.xml
+++ b/doc/org.eclipse.cdt.doc.user/contexts_CDT_DEBUGGER_DSFGDB.xml
@@ -2,7 +2,7 @@
 <?NLS TYPE="org.eclipse.help.contexts"?>
 <!DOCTYPE contexts [
 	<!ENTITY defaultCSHelp "Default Context Sensitive Help">
-	<!ENTITY gdbmiPrefs "GDB MI Preference Page">
+	<!ENTITY gdbPrefs "GDB Preferences">
 ]>
 <contexts>
 
@@ -12,12 +12,10 @@
    	label="&defaultCSHelp;"/>
 </context>
 <context id="dsfgdb_preference_page">
-   <description>Control the behavior of the C/C++ debugger when debugging with GDB, specifically when using a GDB (DSF) launcher.</description>
-   <topic href="reference/cdt_u_dsfgdb.htm" label="GDB Preferences"/>
+   <description>Control the behavior of the C/C++ debugger when debugging with GDB, specifically when using a GDB (DSF) launcher.  Click below to see detailed help.</description>
+   <topic href="reference/cdt_u_dsfgdb.htm" label="&gdbPrefs;"/>
 </context>
 <context id="update_threadlist_button_context" title="Force thread list update on suspend">
    <description>This checkbox controls whether the CDT debugger will ask gdb for the target program&apos;s thread list on each suspend event (breakpoint-hit, step, etc). Normally, this isn&apos;t necessary, as GDB sends notifications in realtime when a thread is created or destroyed. However, some lightweight GDB remote stubs won&apos;t send these notifications. As such, the CDT debugger doesn&apos;t find out about new or destroyed threads unless it polls gdb. Turn on this option if you are debugging such a target (typically an embedded one).</description>
 </context>
-
-
 </contexts>
diff --git a/doc/org.eclipse.cdt.doc.user/images/cdt_dsfgdb_preferences_page.png b/doc/org.eclipse.cdt.doc.user/images/cdt_dsfgdb_preferences_page.png
index c810b8743c8..73e67454fb4 100644
--- a/doc/org.eclipse.cdt.doc.user/images/cdt_dsfgdb_preferences_page.png
+++ b/doc/org.eclipse.cdt.doc.user/images/cdt_dsfgdb_preferences_page.png
diff --git a/doc/org.eclipse.cdt.doc.user/pom.xml b/doc/org.eclipse.cdt.doc.user/pom.xml
index 337e431b85e..5c69a990f52 100644
--- a/doc/org.eclipse.cdt.doc.user/pom.xml
+++ b/doc/org.eclipse.cdt.doc.user/pom.xml
@@ -10,7 +10,7 @@
 		<relativePath>../../pom.xml</relativePath>
 	</parent>
 
-	<version>5.2.0-SNAPSHOT</version>
+	<version>5.3.0-SNAPSHOT</version>
 	<artifactId>org.eclipse.cdt.doc.user</artifactId>
 	<packaging>eclipse-plugin</packaging>
 
diff --git a/doc/org.eclipse.cdt.doc.user/reference/cdt_u_dsfgdb.htm b/doc/org.eclipse.cdt.doc.user/reference/cdt_u_dsfgdb.htm
index f07bf3a3a33..bad7c2b0e2f 100644
--- a/doc/org.eclipse.cdt.doc.user/reference/cdt_u_dsfgdb.htm
+++ b/doc/org.eclipse.cdt.doc.user/reference/cdt_u_dsfgdb.htm
@@ -12,7 +12,7 @@
 
 <h1 role="main">GDB Debugging Preferences</h1>
 
-<p>Use the <img src="../images/command_link.png" alt="" > <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.cdt.dsf.gdb.ui.preferences)")'>GDB</a> preferences panel to control how the CDT debugger behaves when debugging with GDB, 
+<p>Use this preferences panel to control how the CDT debugger behaves when debugging with GDB, 
 specifically when using a <em>GDB (DSF)</em> launcher. 
 <p><img src="../images/cdt_dsfgdb_preferences_page.png"  alt="GDB preferences panel"></p>
 
@@ -20,31 +20,121 @@ specifically when using a <em>GDB (DSF)</em> launcher.
 <p><table border="1" cellpadding="4" cellspacing="0" width="700px" bordercolor="#DDDDDD" >
 	<caption><strong>GDB Preference Panel Options</strong></caption>
 	<colgroup>
-		<col width="25%" valign="top" >
-		<col width="75%" valign="top" >
+		<col width="20%" valign="top" >
+		<col width="30%" valign="top" >
+		<col width="50%" valign="top" >
 	</colgroup>
  	<tr>
+		<th id="category">Category</th>	
 		<th id="option">Option</th>	
 		<th id="description">Description</th>
-	 </tr>
+	</tr>
+
+	<! -------------------------------------------------------------------------------------------------- >
+	<! ----------------------------- Debug Configurations Defaults Category ----------------------------- >
+	<! -------------------------------------------------------------------------------------------------- >
+
 	<tr>
-		<td valign="top" headers="option"><strong>Enable GDB traces</strong></td>
-		<td valign="top" headers="description">When checked, the debug session will produce an additional console which will contain all the gdb/mi activity. Basically, this details the 
-  interaction between the CDT debugger and GDB. This information is often critical when the debugger is not behaving as you expect. Turn this on and submit
-  the console output when submitting a bugzilla report against the CDT debugger.</td>
+		<td rowspan=6 valign="top" headers="category"><strong>Debug Configurations Defaults</strong></td>
+	</tr>
+	<tr>
+		<td valign="top" headers="option"><strong>GDB debugger</strong></td>
+		<td valign="top" headers="description">Specifies the GDB debugger binary that will be used by default for each 
+		newly created debug launch.  Using an absolute path will directly point to the binary (e.g, /home/user/myGdb), 
+		while using a binary name will have CDT look through the PATH variable for that binary (e.g., myGdb).  This can
+		be useful of your GDB binary is not named 'gdb'.  Each launch configuration allows to override this setting in
+		the Debugger tab.</td>
+	</tr>
+	<tr>
+		<td valign="top" headers="option"><strong>GDB command file</strong></td>
+		<td valign="top" headers="description">Specifies the GDB debugger command file that will be used by default for each 
+		newly created debug launch.  This can be useful if you often/always want to use a GDB command file for your launches.
+		Each launch configuration allows to override this setting in the Debugger tab.</td>
+	</tr>
+	<tr>
+		<td valign="top" headers="option"><strong>Stop on startup</strong></td>
+		<td valign="top" headers="description">When checked, the CDT debugger will stop execution at the specified symbol when
+		launching or re-starting a process.  By default, this setting makes the CDT debugger stop when entering 'main'.</td>
+	</tr>
+	<tr>
+		<td valign="top" headers="option"><strong>Command timeout</strong></td>
+		<td valign="top" headers="description">When checked, the CDT debugger will abort the debug session if any command sent 
+		to GDB does not get an answer before the specified timeout.  Using this can prevent debug sessions from hanging forever 
+		when debugging un-reliable targets.
+		<p>
+		Using the <em>Advanced...</em> button allows to set a different timeout for individual commands.  A value of zero can be
+		used to specify "no timeout" for a particular command.  MI commands must start with a hyphen ('-').  
+		For example, '-target-select'.</td>
+	</tr>
+	<tr>
+		<td valign="top" headers="option"><strong>Non-stop mode</strong></td>
+		<td valign="top" headers="description">When checked, the CDT debugger will run in non-stop mode for each newly created 
+		debug launch.  <em>Non-stop</em> mode allows each thread of a debug session to be controlled independently. This allows to stop 
+		one or more threads while leaving others running. In contrast, <em>all-stop</em> mode interrupts and resumes all threads at the
+		same time.  Note that <em>non-stop</em> mode is only available starting with GDB 7.0.</td>
+	</tr>
+
+	<! -------------------------------------------------------------------------------------------------- >
+	<! ------------------------------------ General Behavior Category ----------------------------------- >
+	<! -------------------------------------------------------------------------------------------------- >
+	
+	<tr>
+		<td rowspan=5 valign="top" headers="category"><strong>General Behavior</strong></td>
 	</tr>
 	<tr>
 		<td valign="top" headers="option"><strong>Terminate GDB when last process exits</strong></td>
-		<td valign="top" headers="description">When checked, the CDT debugger will terminate the GDB host process after all the target processes it is debugging have terminated. Otherwise it will leave it running.</td>
+		<td valign="top" headers="description">When checked, the CDT debugger will terminate the GDB
+		process (on the host) after all the target processes it is debugging have terminated. Otherwise it 
+		will leave it running.  It can be useful to keep GDB running if you expect to want to attach or create
+		new processes to debug after the previously debugged processes have terminated.</td>
 	</tr>
 	<tr>
 		<td valign="top" headers="option"><strong>Use enhanced debug hover</strong></td>
-		<td valign="top" headers="description">When checked, hovering over an expression in the editor during a debug session will bring up an <em>enhanced</em> expression evaluation control. Otherwise, a more basic control is used. This, of course, assumes that you have the debugger's hovering capability turned on in C/C++ > Editor > Hovers. If not, this checkbox has no effect.<br>
-	<img src="../images/cdt_debug_hover_modes.png"  alt="debug hover modes"></td>
+		<td valign="top" headers="description">When checked, hovering over an expression in the editor during a 
+		debug session will bring up an <em>enhanced</em> expression evaluation control. Otherwise, a more basic 
+		control is used. This, of course, assumes that you have the debugger's hovering capability turned on in 
+		C/C++ > Editor > Hovers. If not, this checkbox has no effect.<br>
+			<img src="../images/cdt_debug_hover_modes.png"  alt="debug hover modes"></td>
+	</tr>
+	<tr>
+		<td valign="top" headers="option"><strong>Show only suspended threads in the Debug view</strong></td>
+		<td valign="top" headers="description">When checked, the Debug view will only show threads that are suspended.
+		When dealing with a large number of threads, this helps focus on the threads being inspected.  Obviously, 
+		this option is only valuable in <em>non-stop</em> mode, where some threads can run while others are stopped.</td>
+	</tr>
+	<tr>
+		<td valign="top" headers="option"><strong>Enable GDB traces</strong></td>
+		<td valign="top" headers="description">When checked, the debug session will produce an additional console which 
+		will contain all the gdb/mi activity. Basically, this details the interaction between the CDT debugger and GDB. 
+		This information is often critical when the debugger is not behaving as you expect. Include this console output
+		when submitting a bugzilla report against the CDT debugger.  It is recommended to keep this setting enabled at 
+		all times, as it does not cause any negative effect.</td>
 	</tr>
+
+	<! -------------------------------------------------------------------------------------------------- >
+	<! ----------------------------------- Pretty Printing Category ------------------------------------- >
+	<! -------------------------------------------------------------------------------------------------- >
+
+	<tr>
+		<td rowspan=3 valign="top" headers="category"><strong>Pretty Printing</strong></td>
+	</tr>
+	<tr>
+		<td valign="top" headers="option"><strong>Enable pretty printers in variable/expression tree</strong></td>
+		<td valign="top" headers="description">When checked, the CDT Debugger will display STL types in a user-friendly
+		fashion.  This can be seen in the Variables and Expressions views, as well as in the advanced editor hover.
+		For example, Maps, Lists and Vectors will be shown in an array-style format instead of showing the
+		details of the actual implementation of the data struture.  Note that <em>pretty printing</em> requires a GDB that
+		has python support enabled and the user of STL pretty-printers.</td>
+	</tr>
+	<tr>
+		<td valign="top" headers="option"><strong>For collections, initially limit child count to</strong></td>
+		<td valign="top" headers="description">When using pretty printing, collections (e.g., Maps, Lists, etc) can contain
+		a large number of elements.  Trying to display all this children at once can cause very poor responsiveness.  This
+		value will limit the number of children displayed initially, while allowing the user to manually request more
+		children directly from the view.</td>
+	</tr>	
 </table>
 <p><img src="../images/ngref.gif" ALT="Related reference" width="143" height="21"> <br>
-<a href="../reference/cdt_u_gdb_mi.htm">GDB MI Debug preferences</a></p>
 <hr >
 <p><img src="../images/ng00_04a.gif" ALT="IBM Copyright Statement" ></p>