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