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

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

[Joel Brobecker]

Hello,

While reviewing all the changes I made for GDB/MI, recently, and making
sure that every new features should be check-able before use, I noticed
that were were missing a way to test if --exec-run supports --start.

This adds "exec-run-start-option" in the output of the -list-features
commands, allowing front-ends to easily determine whether -exec-run
supports the --start option.

gdb/ChangeLog:

        * mi/mi-main.c (mi_cmd_list_features): add "exec-run-start-option".
        * NEWS: Expand the entry documenting the new -exec-run --start
        option to mention the corresponding new entry in the output of
        "-list-features".

gdb/doc/ChangeLog:

	* gdb.texinfo (GDB/MI Miscellaneous Commands): Document the new
	"exec-run-start-option" entry in the output of the "-list-features"
	command.

gdb/testsuite/ChangeLog:

        * gdb.mi/mi-start.exp: Add test verifying that -list-features
        contains "exec-run-start-option".

Tested on x86_64-linux. Both code and doco parts are relatively
straightforward, so I am planning on checking this in in a day or
two, assuming doco approval.

Thanks,
-- 
Joel

---
 gdb/NEWS                          | 4 +++-
 gdb/doc/gdb.texinfo               | 3 +++
 gdb/mi/mi-main.c                  | 1 +
 gdb/testsuite/gdb.mi/mi-start.exp | 6 ++++++
 4 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index 72816a0..04f4acd 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -188,7 +188,9 @@ show code-cache
   ** The -exec-run command now accepts an optional "--start" option.
      When used, the command follows the same semantics as the "start"
      command, stopping the program's execution at the start of its
-     main subprogram.
+     main subprogram.  Support for this feature can be verified using
+     the "-list-features" command, which should contain
+     "exec-run-start-option".
 
   ** The new commands -catch-assert and -catch-exceptions insert
      catchpoints stopping the program when Ada exceptions are raised.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 2602427..30a7227 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -35213,6 +35213,9 @@ Indicates support for the @code{-info-gdb-mi-command} command.
 Indicates support for the "undefined-command" error code in error result
 records, produced when trying to execute an undefined @sc{gdb/mi} command
 (@pxref{GDB/MI Result Records}).
+@item exec-run-start-option
+Indicates that the @code{-exec-run} command supports the @option{--start}
+option (@pxref{GDB/MI Program Execution}).
 @end table
 
 @subheading The @code{-list-target-features} Command
diff --git a/gdb/mi/mi-main.c b/gdb/mi/mi-main.c
index 07f1dc1..63456cd 100644
--- a/gdb/mi/mi-main.c
+++ b/gdb/mi/mi-main.c
@@ -1818,6 +1818,7 @@ mi_cmd_list_features (char *command, char **argv, int argc)
       ui_out_field_string (uiout, NULL, "language-option");
       ui_out_field_string (uiout, NULL, "info-gdb-mi-command");
       ui_out_field_string (uiout, NULL, "undefined-command-error-code");
+      ui_out_field_string (uiout, NULL, "exec-run-start-option");
 
 #if HAVE_PYTHON
       if (gdb_python_initialized)
diff --git a/gdb/testsuite/gdb.mi/mi-start.exp b/gdb/testsuite/gdb.mi/mi-start.exp
index 98dfef4..0cd759f 100644
--- a/gdb/testsuite/gdb.mi/mi-start.exp
+++ b/gdb/testsuite/gdb.mi/mi-start.exp
@@ -41,6 +41,12 @@ mi_gdb_reinitialize_dir $srcdir/$subdir
 mi_gdb_reinitialize_dir $srcdir/$subdir
 mi_gdb_load ${binfile}
 
+# First, verify that the debugger correctly advertises support
+# for the --start option of the -exec-run command.
+mi_gdb_test "-list-features" \
+            "\\^done,features=\\\[.*\"exec-run-start-option\".*\\\]" \
+            "-list-features includes \"exec-run-start-option\""
+
 mi_run_cmd "--start"
 mi_expect_stop "breakpoint-hit" "main" "" ".*mi-start.c" "$decimal" \
 { "" "disp=\"del\"" } "run to main"
-- 
1.8.1.2

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

[Eli Zaretskii]

