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

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

[Joel Brobecker]

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

This is the documentation for a new set/show command and their effect.
This is currently being reviewed under:

        http://sources.redhat.com/ml/gdb-patches/2005-09/msg00195.html

The interface has been agreed on, so we can proceed with the doc update
while the implementation details are being worked-out.

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.

-- 
Joel

[-- Attachment #2: gdbdoc.diff --]
[-- Type: text/plain, Size: 1070 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	26 Sep 2005 23:07:46 -0000
@@ -5692,6 +5692,20 @@ 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
+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
+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

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

[Eli Zaretskii]

> Date: Mon, 26 Sep 2005 16:08:06 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> 
> This is the documentation for a new set/show command and their effect.

Thanks.  See my comments below.

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

> +@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.

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

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

Other than that, fine.

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

[Joel Brobecker]

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

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

[Eli Zaretskii]

> Date: Mon, 26 Sep 2005 21:09:35 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sources.redhat.com
> 
> OK, I also did a "make info", just to double-check, no error as well.

Thanks.

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

Sorry, I should have checked my memory before asking for a @kindex.  I
now recall that I decided to have only one @kindex entry for all of
the "set print ..." family, and such an entry is already near the
beginning of this section.

So please don't add a @kindex entry for this new command.  Sorry for
the trouble.

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

Yes, you are right.

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

Fine with me, after you remove the extra @kindex.

Thanks.

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

[Joel Brobecker]

> > 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.
> 
> Fine with me, after you remove the extra @kindex.

OK, patch checked in, with the kindex removed.

Thanks,
-- 
Joel