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

[Eli Zaretskii <eliz at is dot elta dot co dot il>]

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.