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

Andrew Cagney
2001-07-06T15:20:00Z

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