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