Re: [patch/rfa:doco] Reformat ``Remote Protocol'' appendix

["Eli Zaretskii" <eliz at is dot elta dot co dot il>]

> Date: Sun, 04 Aug 2002 13:29:56 -0400
> From: Andrew Cagney <ac131313@ges.redhat.com>
> 
> This patch re-formats the ``Remote Protocol'' section.  It replaces the 
> @multitable with a more normal @table (and gets rid of all those hfull 
> problems).

Thanks!

Sorry for the long delay.  Here are my comments:

> Fields within the packet should be separated using @samp{,} @samp{;} or
> @samp{:}.  Except where otherwise noted all numbers are represented in
> HEX with leading zeros suppressed.

Suggest an index entry here about the separators.

> Reply:
> @xref{Stop Reply Packets}.

This @xref (and others similar to it) should probably be written as

  @xref{Stop Reply Packets}, for the reply specifications.

> @item @code{a} --- reserved
> 
> Reserved for future use

A period is missing after the last sentence.

> Initialized @samp{argv[]} array passed into program. @var{arglen}
> specifies the number of bytes in the hex encoded byte stream @var{arg}.
> See @file{gdbserver} for more details.

What is this file `gdbserver' to which we refer the reader here?  Is
that the gdbserver binary?

> @var{addr} is address to resume. If @var{addr} is omitted, resume at
> current address.

Please make sure that there are 2 blanks after a period that ends a
sentence, here and elsewhere.

> @item @code{e} --- reserved
> 
> Reserved for future use

Missing period (there are more like this one).

> For a description of the @var{XX@dots{}} data, @xref{read registers
> packet}.

Please use "see @ref" instead of @xref.  The latter produces a
capitalized "See", which is wrong in the middle of a sentence.

> @item @code{H}@var{c}@var{t@dots{}} --- set thread 
> 
> Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
> @samp{G}, et.al.).  @var{c} = @samp{c} for thread used in step and
> continue; @var{t@dots{}} can be -1 for all threads.  @var{c} = @samp{g} for
> thread used in other operations.  If zero, pick a thread, any thread.

I think this text is better here:

    @item @code{H}@var{c}@var{t@dots{}} --- set thread 

    Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g},
    @samp{G}, et.al.).  @var{c} depends on the operation to be performed:
    it should be @samp{c} for step and continue operations, @samp{g} for
    other operations.  The thread designator @var{t@dots{}} may be -1,
    meaning all the threads, a thread number, or zero which means pick any
    thread.

> For a discussing of naming conventions, @xref{general query packet}.

This should use "see @ref" or @pxref in parens instead of @xref.

> @var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
> breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
> @samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
> bytes.  For a software breakpoint, @var{length} specifies the size of

Please use "---" instead of just "-".  The latter is typeset by TeX
as a minus, not as a dash.

> @node Stop Reply Packets
> @section Stop Reply Packets

A @cindex entry here is probably a good idea.

> The process exited, and @var{AA} is the exit status.  This is only
> applicable for certains sorts of targets.

The trailing `s' in "certains" is a typo.

> @var{AA} = signal number; @var{t@dots{}} = address of symbol "_start";

Please use @code_start} instead of "_start".

> @var{d@dots{}} = base of data section; @var{b@dots{}} = base of bss section.
> @emph{Note: only used by Cisco Systems targets.  The difference between
> this reply and the "qOffsets" query is that the 'N' packet may arrive
> spontaneously whereas the 'qOffsets' is a query initiated by the host
> debugger.}

Please use @samp{N} instead of 'N'.

> @var{XX@dots{}} is hex encoding of @sc{ascii} data.  This can happen at any
> time while the program is running and the debugger should continue to
> wait for 'W', 'T', etc.

Same here.

> In response to each query, the target will reply with a list of one or
> more thread ids, in big-endian hex, separated by commas.  GDB will

"GDB" should be @value{GDBN}.

> @item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info
> 
> Where @var{<id>} is a thread-id in big-endian hex.  Obtain a printable

There's no need in <> around "id".

> in @value{GDBN}'s @samp{info threads} display.  Some examples of
> possible thread extra info strings are "Runnable", or "Blocked on
> Mutex".

Please use `` and '' rather than " for quoting things.  The former
are typeset by TeX in a way that produces a more pleasant effect (the
on-line manual has `` and '' transformed into ").

> @item @code{q}@code{Rcmd,}@var{COMMAND} --- remote command
> 
> @var{COMMAND} (hex encoded) is passed to the local interpreter for

Please use @var{command}, not @var{COMMAND}.  In Info the up-casing
will be done anyway, while in the printed version upper-case is ugly
and against the conventions of @var arguments.

> number of intermediate @code{O}@var{OUTPUT} console output packets.

Same with OUTPUT.

> @item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value
> 
> Set the value of SYM_NAME to SYM_VALUE.

These should be @var{sym_name} and @var{sym_value}.

Finally, perhaps there should be an index entry for each
packet/command.