> From: Joel Brobecker <brobecker@adacore.com>
> Date: Tue,  3 Dec 2013 10:21:10 +0400
> 
> While reviewing all the changes I made for GDB/MI, recently, and making
> sure that every new features should be check-able before use, I noticed
> that were were missing a way to test if --exec-run supports --start.
> 
> This adds "exec-run-start-option" in the output of the -list-features
> commands, allowing front-ends to easily determine whether -exec-run
> supports the --start option.
> 
> gdb/ChangeLog:
> 
>         * mi/mi-main.c (mi_cmd_list_features): add "exec-run-start-option".
>         * NEWS: Expand the entry documenting the new -exec-run --start
>         option to mention the corresponding new entry in the output of
>         "-list-features".
> 
> gdb/doc/ChangeLog:
> 
> 	* gdb.texinfo (GDB/MI Miscellaneous Commands): Document the new
> 	"exec-run-start-option" entry in the output of the "-list-features"
> 	command.
> 
> gdb/testsuite/ChangeLog:
> 
>         * gdb.mi/mi-start.exp: Add test verifying that -list-features
>         contains "exec-run-start-option".
> 
> Tested on x86_64-linux. Both code and doco parts are relatively
> straightforward, so I am planning on checking this in in a day or
> two, assuming doco approval.

You have my approval, with one comment: each one of the items in that
@table in gdb.texinfo should be indexed, to facilitate their
discoverability by readers.  E.g., for this item I'd suggest

 @findex exec-run-start-option
 @cindex support for @option{--start} option in @code{-exec-run}

I'd also add an index entry for the entire section

 @cindex supported @sc{gdb/mi} features, list

From the past couple of weeks, it sounds like this section will grow
very fast (so maybe it should become a full-fledged @node).

Thanks.

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

[Joel Brobecker]

> > gdb/ChangeLog:
> > 
> >         * mi/mi-main.c (mi_cmd_list_features): add "exec-run-start-option".
> >         * NEWS: Expand the entry documenting the new -exec-run --start
> >         option to mention the corresponding new entry in the output of
> >         "-list-features".
> > 
> > gdb/doc/ChangeLog:
> > 
> > 	* gdb.texinfo (GDB/MI Miscellaneous Commands): Document the new
> > 	"exec-run-start-option" entry in the output of the "-list-features"
> > 	command.
> > 
> > gdb/testsuite/ChangeLog:
> > 
> >         * gdb.mi/mi-start.exp: Add test verifying that -list-features
> >         contains "exec-run-start-option".
> > 
> > Tested on x86_64-linux. Both code and doco parts are relatively
> > straightforward, so I am planning on checking this in in a day or
> > two, assuming doco approval.
> 
> You have my approval, with one comment: each one of the items in that
> @table in gdb.texinfo should be indexed, to facilitate their
> discoverability by readers.  E.g., for this item I'd suggest
> 
>  @findex exec-run-start-option
>  @cindex support for @option{--start} option in @code{-exec-run}
> 
> I'd also add an index entry for the entire section
> 
>  @cindex supported @sc{gdb/mi} features, list
> 
> >From the past couple of weeks, it sounds like this section will grow
> very fast (so maybe it should become a full-fledged @node).

Thanks, Eli. I will prepare a followup patch as soon as this one
gets in. I don't see the section growing very fast, now that we have
-info-gdb-mi-commands, so it would be mostly for new switches. But
I do agree with all suggestions overall.

-- 
Joel

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

[Joel Brobecker]

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

Hello Eli,

> > gdb/doc/ChangeLog:
> > 
> > 	* gdb.texinfo (GDB/MI Miscellaneous Commands): Document the new
> > 	"exec-run-start-option" entry in the output of the "-list-features"
> > 	command.
[...]
> You have my approval, with one comment: each one of the items in that
> @table in gdb.texinfo should be indexed, to facilitate their
> discoverability by readers.  E.g., for this item I'd suggest
> 
>  @findex exec-run-start-option
>  @cindex support for @option{--start} option in @code{-exec-run}

I can add the @findex for each item in the list. However, can you
explain why the @cindex. ISTM that it might be better to cross-reference
this element from the part of the manual that documents the actual
feature? Otherwise, someone looking at the index on how to "start"
a program with GDB/MI might find this index entry, follow it, only
to find how to check for the feature, not how to use it. WDYT?

