This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: Formatting of packet descriptions in GDB manual
- From: Eli Zaretskii <eliz at gnu dot org>
- To: Jim Blandy <jimb at red-bean dot com>
- Cc: gdb-patches at sources dot redhat dot com
- Date: Wed, 16 Nov 2005 09:11:23 +0200
- Subject: Re: Formatting of packet descriptions in GDB manual
- References: <8f2776cb0511111624h4d646cd9i1f86824c5edc613f@mail.gmail.com> <ubr0q2vl9.fsf@gnu.org> <8f2776cb0511120047y50b3a273pe17ddd5c53342be1@mail.gmail.com> <u4q6h32bk.fsf@gnu.org> <20051113171247.GA1945@nevyn.them.org> <ur79ki4h7.fsf@gnu.org> <20051114022955.GA10567@nevyn.them.org> <uoe4nj1ih.fsf@gnu.org> <20051114134924.GB21373@nevyn.them.org> <8f2776cb0511152147i4c24e43aue46a54332fd4c0f3@mail.gmail.com> <8f2776cb0511152152p85abe3pa7ad547043c53c0a@mail.gmail.com>
- Reply-to: 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!