Re: [PROPOSAL] Checking for supported packets - revised

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 9 May 2006 19:01:23 -0400
> From: Daniel Jacobowitz <drow@false.org>
> 
> Here are the new commands currently in my patch, and the updated
> protocol documentation.  If no one has any additional comments about
> it, I'll submit the corresponding code soon.

The text is okay with me, but please take care of these minor gotchas:

> +@item qSupported @r{[}:@var{feature} @r{[};@var{feature}@r{]}... @r{]}
                                                                ^^^
This should use @dots{}, not literal dots.

> +@cindex supported packets, remote query
> +@cindex features of the remote protocol
> +@cindex @samp{qSupported} packet
> +Tell the remote target about features supported by @value{GDBN}, and
> +query it for features it supports.  This packet allows @value{GDBN}
> +and the remote target to take advantage of each others' features.
> +It also can eliminate excessive round trips when connecting to
> +a target; on high-latency links, a single @samp{qSupported} packet
> +is faster than a series of probe packets for unsupported packets.
> +
> +No values of @var{feature} are defined yet.

Is there any way to somehow mark this last sentence, so that we will
remove it as soon as at least one feature is defined?  I'm afraid we
will forget.

> +Currently, all remote packets which are not mentioned in the response
> +will be probed individually, just as if the @samp{qSupported} query
> +was not supported.  In the future, some new packets may be added to

Same here.

> +@item @var{name}?
> +The remote protocol packet @var{name} may be supported, and @value{GDBN}
> +should attempt to detect the packet when it is needed.

"attempt to detect the packet"?  Perhaps it's better to say "attempt
to detect whether the packet is supported".

> +The name of a packet which can be marked as supported or unsupported
> +is the text of the packet in this documentation, up to but not
> +including the first punctuation character or variable.  For example, a
> +target which supports hardware watchpoints but not hardware
> +breakpoints might report @samp{Z0-;Z1-;Z2+;Z3+;Z4+}.  An exception is
> +made for @samp{qPart:@var{object}} packets; the name of the packet
> +includes the @var{object}, but not the @var{annex}.  Individual
> +@samp{qPart} objects types must be reported separately.

Please add a cross-reference to the two places where the two example
packets are described, so that the reader could consult them in case
they don't remember the packets' formats by heart.