> I'd also add an index entry for the entire section
> 
>  @cindex supported @sc{gdb/mi} features, list

Attached is a patch that does that.

Incidentally, I've been meaning to talk about a small nit: Why are
we adding the anchors and indexing commands after the @section/node/etc?
When you click on the reference, the browser jumps to the text, but
because the anchor if after the section title, we're not seeing it.
For now, I've been consistent with the current practice...

> >From the past couple of weeks, it sounds like this section will grow
> very fast (so maybe it should become a full-fledged @node).

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.

gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI Miscellaneous Commands): Add @cindex
        entry for section docuumenting the -list-features GDB/MI command.

Thanks,
-- 
Joel

[-- Attachment #2: 0001-Add-cindex-for-section-documenting-the-list-features.patch --]
[-- Type: text/x-diff, Size: 906 bytes --]

From 1fd741c48e1466440fc0e2372c6484e292c2a54c Mon Sep 17 00:00:00 2001
From: Joel Brobecker <brobecker@adacore.com>
Date: Tue, 10 Dec 2013 12:51:38 +0100
Subject: [PATCH] Add @cindex for section documenting the -list-features GDB/MI
 command.

gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI Miscellaneous Commands): Add @cindex
        entry for section docuumenting the -list-features GDB/MI command.
---
 gdb/doc/gdb.texinfo | 1 +
 1 file changed, 1 insertion(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 7dfa9f6..d7c90f5 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -35208,6 +35208,7 @@ to the debugger:
 
 @subheading The @code{-list-features} Command
 @findex -list-features
+@cindex supported @sc{gdb/mi} features, list
 
 Returns a list of particular features of the MI protocol that
 this version of gdb implements.  A feature can be a command,
-- 
1.8.1.2

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

[Eli Zaretskii]

> Date: Tue, 10 Dec 2013 13:02:52 +0100
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> >  @findex exec-run-start-option
> >  @cindex support for @option{--start} option in @code{-exec-run}
> 
> I can add the @findex for each item in the list. However, can you
> explain why the @cindex. ISTM that it might be better to cross-reference
> this element from the part of the manual that documents the actual
> feature? Otherwise, someone looking at the index on how to "start"
> a program with GDB/MI might find this index entry, follow it, only
> to find how to check for the feature, not how to use it. WDYT?

We should do both, I think.

> > I'd also add an index entry for the entire section
> > 
> >  @cindex supported @sc{gdb/mi} features, list
> 
> Attached is a patch that does that.

Thanks.

> Incidentally, I've been meaning to talk about a small nit: Why are
> we adding the anchors and indexing commands after the @section/node/etc?
> When you click on the reference, the browser jumps to the text, but
> because the anchor if after the section title, we're not seeing it.

"It" being what? the section title or something else?  I'm afraid I
don't understand the problem.

> > >From the past couple of weeks, it sounds like this section will grow
> > very fast (so maybe it should become a full-fledged @node).
> 
> 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.

Thanks.

pushed: Add @cindex for section documenting the -list-features GDB/MI command. (was: "[RFA/commit+doco] GDB/MI: Document support for -exec-run --start in -list-features")

[Joel Brobecker]

> > Attached is a patch that does that.
> 
> Thanks.

Just for the record, this patch has now been pushed.

gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI Miscellaneous Commands): Add @cindex
        entry for section docuumenting the -list-features GDB/MI command.

I am now working on moving some of the comments to their own node.

-- 
Joel

Re: pushed: Add @cindex for section documenting the -list-features GDB/MI command. (was: "[RFA/commit+doco] GDB/MI: Document support for -exec-run --start in -list-features")

[Eli Zaretskii]

> Date: Thu, 12 Dec 2013 17:02:30 +0100
> From: Joel Brobecker <brobecker@adacore.com>
> 
> Just for the record, this patch has now been pushed.
> 
> gdb/doc/ChangeLog:
> 
>         * gdb.texinfo (GDB/MI Miscellaneous Commands): Add @cindex
>         entry for section docuumenting the -list-features GDB/MI command.
> 
> I am now working on moving some of the comments to their own node.

Thanks.

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

[Joel Brobecker]

