Re: [RFA/commit+doco] GDB/MI: Document support for -exec-run --start in -list-features

[Joel Brobecker <brobecker at adacore dot com>]

> > > gdb/doc/ChangeLog:
> > > 
> > >         * gdb.texinfo (GDB/MI): Add "GDB/MI Support Commands" entry
> > >         in menu.
> > >         (GDB/MI Support Commands): New node, with its contents being
> > >         extracted from the "GDB/MI Miscellaneous Commands" node.
> > >         A small paragraph introducing the section is also added at
> > >         the start.
> > >         (GDB/MI Miscellaneous Commands): Delete the description of the
> > >         -info-gdb-mi-command, -list-features and -list-target-features
> > >         commands, now hosted in the "GDB/MI Support Commands" node.
> This is OK to go in.  Thanks.

Sorry about the delay, Eli. I realized shortly after you approved
the patch that I forgot one tiny piece which was obvious in retrospect:
Fix the cross references to the "old" node/location. It turns out
that there was only one such reference so far, so the patch is not
very different.

Attached is what I checked in.

gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI): Add "GDB/MI Support Commands" entry
        in menu.
        (GDB/MI Variable Objects): Adjust reference to "-list-features"
        command, now in a new node.
        (GDB/MI Support Commands): New node, with its contents being
        extracted from the "GDB/MI Miscellaneous Commands" node.
        A small paragraph introducing the section is also added at
        the start.
        (GDB/MI Miscellaneous Commands): Delete the description of the
        -info-gdb-mi-command, -list-features and -list-target-features
        commands, now hosted in the "GDB/MI Support Commands" node.

-- 
Joel

>From 95cd9351c0d5404644ba45b5fbba7cf7e6985ec4 Mon Sep 17 00:00:00 2001
From: Joel Brobecker <brobecker@adacore.com>
Date: Fri, 13 Dec 2013 07:01:33 +0100
Subject: [PATCH] Move GDB/MI commands related to support-query to their own
 @node.

A number of commands provide the capability to query the debugger
about support for various features, and one of them in particular
(-list-features), is expected to grow as new features get added.
-list-target-features should also grow a bit over time, but probably
slower.

These commands deserve their own section and @node.

gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI): Add "GDB/MI Support Commands" entry
        in menu.
        (GDB/MI Variable Objects): Adjust reference to "-list-features"
        command, now in a new node.
        (GDB/MI Support Commands): New node, with its contents being
        extracted from the "GDB/MI Miscellaneous Commands" node.
        A small paragraph introducing the section is also added at
        the start.
        (GDB/MI Miscellaneous Commands): Delete the description of the
        -info-gdb-mi-command, -list-features and -list-target-features
        commands, now hosted in the "GDB/MI Support Commands" node.
---
 gdb/doc/gdb.texinfo | 292 +++++++++++++++++++++++++++-------------------------
 1 file changed, 151 insertions(+), 141 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index b7551c2..29f1cfc 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -28845,6 +28845,7 @@ may repeat one or more times.
 * GDB/MI Target Manipulation::
 * GDB/MI File Transfer Commands::
 * GDB/MI Ada Exceptions Commands::
+* GDB/MI Support Commands::
 * GDB/MI Miscellaneous Commands::
 @end menu
 
@@ -33003,7 +33004,7 @@ select a visualizer by following the built-in process
 a varobj is created, and so ordinarily is not needed.
 
 This feature is only available if Python support is enabled.  The MI
-command @code{-list-features} (@pxref{GDB/MI Miscellaneous Commands})
+command @code{-list-features} (@pxref{GDB/MI Support Commands})
 can be used to check this.
 
 @subsubheading Example
@@ -35029,145 +35030,13 @@ Catchpoint Commands}.
 
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-@node GDB/MI Miscellaneous Commands
-@section Miscellaneous @sc{gdb/mi} Commands
-
-@c @subheading -gdb-complete
-
-@subheading The @code{-gdb-exit} Command
-@findex -gdb-exit
-
-@subsubheading Synopsis
-
-@smallexample
- -gdb-exit
-@end smallexample
-
-Exit @value{GDBN} immediately.
-
-@subsubheading @value{GDBN} Command
-
-Approximately corresponds to @samp{quit}.
-
-@subsubheading Example
-
-@smallexample
-(gdb)
--gdb-exit
-^exit
-@end smallexample
-
-
-@ignore
-@subheading The @code{-exec-abort} Command
-@findex -exec-abort
-
-@subsubheading Synopsis
-
-@smallexample
- -exec-abort
-@end smallexample
-
-Kill the inferior running program.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{kill}.
-
-@subsubheading Example
-N.A.
-@end ignore
-
-
-@subheading The @code{-gdb-set} Command
-@findex -gdb-set
-
-@subsubheading Synopsis
-
-@smallexample
- -gdb-set
-@end smallexample
-
-Set an internal @value{GDBN} variable.
-@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{set}.
-
-@subsubheading Example
-
-@smallexample
-(gdb)
--gdb-set $foo=3
-^done
-(gdb)
-@end smallexample
-
-
-@subheading The @code{-gdb-show} Command
-@findex -gdb-show
-
-@subsubheading Synopsis
-
-@smallexample
- -gdb-show
-@end smallexample
-
-Show the current value of a @value{GDBN} variable.
-
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} command is @samp{show}.
-
-@subsubheading Example
-
-@smallexample
-(gdb)
--gdb-show annotate
-^done,value="0"
-(gdb)
-@end smallexample
-
-@c @subheading -gdb-source
-
-
-@subheading The @code{-gdb-version} Command
-@findex -gdb-version
+@node GDB/MI Support Commands
+@section @sc{gdb/mi} Support Commands
 
