Re: [RFA/doco] Document set/show print array-indexes

[Joel Brobecker <brobecker@adacore.com>]

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

> Thanks.  See my comments below.

Thanks for the quick review (as usual!).

> > Tested by building the HTML documentation and checking the result.
> 
> It is also advisable to build the Info version and at least make sure
> there are no error messages from makeinfo.

OK, I also did a "make info", just to double-check, no error as well.

> > +@item set print array-indexes
> > +@itemx set print array-indexes on
> > +@cindex print array indexes
> 
> Please add here a @kindex entry for this command.  All commands are
> indexed via @kindex in the GDB manual.

Done. Note that the other commands in the same section as also lacking
this @kindex. I can add it for you if you like (separate patch, though).

BTW: I followed the example of previously written entries, but I think
it might make sense to move the @cindex and @kindex entries just before
the @item. When I clicked on the link in the index, my browser showed
jumped to the text, but the actual command was "hidden" (the browser
scrolle a few lines too much). And when you look at the HTML generated,
it makes sense:

    <DT><CODE>set print array-indexes</CODE>
    <DD><DT><CODE>set print array-indexes on</CODE>
    
    <DD><A NAME="IDX388"></A>
    <A NAME="IDX389"></A>
    Print the index of each element when displaying arrays.  May be more
    convenient to locate a given element in the array or quickly find the
    index of a given element in that printed array.  The default is off.
    <P>

I think the NAME tag should be just before the two <CODE> sections.
What do you think?

> Also, I think the @cindex entry should use "indices", because that's
> the right spelling.  (Maybe we should change the command to "set array
> index" in singular, to avoid this issue.)

Actually, I disagree. I checked in a dictionary as well as with a friend
of mine who is a native speaker (who will be an English teacher in his
next life). The two spellings are actually correct, and certain
dictionaries attribute a different meaning to each spelling while others
say it's the same.

            * an ordered list, plural indexes
            * a number or variable, plural indices.

If you follow the above definition, then I think you'll say the TSX
indices (sorry for this Cannuck-ism :), while to me indexes will work
for the plural of a book index. Similarly, to me, the index in an array
is not just a number, but a key to the element it refers to, hence indexes.

All this nit-picking put apart though (I just like learning about words),
common usage no longer dissociates between the two, so both should be fine.
I don't have any problem changing "indexes" to "index", though, if others
agree.

> > +index of a given element in that printed array. The default is off.
>                                                  ^^^
> Need 2 blanks here.

Good catch. Fixed! I also just caught a small copy/paste error in the
"show" command. Fixed as well.

2005-09-26  Joel Brobecker  <brobecker@adacore.com>

        * gdb.texinfo (Print Settings): Add documentation for set/show
        print array-indexes.

Tested by building the HTML documentation and checking the result.
Info documentation also built without any error.

-- 
Joel

[-- Attachment #2: gdbdoc.diff --]
[-- Type: text/plain, Size: 1112 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.279
diff -u -p -r1.279 gdb.texinfo
--- gdb.texinfo	18 Sep 2005 03:28:18 -0000	1.279
+++ gdb.texinfo	27 Sep 2005 04:04:41 -0000
@@ -5692,6 +5692,21 @@ Return to compressed format for arrays.
 Show whether compressed or pretty format is selected for displaying
 arrays.
 
+@item set print array-indexes
+@itemx set print array-indexes on
+@cindex print array indexes
+@kindex set print array-indexes
+Print the index of each element when displaying arrays.  May be more
+convenient to locate a given element in the array or quickly find the
+index of a given element in that printed array.  The default is off.
+
+@item set print array-indexes off
+Stop printing element indexes when displaying arrays.
+
+@item show print array-indexes
+Show whether the index of each element is printed when displaying
+arrays.
+
 @item set print elements @var{number-of-elements}
 @cindex number of array elements to print
 @cindex limit on number of printed array elements