> > > >From the past couple of weeks, it sounds like this section will grow
> > > very fast (so maybe it should become a full-fledged @node).
> > 
> > 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?

Thanks,
-- 
Joel

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

[Joel Brobecker]

[-- 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

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

[Eli Zaretskii]

> Date: Fri, 13 Dec 2013 16:51:24 +0100
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> > > > 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!

Yes, you did.  This is OK to go in.  Thanks.

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

[Joel Brobecker]

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

> > > 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

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

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

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

[Joel Brobecker]

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

Next step in the patch series is to add @findex'es for each
item in the -list-features table. This one was purely mechanical...

gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI Support Commands): Add @findex entries
        for each @item in the table describing the list of features.
        Add empty line between each @item.

OK to commit?

Thank you,
-- 
Joel

[-- Attachment #2: 0001-Add-findex-for-each-item-of-list-features.patch --]
[-- Type: text/x-diff, Size: 2936 bytes --]

From 48758b378554b9b148c86ff94c8d0f5a0bff054b Mon Sep 17 00:00:00 2001
From: Joel Brobecker <brobecker@adacore.com>
Date: Mon, 23 Dec 2013 05:33:59 +0400
Subject: [PATCH] Add @findex for each @item of -list-features

This is to make it easier to discover the various options displayed
by the -list-features command.

It also adds an empty line between each @item of the table, for
added clarity.  Otherwise, it is becoming harder to visually
separate each entry, and thus edit that part of the file.

gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI Support Commands): Add @findex entries
        for each @item in the table describing the list of features.
        Add empty line between each @item.
---
 gdb/doc/gdb.texinfo | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 29f1cfc..6b8241d 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -35115,39 +35115,62 @@ Example output:
 The current list of features is:
 
 @table @samp
+
 @item frozen-varobjs
+@findex frozen-varobjs
 Indicates support for the @code{-var-set-frozen} command, as well
 as possible presense of the @code{frozen} field in the output
 of @code{-varobj-create}.
+
 @item pending-breakpoints
+@findex pending-breakpoints
 Indicates support for the @option{-f} option to the @code{-break-insert}
 command.
+
 @item python
+@findex python
 Indicates Python scripting support, Python-based
 pretty-printing commands, and possible presence of the
 @samp{display_hint} field in the output of @code{-var-list-children}
+
 @item thread-info
+@findex thread-info
 Indicates support for the @code{-thread-info} command.
+
 @item data-read-memory-bytes
+@findex data-read-memory-bytes
 Indicates support for the @code{-data-read-memory-bytes} and the
 @code{-data-write-memory-bytes} commands.
+
 @item breakpoint-notifications
+@findex breakpoint-notifications
 Indicates that changes to breakpoints and breakpoints created via the
 CLI will be announced via async records.
+
 @item ada-task-info
+@findex ada-task-info
 Indicates support for the @code{-ada-task-info} command.
+
 @item language-option
+@findex language-option
 Indicates that all @sc{gdb/mi} commands accept the @option{--language}
 option (@pxref{Context management}).
+
 @item info-gdb-mi-command
+@findex info-gdb-mi-command
 Indicates support for the @code{-info-gdb-mi-command} command.
+
 @item undefined-command-error-code
+@findex undefined-command-error-code
 Indicates support for the "undefined-command" error code in error result
 records, produced when trying to execute an undefined @sc{gdb/mi} command
 (@pxref{GDB/MI Result Records}).
+
 @item exec-run-start-option
+@findex exec-run-start-option
 Indicates that the @code{-exec-run} command supports the @option{--start}
 option (@pxref{GDB/MI Program Execution}).
+
 @end table
 
 @subheading The @code{-list-target-features} Command
-- 
1.8.3.2

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

[Eli Zaretskii]

> Date: Mon, 23 Dec 2013 05:40:15 +0400
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> Next step in the patch series is to add @findex'es for each
> item in the -list-features table. This one was purely mechanical...
> 
> gdb/doc/ChangeLog:
> 
>         * gdb.texinfo (GDB/MI Support Commands): Add @findex entries
>         for each @item in the table describing the list of features.
>         Add empty line between each @item.
> 
> OK to commit?