-@subsubheading Synopsis
-
-@smallexample
- -gdb-version
-@end smallexample
-
-Show version information for @value{GDBN}.  Used mostly in testing.
-
-@subsubheading @value{GDBN} Command
-
-The @value{GDBN} equivalent is @samp{show version}.  @value{GDBN} by
-default shows this information when you start an interactive session.
-
-@subsubheading Example
-
-@c This example modifies the actual output from GDB to avoid overfull
-@c box in TeX.
-@smallexample
-(gdb)
--gdb-version
-~GNU gdb 5.2.1
-~Copyright 2000 Free Software Foundation, Inc.
-~GDB is free software, covered by the GNU General Public License, and
-~you are welcome to change it and/or distribute copies of it under
-~ certain conditions.
-~Type "show copying" to see the conditions.
-~There is absolutely no warranty for GDB.  Type "show warranty" for
-~ details.
-~This GDB was configured as
- "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
-^done
-(gdb)
-@end smallexample
+Since new commands and features get regularly added to @sc{gdb/mi},
+some commands are available to help front-ends query the debugger
+about support for these capabilities.  Similarly, it is also possible
+to query @value{GDBN} about target support of certain features.
 
 @subheading The @code{-info-gdb-mi-command} Command
 @cindex @code{-info-gdb-mi-command}
@@ -35229,11 +35098,11 @@ this version of gdb implements.  A feature can be a command,
 or a new field in an output of some command, or even an
 important bugfix.  While a frontend can sometimes detect presence
 of a feature at runtime, it is easier to perform detection at debugger
-startup. 
+startup.
 
 The command returns a list of strings, with each string naming an
 available feature.  Each returned string is just a name, it does not
-have any internal structure.  The list of possible feature names 
+have any internal structure.  The list of possible feature names
 is given below.
 
 Example output:
@@ -35312,6 +35181,147 @@ Indicates that the target is capable of reverse execution.
 
 @end table
 
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI Miscellaneous Commands
+@section Miscellaneous @sc{gdb/mi} Commands
+
+@c @subheading -gdb-complete
+
+@subheading The @code{-gdb-exit} Command
+@findex -gdb-exit
+
+@subsubheading Synopsis
+
+@smallexample
+ -gdb-exit
+@end smallexample
+
+Exit @value{GDBN} immediately.
+
+@subsubheading @value{GDBN} Command
+
+Approximately corresponds to @samp{quit}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-gdb-exit
+^exit
+@end smallexample
+
+
+@ignore
+@subheading The @code{-exec-abort} Command
+@findex -exec-abort
+
+@subsubheading Synopsis
+
+@smallexample
+ -exec-abort
+@end smallexample
+
+Kill the inferior running program.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{kill}.
+
+@subsubheading Example
+N.A.
+@end ignore
+
+
+@subheading The @code{-gdb-set} Command
+@findex -gdb-set
+
+@subsubheading Synopsis
+
+@smallexample
+ -gdb-set
+@end smallexample
+
+Set an internal @value{GDBN} variable.
+@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ?????
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{set}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-gdb-set $foo=3
+^done
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-gdb-show} Command
+@findex -gdb-show
+
+@subsubheading Synopsis
+
+@smallexample
+ -gdb-show
+@end smallexample
+
+Show the current value of a @value{GDBN} variable.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{show}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-gdb-show annotate
+^done,value="0"
+(gdb)
+@end smallexample
+
+@c @subheading -gdb-source
+
+
+@subheading The @code{-gdb-version} Command
+@findex -gdb-version
+
+@subsubheading Synopsis
+
+@smallexample
+ -gdb-version
+@end smallexample
+
+Show version information for @value{GDBN}.  Used mostly in testing.
+
+@subsubheading @value{GDBN} Command
+
+The @value{GDBN} equivalent is @samp{show version}.  @value{GDBN} by
+default shows this information when you start an interactive session.
+
+@subsubheading Example
+
+@c This example modifies the actual output from GDB to avoid overfull
+@c box in TeX.
+@smallexample
+(gdb)
+-gdb-version
+~GNU gdb 5.2.1
+~Copyright 2000 Free Software Foundation, Inc.
+~GDB is free software, covered by the GNU General Public License, and
+~you are welcome to change it and/or distribute copies of it under
+~ certain conditions.
+~Type "show copying" to see the conditions.
+~There is absolutely no warranty for GDB.  Type "show warranty" for
+~ details.
+~This GDB was configured as
+ "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi".
+^done
+(gdb)
+@end smallexample
+
 @subheading The @code{-list-thread-groups} Command
 @findex -list-thread-groups
 
-- 
1.8.3.2