Re: Formatting of packet descriptions in GDB manual

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of packet descriptions in GDB manual

jimb (Bugzilla)
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.

gdb/doc/ChangeLog:
2005-11-15  Jim Blandy  <[hidden email]>

        * gdb.texinfo (Packets): Use @code for packet contents.  Drop
        summaries from packet @item lines; the same information appears
        immediately below in the description.  Delete paragraph breaks
        after packet @item commands, so that the description appears
        directly to the right of the packet prototype in the printed
        manual, if it fits.  Place spaces in packet prototypes between
        @vars and non-@var letters, and explain that they're just for
        formatting.  Use @dots{} instead of '...'.

jimb.gdb-doc-remote-protocol-formatting.patch (41K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of packet descriptions in GDB manual

Eli Zaretskii
> Date: Tue, 15 Nov 2005 21:52:06 -0800
> From: Jim Blandy <[hidden email]>
>
> 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!
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of packet descriptions in GDB manual

jimb (Bugzilla)
Okay --- here's what I've committed.

gdb/doc/ChangeLog:
2005-11-16  Jim Blandy  <[hidden email]>

        * gdb.texinfo (Packets, Stop Reply Packets)
        (General Query Packets): Various formatting cleanups.
        - Use @samp for packet contents.
        - Drop summaries from packet @item lines; the same information appears
          immediately below in the description.
        - Delete paragraph breaks after packet @item commands, so that the
          description appears directly to the right of the packet prototype
          in the printed manual, if it fits.
        - Place spaces in packet prototypes between @vars and non-@var
          letters, and explain that they're just for formatting.
        - Use @dots{} instead of '...'.
        - Fix uses of @code where @var was needed.
        - Replace "deprecated" markers with English text spelling out the
          packet's status and the preferred alternatives.
        - Remove "(reserved)" markers on 'A' and 'I' packets; it's unclear
          what this ever meant.
        - Remove "(draft)" markers on 'i' packets; nobody has commented on
          this for a long time.
        - Remove "(draft)" markers on 'z' and 'Z' packets; these have been
          implemented several times, and have been in use for years.

jimb.gdb-doc-remote-protocol-formatting.patch (60K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of packet descriptions in GDB manual

Nathan J. Williams
Jim Blandy <[hidden email]> writes:

> - Remove "(reserved)" markers on 'A' and 'I' packets; it's unclear
>  what this ever meant.

> - Remove "(draft)" markers on 'i' packets; nobody has commented on
>  this for a long time.

Has anyone ever implemented "i" or "I"?

        - Nathan
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of packet descriptions in GDB manual

Eli Zaretskii
In reply to this post by jimb (Bugzilla)
> Date: Wed, 16 Nov 2005 02:35:22 -0800
> From: Jim Blandy <[hidden email]>
> Cc: [hidden email]
>
> Okay --- here's what I've committed.

Thanks.
Reply | Threaded
Open this post in threaded view
|

Re: Formatting of packet descriptions in GDB manual

Daniel Jacobowitz-2
In reply to this post by Nathan J. Williams
On Wed, Nov 16, 2005 at 12:31:44PM -0500, Nathan J. Williams wrote:
> Jim Blandy <[hidden email]> writes:
>
> > - Remove "(reserved)" markers on 'A' and 'I' packets; it's unclear
> >  what this ever meant.
>
> > - Remove "(draft)" markers on 'i' packets; nobody has commented on
> >  this for a long time.
>
> Has anyone ever implemented "i" or "I"?

Not as far as I know.

--
Daniel Jacobowitz
CodeSourcery, LLC