RFA: GDB manual: clean up query packet documentation

RFA: GDB manual: clean up query packet documentation

[Jim Blandy]

[-- Attachment #1: Type: text/plain, Size: 342 bytes --]

gdb/doc/ChangeLog:
2005-11-17  Jim Blandy  <jimb@redhat.com>

	* gdb.texinfo (Packets): Move information out of 'q' and 'Q'
	entries into the General Query Packets section.  Add a
	cross-reference to that section.
	(General Query Packets): Add introductory text.  Explain naming
	conventions, and how the end of a name is recognized.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: jimb.gdb-doc-remote-protocol-query-cleanup.patch --]
[-- Type: text/x-patch; name="jimb.gdb-doc-remote-protocol-query-cleanup.patch", Size: 4017 bytes --]

gdb/doc/ChangeLog:
2005-11-17  Jim Blandy  <jimb@redhat.com>

	* gdb.texinfo (Packets): Move information out of 'q' and 'Q'
	entries into the General Query Packets section.  Add a
	cross-reference to that section.
	(General Query Packets): Add introductory text.  Explain naming
	conventions, and how the end of a name is recognized.

Index: gdb/doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.292
diff -c -p -r1.292 gdb.texinfo
*** gdb/doc/gdb.texinfo	16 Nov 2005 10:34:33 -0000	1.292
--- gdb/doc/gdb.texinfo	18 Nov 2005 00:55:12 -0000
*************** for success
*** 22397,22426 ****
  for an error
  @end table
  
! @item q @var{query}
! @anchor{general query packet}
  @cindex @samp{q} packet
- General query.  Request info about @var{query}.  In general
- @value{GDBN} queries have a leading upper case letter.  Custom vendor
- queries should use a company prefix (in lower case) ex:
- @samp{qfsf.var}.  @var{query} may optionally be followed by a @samp{,}
- or @samp{;} separated list.  Stubs must ensure that they match the
- full @var{query} name.
- 
- Reply:
- @table @samp
- @item @var{XX@dots{}}
- Hex encoded data from query.  The reply must not be empty.
- @item E @var{NN}
- error reply
- @item
- Indicating an unrecognized @var{query}.
- @end table
- 
- @item Q @var{var}=@var{val}
  @cindex @samp{Q} packet
! General set.  Set value of @var{var} to @var{val}.
! @xref{general query packet}, for a discussion of naming conventions.
  
  @item r
  @cindex @samp{r} packet
--- 22397,22408 ----
  for an error
  @end table
  
! @item q @var{name} @var{params}@dots{}
! @itemx Q @var{name} @var{params}@dots{}
  @cindex @samp{q} packet
  @cindex @samp{Q} packet
! General query (@samp{q}) and set (@samp{Q}).  These packets are
! described fully in @ref{General Query Packets}.
  
  @item r
  @cindex @samp{r} packet
*************** protocol extension}, for more details.
*** 22735,22741 ****
  @section General Query Packets
  @cindex remote query requests
  
! The following set and query packets have already been defined.
  
  Like the descriptions of the other packets, each description here
  has a template showing the packet's overall syntax, followed by an
--- 22717,22749 ----
  @section General Query Packets
  @cindex remote query requests
  
! Packets starting with @samp{q} are @dfn{general query packets};
! packets starting with @samp{Q} are @dfn{general set packets}.  General
! query and set packets are a semi-unified form for retrieving and
! sending information to and from the stub.
! 
! The initial letter of a query or set packet is followed by a name
! indicating what sort of thing the packet applies to.  For example,
! @value{GDBN} may use a @samp{qSymbol} packet to exchange symbol
! definitions with the stub.  These packet names follow some
! conventions:
! 
! @itemize @bullet
! @item
! The name must not contain commas, colons or semicolons.
! @item
! Most @value{GDBN} query and set packets have a leading upper case
! letter.
! @item
! The names of custom vendor packets should use a company prefix, in
! lower case, followed by a period.  For example, packets designed at
! the Acme Corporation might begin with @samp{qacme.foo} (for querying
! foos) or @samp{Qacme.bar} (for setting bars).
! @end itemize
! 
! A query or set packet may optionally be followed by a @samp{,} or
! @samp{;} separated list.  Stubs must be careful to match the full
! packet name, in case packet names have common prefixes.
  
  Like the descriptions of the other packets, each description here
  has a template showing the packet's overall syntax, followed by an
