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

[Andrew Cagney]

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

I changed it to:

Fields within the packet should be separated using @samp{,} @samp{;} or
@cindex remote protocol, field separator
@samp{:}.  Except where otherwise noted all numbers are represented in
@sc{hex} with leading zeros suppressed.

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

Done.

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

Fixed*N

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

It is the program.  I've changed it to @code{gdbserver} which is used 
elsewhere.

>> @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.

I fixed this this local case.  Also bug reported the need to audit the 
file :-(


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

Oops, yes, changed to:

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

>> @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.

Um, yes!

> 
>> For a discussing of naming conventions, @xref{general query packet}.
> 
> 
> This should use "see @ref" or @pxref in parens instead of @xref.

Changed to (note the discussing -> discussion :-):

@xref{general query packet}, for a discussion of naming conventions.

>> @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.


Doh!

>> @node Stop Reply Packets
>> @section Stop Reply Packets
> 
> 
> A @cindex entry here is probably a good idea.

``@cindex stop reply packets''

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

``The process exited, and @var{AA} is the exit status.  This is only
applicable to certain targets.''

>> @var{AA} = signal number; @var{t@dots{}} = address of symbol "_start";
> 
> 
> Please use @code_start} instead of "_start".

Done.

>> @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'.

Changed to ...

``@var{AA} = signal number; @var{t@dots{}} = address of symbol
@start{_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 @samp{qOffsets} query is that
the @samp{N} packet may arrive spontaneously whereas the @samp{qOffsets}
is a query initiated by the host debugger.}''


>> @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.

Done.

>> 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".

Done.  Also in the ``Reply'' section above.

>> 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 ").

Fixed.


>> @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.

Done.

>> @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}.

Fixed.

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

Yes.  That is something to do next.  Exactly how should it be done 
though?  Something like:
	@cindex packet, e
	@cindex e packet
et.al..

Attatched again is the update.  It's starting to look like a manual entry.

Andrew

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: gdb.texinfo
URL: <http://sourceware.org/pipermail/gdb-patches/attachments/20020813/9618baec/attachment.ksh>