Re: [RFC 4/5] Documentation changes for 'frame apply' and 'thread apply'

[Eli Zaretskii <eliz at gnu dot org>]

> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Sat,  5 May 2018 21:28:03 +0200
> 
> +@table @asis

Since all the @item's in this table use @code, it is better to say

  @table @code

> +@item Flags @code{c} and @code{s} : error handling when applying @var{command}.

This is not a good way of formatting a table.  I suggest to use this
instead:

 By default, @value{GDBN} displays some thread information before the
 output produced by @var{command}, and an error raised during the
 execution of a @var{command} will abort @code{thread apply}.  The
 following flags can be used to fine-tune this behavior:

 @table @code
 @item c
 The flag @code{c}, which stands for @samp{continue}, causes any
 errors in @var{command} to be displayed, and the execution of
 @vode{thread apply} then continues.
 @item s
 The flag @code{s}, which stands for @samp{silent}, causes any errors
 or empty output produced by a @var{command} to be silently ignored.
 That is, the execution continues, but the errors are not printed.
 @item v
 The flag @code{v} increases the verbosity of the info displayed for
 each thread.
 @item q
 The flag @code{q} (@samp{quiet}) decreases the verbosity.
 @end @table

 Flags @code{c} and @code{s} cannot be used together.

 The default value of verbosity, 1, prints the per-inferior thread
 number and the target system's thread ID.  Under verbosity 0, no
 thread info is printed.

> +@item tfaas @var{command}
> +Shortcut for @code{thread apply all -s frame apply all -s @var{COMMAND}}.

Any reason why -s should be specified twice?

> +The @var{flags} control what output to produce and how to handle
> +errors raised when applying @var{command} to a frame.  @var{flags}
> +must start with a @code{-} directly followed by one or more letters in
> +@code{vqcs}.

I suggest to use here the same paradigm as shown above for "thread
apply".

> +Some frame information is printed before the output or error produced
> +by applying @var{command} to a frame.  The printed frame information
> +@footnote{Note that the way the frame information is printed can be changed
> +using the @code{set backtrace} settings such as @code{set
> +filename-display}. @ref{Backtrace,,Backtraces}}

Please use @xref here, and leave 2 spaces between sentences.  (And I'm
not sure it's a good idea to have cross-references in footnotes.  Did
you make sure this produces reasonable results in the printed manual?)

> +Note that the command @code{tfaas @var{command}} applies @var{command}
> +on all frames of all threads. @ref{Threads,,Threads}

Ditto.

Thanks.