[patch] Add col_name to ui_out_table_header()

[patch] Add col_name to ui_out_table_header()

[Andrew Cagney]

Hello,

This patch adds a ``col_name'' argument to the ui_out_table_header() 
call.  This lets MI include the col_name/field_name in both the table 
header and table body.

	Andrew
From ac131313@cygnus.com Thu Jun 21 09:12:00 2001
From: Andrew Cagney <ac131313@cygnus.com>
To: gdb-patches@sources.redhat.com
Subject: [patch/mi] Output ``[]'' when a list but
Date: Thu, 21 Jun 2001 09:12:00 -0000
Message-id: <3B321CF9.5080708@cygnus.com>
X-SW-Source: 2001-06/msg00361.html
Content-length: 192

Hello,

This tweek updates mi-out so that, when MI_VERSION > 0, ``[]'' instead 
of ``{}'' is used on lists.  Since nothing currently uses the list calls 
none of the output changes.

	Andrew

Re: [patch] Add col_name to ui_out_table_header()

[Eli Zaretskii]

> Date: Thu, 21 Jun 2001 11:37:12 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> This patch adds a ``col_name'' argument to the ui_out_table_header() 
> call.

This needs to be accompanied by a suitable change to gdbint.texinfo,
since ui_out_table_header is documented there.

[rfa/doc] Update ui-out; Was: [patch] Add col_name to ui_out_table_header()

[Andrew Cagney]

> Date: Thu, 21 Jun 2001 11:37:12 -0400
>> From: Andrew Cagney <ac131313@cygnus.com>
>> 
>> This patch adds a ``col_name'' argument to the ui_out_table_header() 
>> call.
> 
> 
> This needs to be accompanied by a suitable change to gdbint.texinfo,
> since ui_out_table_header is documented there.


Attached.

	Andrew

Re: [rfa/doc] Update ui-out; Was: [patch] Add col_name to ui_out_table_header()

[Eli Zaretskii]

On Wed, 4 Jul 2001, Andrew Cagney wrote:

> > Date: Thu, 21 Jun 2001 11:37:12 -0400
> >> From: Andrew Cagney <ac131313@cygnus.com>
> >> 
> >> This patch adds a ``col_name'' argument to the ui_out_table_header() 
> >> call.
> > 
> > 
> > This needs to be accompanied by a suitable change to gdbint.texinfo,
> > since ui_out_table_header is documented there.
> 
> Attached.

Thanks.  I have a few comments:

> ! @subsection Table, Tuple and List Functions
>   
>   @cindex list output functions
>   @cindex table output functions
> ! This section introduces @code{ui_out} routines for building lists,
> ! tuples and tables.  The routines to output the actual data items
> ! (fields) are presented in the next section.

Please add here a @cindex entry about "tuple output functions".

> ! To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
> ! containing information about an object; A @dfn{list} is a sequence of

This "A" after a semi-colon should be a lower-case "a".

> ! @code{ui_out_table_end}.  The tuples are produce by calling

"The tuples are produced"

Btw, I don't understand why did you consistently change active into
passive tense.  Compare the old text:

                                    You produce the lists by calling
  @code{ui_out_list_begin} and @code{ui_out_list_end}, with suitable
  calls to functions which actually output fields between them.

with the new:

                                    The tuples are produced by calling
  @code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable
  calls to functions which actually output fields between them.

English is not my first language (not even the second, actually), but
I know RMS always corrects my passive-tense sentences.

> ! @deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{lstid})
> ! This function marks the beginning of a tuple output.  @var{lstid} points
> ! to an optional string that identifies the list; it is copied by the
                                              ^^^^
Shouldn't this say "tuple" rather than "list"?

> ! @deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})
> ! This function signals an end of a list output.  There should be exactly
                                      ^^^^
Same here.

> ! @deftypefun struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
> ! This function opens a tuple and then installs a cleanup to close that
> ! same tuple.

I think we should explain here what does "installs a cleanup to close
that same tuple" mean, and why this function is useful.  A
cross-reference to the Cleanups section would also help (but it cannot
be enough to explain why this function was introduced, since the
Cleanups section is very short and doesn't really explain the purpose
of cleanups in a clear manner.)

> + @deftypefun struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
> + This function opens a list and then installs a cleanup to close that same
> + list.
> + @end deftypefun

Same here.

Re: [rfa/doc] Update ui-out; Was: [patch] Add col_name to ui_out_table_header()

[Andrew Cagney]

> English is not my first language (not even the second, actually), but
> I know RMS always corrects my passive-tense sentences.


So FSF documents should be written as second person present tense 
(correct name?).  I never know and use third person past tense as a 
matter of habbit.

	Andrew

Re: [rfa/doc] Update ui-out; Was: [patch] Add col_name to ui_out_table_header()

[Eli Zaretskii]

