Re: Formatting of packet descriptions in GDB manual

Eli Zaretskii
2005-11-16T07:11:30Z

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