*************** explanation of the packet's meaning.  We
*** 22743,22748 ****
--- 22751,22758 ----
  templates for clarity; these are not part of the packet's syntax.  No
  @value{GDBN} packet uses spaces to separate its components.
  
+ Here are the currently defined query and set packets:
+ 
  @table @samp
  
  @item qC

Re: RFA: GDB manual: clean up query packet documentation

[Eli Zaretskii]

> Date: Thu, 17 Nov 2005 17:27:45 -0800
> From: Jim Blandy <jimb@red-bean.com>
> 
> gdb/doc/ChangeLog:
> 2005-11-17  Jim Blandy  <jimb@redhat.com>
> 
> 	* gdb.texinfo (Packets): Move information out of 'q' and 'Q'
> 	entries into the General Query Packets section.  Add a
> 	cross-reference to that section.
> 	(General Query Packets): Add introductory text.  Explain naming
> 	conventions, and how the end of a name is recognized.

Thanks, this is approved.

One question, though:

> - Reply:
> - @table @samp
> - @item @var{XX@dots{}}
> - Hex encoded data from query.  The reply must not be empty.
> - @item E @var{NN}
> - error reply
> - @item
> - Indicating an unrecognized @var{query}.
> - @end table

This "Reply:" part is not in the new text.  Did you really intend to
delete it, and if so, why?

Re: RFA: GDB manual: clean up query packet documentation

[Jim Blandy]

On 11/18/05, Eli Zaretskii <eliz@gnu.org> wrote:
> One question, though:
>
> > - Reply:
> > - @table @samp
> > - @item @var{XX@dots{}}
> > - Hex encoded data from query.  The reply must not be empty.
> > - @item E @var{NN}
> > - error reply
> > - @item
> > - Indicating an unrecognized @var{query}.
> > - @end table
>
> This "Reply:" part is not in the new text.  Did you really intend to
> delete it, and if so, why?

The descriptions for the individual packets give the forms of their
replies, and the fact that an empty reply means that the packet isn't
recognized applies to all packets, and is explained in the "Overview"
node.

Re: RFA: GDB manual: clean up query packet documentation

[Eli Zaretskii]

> Date: Fri, 18 Nov 2005 09:33:44 -0800
> From: Jim Blandy <jimb@red-bean.com>
> Cc: gdb-patches@sources.redhat.com
> 
> On 11/18/05, Eli Zaretskii <eliz@gnu.org> wrote:
> > One question, though:
> >
> > > - Reply:
> > > - @table @samp
> > > - @item @var{XX@dots{}}
> > > - Hex encoded data from query.  The reply must not be empty.
> > > - @item E @var{NN}
> > > - error reply
> > > - @item
> > > - Indicating an unrecognized @var{query}.
> > > - @end table
> >
> > This "Reply:" part is not in the new text.  Did you really intend to
> > delete it, and if so, why?
> 
> The descriptions for the individual packets give the forms of their
> replies, and the fact that an empty reply means that the packet isn't
> recognized applies to all packets, and is explained in the "Overview"
> node.

Okay.

Re: RFA: GDB manual: clean up query packet documentation

[Jim Blandy]

On 11/17/05, Jim Blandy <jimb@red-bean.com> wrote:
> gdb/doc/ChangeLog:
> 2005-11-17  Jim Blandy  <jimb@redhat.com>
>
>         * gdb.texinfo (Packets): Move information out of 'q' and 'Q'
>         entries into the General Query Packets section.  Add a
>         cross-reference to that section.
>         (General Query Packets): Add introductory text.  Explain naming
>         conventions, and how the end of a name is recognized.

Committed, with an expanded ChangeLog entry.  Thanks.