Re: Formatting of packet descriptions in GDB manual

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Tue, 15 Nov 2005 21:52:06 -0800
> From: Jim Blandy <jimb@red-bean.com>
> 
> Here's a patch that implements the formatting changes to the
> description of the remote protocol packets we've been discussing on
> gdb@.
> 
> This uses @code for the packet templates, even though in my last
> message there I said I thought @samp was more appropriate; @code is
> what I've got right now, and I didn't want to go and change everything
> twice if the conclusion was that @code was better.  But you can see
> what was done.

Thanks.  This is fine, but while at that, let's fix a few more minor
problems in the original text:

> ! @item b @var{baud}
>   @cindex @code{b} packet
> ! @strong{(deprecated)}
>   Change the serial line speed to @var{baud}.

I have a problem with this "(deprecated)" thing.  Can we simply add a
sentence saying this is deprecated in favor of whatever substitutions
we want people to use instead?

> ! @item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]}
>   @anchor{cycle step packet}
>   @cindex @code{i} packet
> ! @strong{(draft)}
>   Step the remote target by a single clock cycle.  If @code{,}@var{nnn} is
>   present, cycle step @var{nnn} cycles.  If @var{addr} is present, cycle
>   step starting at that address.

Similarly here for "(draft)", but in this case I don't even understand
the implications of this packet being ``draft''.  Can we spell them
out in plain English?

(There are more "(deprecated)" and "(draft)" in that section.)

Several places use two or more @item's in consecutive lines, then
describe them both.  This is incorrect Texinfo: all but the first
@item should be @itemx.

> ! The @code{C}, @code{c}, @code{S}, @code{s} and @code{?} packets can
> ! receive any of the below as a reply.  In the case of the @code{C},
> ! @code{c}, @code{S} and @code{s} packets, that reply is only returned
> ! when the target halts.  In the below the exact meaning of ``signal
> ! number'' is poorly defined.

This ``signal number'' will look better in print and PDF if we use
@dfn{signal number}.

>   @var{AA} = two hex digit signal number; @var{n...} = register number
>   (hex), @var{r...}  = target byte ordered register contents, size defined
> ! by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @code{thread},
>   @var{r...} = thread process ID, this is a hex integer; @var{n...} =
> ! (@code{watch} | @code{rwatch} | @code{awatch}, @var{r...} = data
>   address, this is a hex integer; @var{n...} = other string not starting
>   with valid hex digit.  @value{GDBN} should ignore this @var{n...},
>   @var{r...} pair and go on to the next.  This way we can extend the

I think this paragraph will read better if we replace the equals signs
with ``is'' or ``are'', as appropriate, or with some other English
construct.

Otherwise, this can go in, after you replace @code with @samp in the
@table lines, per your other message.

Thanks!