It is OK, but the same effect for a much smaller effort would be
achieved by replacing @table with @ftable.  Thgen each @item
automatically gets inserted into the function index.

Thanks.

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

[Joel Brobecker]

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

> > gdb/doc/ChangeLog:
> > 
> >         * gdb.texinfo (GDB/MI Support Commands): Add @findex entries
> >         for each @item in the table describing the list of features.
> >         Add empty line between each @item.
> > 
> > OK to commit?
> 
> It is OK, but the same effect for a much smaller effort would be
> achieved by replacing @table with @ftable.  Thgen each @item
> automatically gets inserted into the function index.

I didn't know that, thanks! Here is a new patch...

gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI Support Commands): Change @table into
        @ftable.

-- 
Joel

[-- Attachment #2: 0001-Turn-list-feature-table-into-ftable.patch --]
[-- Type: text/x-diff, Size: 1268 bytes --]

From 86e54f9d0fa850ad464be97defd082a0224bd61b Mon Sep 17 00:00:00 2001
From: Joel Brobecker <brobecker@adacore.com>
Date: Mon, 23 Dec 2013 05:33:59 +0400
Subject: [PATCH] Turn -list-feature @table into @ftable.

This is to make it easier to discover the various options displayed
by the -list-features command.

gdb/doc/ChangeLog:

        * gdb.texinfo (GDB/MI Support Commands): Change @table into
        @ftable.
---
 gdb/doc/gdb.texinfo | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 29f1cfc..8814cd0 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -35114,7 +35114,7 @@ Example output:
 
 The current list of features is:
 
-@table @samp
+@ftable @samp
 @item frozen-varobjs
 Indicates support for the @code{-var-set-frozen} command, as well
 as possible presense of the @code{frozen} field in the output
@@ -35148,7 +35148,7 @@ records, produced when trying to execute an undefined @sc{gdb/mi} command
 @item exec-run-start-option
 Indicates that the @code{-exec-run} command supports the @option{--start}
 option (@pxref{GDB/MI Program Execution}).
-@end table
+@end ftable
 
 @subheading The @code{-list-target-features} Command
 @findex -list-target-features
-- 
1.8.3.2

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

[Eli Zaretskii]

> Date: Mon, 23 Dec 2013 08:28:41 +0400
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> > > gdb/doc/ChangeLog:
> > > 
> > >         * gdb.texinfo (GDB/MI Support Commands): Add @findex entries
> > >         for each @item in the table describing the list of features.
> > >         Add empty line between each @item.
> > > 
> > > OK to commit?
> > 
> > It is OK, but the same effect for a much smaller effort would be
> > achieved by replacing @table with @ftable.  Thgen each @item
> > automatically gets inserted into the function index.
> 
> I didn't know that, thanks! Here is a new patch...

Obviously correct, thanks.

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

[Joel Brobecker]

> > > > gdb/doc/ChangeLog:
> > > > 
> > > >         * gdb.texinfo (GDB/MI Support Commands): Add @findex entries
> > > >         for each @item in the table describing the list of features.
> > > >         Add empty line between each @item.
> > > > 
> > > > OK to commit?
> > > 
> > > It is OK, but the same effect for a much smaller effort would be
> > > achieved by replacing @table with @ftable.  Thgen each @item
> > > automatically gets inserted into the function index.
> > 
> > I didn't know that, thanks! Here is a new patch...
> 
> Obviously correct, thanks.

Thank you, Eli. The patch has been pushed!

-- 
Joel

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

[Joel Brobecker]

> gdb/ChangeLog:
> 
>         * mi/mi-main.c (mi_cmd_list_features): add "exec-run-start-option".
>         * NEWS: Expand the entry documenting the new -exec-run --start
>         option to mention the corresponding new entry in the output of
>         "-list-features".
> 
> gdb/doc/ChangeLog:
> 
> 	* gdb.texinfo (GDB/MI Miscellaneous Commands): Document the new
> 	"exec-run-start-option" entry in the output of the "-list-features"
> 	command.
> 
> gdb/testsuite/ChangeLog:
> 
>         * gdb.mi/mi-start.exp: Add test verifying that -list-features
>         contains "exec-run-start-option".

FYI, I pushed this patch. I will be working on Eli's suggestion for
more indexing next.

-- 
Joel