> Date: Thu, 05 Jul 2001 22:19:26 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> > English is not my first language (not even the second, actually), but
> > I know RMS always corrects my passive-tense sentences.
> 
> So FSF documents should be written as second person present tense 
> (correct name?).

I don't know if that's something in the GNU standards.  I understand
that it's simply considered to be a good English style: it's better to
say "you do this and that" instead of "this and that is done".

Re: [rfa/doc] Update ui-out; Was: [patch] Add col_name to ui_out_table_header()

[Andrew Cagney]

Eli,

I think I got all of these.  Keep an eye out for the @pxref{} and 
@footnote{}.

	Andrew

> ! @subsection Table, Tuple and List Functions
>> > @cindex list output functions
>> @cindex table output functions
>> ! This section introduces @code{ui_out} routines for building lists,
>> ! tuples and tables.  The routines to output the actual data items
>> ! (fields) are presented in the next section.
> 
> 
> Please add here a @cindex entry about "tuple output functions".
> 
> 
>> ! To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
>> ! containing information about an object; A @dfn{list} is a sequence of
> 
> 
> This "A" after a semi-colon should be a lower-case "a".
> 
> 
>> ! @code{ui_out_table_end}.  The tuples are produce by calling
> 
> 
> "The tuples are produced"
> 
> Btw, I don't understand why did you consistently change active into
> passive tense.  Compare the old text:
> 
>                                     You produce the lists by calling
>   @code{ui_out_list_begin} and @code{ui_out_list_end}, with suitable
>   calls to functions which actually output fields between them.
> 
> with the new:
> 
>                                     The tuples are produced by calling
>   @code{ui_out_tuple_begin} and @code{ui_out_tuple_end}, with suitable
>   calls to functions which actually output fields between them.
> 
> English is not my first language (not even the second, actually), but
> I know RMS always corrects my passive-tense sentences.
> 
> 
>> ! @deftypefun void ui_out_tuple_begin (struct ui_out *@var{uiout}, const char *@var{lstid})
>> ! This function marks the beginning of a tuple output.  @var{lstid} points
>> ! to an optional string that identifies the list; it is copied by the
> 
> ^^^^
> Shouldn't this say "tuple" rather than "list"?
> 
> 
>> ! @deftypefun void ui_out_tuple_end (struct ui_out *@var{uiout})
>> ! This function signals an end of a list output.  There should be exactly
> 
> ^^^^
> Same here.
> 
> 
>> ! @deftypefun struct cleanup *make_cleanup_ui_out_tuple_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
>> ! This function opens a tuple and then installs a cleanup to close that
>> ! same tuple.
> 
> 
> I think we should explain here what does "installs a cleanup to close
> that same tuple" mean, and why this function is useful.  A
> cross-reference to the Cleanups section would also help (but it cannot
> be enough to explain why this function was introduced, since the
> Cleanups section is very short and doesn't really explain the purpose
> of cleanups in a clear manner.)
> 
> 
>> + @deftypefun struct cleanup *make_cleanup_ui_out_list_begin_end (struct ui_out *@var{uiout}, const char *@var{id})
>> + This function opens a list and then installs a cleanup to close that same
>> + list.
>> + @end deftypefun
> 
> 
> Same here.
> 
> 

Re: [rfa/doc] Update ui-out; Was: [patch] Add col_name to ui_out_table_header()

[Eli Zaretskii]

> Date: Fri, 06 Jul 2001 18:20:18 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> I think I got all of these.  Keep an eye out for the @pxref{} and 
> @footnote{}.

I did.  Here's a couple of minor comments.

> ! Most @code{ui_out} routines are of type @code{void}, The exceptions are

"The" should be "the".

> ! To recap: A @dfn{tuple} is a sequence of @dfn{fields}, each field
> ! containing information about an object; a @dfn{list} is a sequence of
> ! @dfn{fields} where each field describes an identical object.

The second "fields" should not be inside a @dfn, since we already have
one here.

> ! and correct implementation of the non-portable @footnote{The function
> ! cast is not portable ISO-C.} code sequence:

@footnote should immediately follow the letter after which you want
the footnote marker in the printed version, because otherwise TeX will
keep the blank between the footnote and the preceding text.  So:

  and correct implementation of the non-portable@footnote{The function

Re: [rfa/doc] Update ui-out; Was: [patch] Add col_name to ui_out_table_header()

[Andrew Cagney]

> "The" should be "the".


Fixed.


> The second "fields" should not be inside a @dfn, since we already have
> one here.


Doh! I should have known about that one.


> @footnote should immediately follow the letter


Ah!

I've checked in the attached.  Let me know what I still need to tweek.

	Andrew

Re: [rfa/doc] Update ui-out; Was: [patch] Add col_name to ui_out_table_header()

[Eli Zaretskii]

> Date: Sat, 07 Jul 2001 12:15:43 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> I've checked in the attached.  Let me know what I still need to tweek.

No, it's fine now.