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

[Joel Brobecker <brobecker@adacore.com>]

[-- Attachment #1: Type: text/plain, Size: 1153 bytes --]

> > > After further consideration, and despite the fact that I said that
> > > the list might not grow that fast, I still tend to agree with you.
> > > I'll do that next. I think we should extract the text out of the 
> > > "misc[...]" node, and move it up to its own node.
> 
> Attached is a patch that does that. The diff looks different from
> the ChangeLog entry, but it's equivalent. As explained in the ChangeLog
> entry, I didn't change the text, only moved it, after having added
> a small introduction to the section.
> 
> 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.
> 
> OK to install?

Sorry, I think I forgot the patch!

-- 
Joel

[-- Attachment #2: 0001-Move-GDB-MI-commands-related-to-support-query-to-the.patch --]
[-- Type: text/x-diff, Size: 8431 bytes --]

From 33d128e63dc704bdcf6fa42149ef5961a6b1abd8 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 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 | 290 +++++++++++++++++++++++++++-------------------------
 1 file changed, 150 insertions(+), 140 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d7c90f5..a497c83 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -28831,6 +28831,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
 
@@ -35015,145 +35016,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}
@@ -35215,11 +35084,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:
@@ -35298,6 +35167,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.1.2