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

Eli Zaretskii
2018-05-06T19:40:07Z

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