From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 11395 invoked by alias); 5 May 2006 21:59:13 -0000 Received: (qmail 11382 invoked by uid 22791); 5 May 2006 21:59:12 -0000 X-Spam-Check-By: sourceware.org Received: from intranet.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.6) by sourceware.org (qpsmtpd/0.31) with ESMTP; Fri, 05 May 2006 21:59:10 +0000 Received: (qmail 16405 invoked from network); 5 May 2006 21:59:08 -0000 Received: from unknown (HELO localhost) (jimb@127.0.0.2) by mail.codesourcery.com with ESMTPA; 5 May 2006 21:59:08 -0000 To: Eli Zaretskii Cc: gdb-patches@sourceware.org Subject: Re: RFA: Document conventions for terminating query/set packet names References: <20060503195650.GA13156@nevyn.them.org> <20060504015712.GA19810@nevyn.them.org> <8f2776cb0605032313s69362babjcda4e60fe33f9d6e@mail.gmail.com> <20060504123755.GA29302@nevyn.them.org> <8f2776cb0605041024u7c420707ie2fbff8a32ce32f0@mail.gmail.com> From: Jim Blandy Date: Fri, 05 May 2006 21:59:00 -0000 In-Reply-To: (Eli Zaretskii's message of "Sat, 06 May 2006 00:49:16 +0300") Message-ID: User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2006-05/txt/msg00114.txt.bz2 Eli Zaretskii writes: >> Cc: gdb-patches@sourceware.org >> From: Jim Blandy >> Date: Fri, 05 May 2006 12:18:23 -0700 >> >> (Argh. In Emacs, the command to insert '@code{}' in a texinfo-mode >> buffer is C-c C-c c. But in a mail-mode buffer, C-c C-c is 'send >> message'...) > > Yeah, was bitten by that one, too. > >> We could replace that last sentence with: >> >> New packets should not begin with @samp{qP} or @samp{qL}.@footnote{The >> @samp{qP} and @samp{qL} packets predate these conventions, and don't >> have any terminator for the packet name; we suspect they are in >> widespread use in places that are difficult to upgrade.} >> >> if you prefer. > > Yes, that's what I had in mind, sorry it wasn't immediately clear. > > But please start the footnote _before_ the period, and add the period > after the right brace that ends the footnote. All right. Here's what I've committed. gdb/doc/ChangeLog: 2006-05-05 Jim Blandy * gdb.texinfo (General Query Packets): Document conventions for terminating packet names, and their violations. Index: gdb/doc/gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.325 diff -u -p -r1.325 gdb.texinfo --- gdb/doc/gdb.texinfo 27 Apr 2006 23:03:42 -0000 1.325 +++ gdb/doc/gdb.texinfo 5 May 2006 21:57:13 -0000 @@ -23106,9 +23106,14 @@ the Acme Corporation might begin with @s 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. +The name of a query or set packet should be separated from any +parameters by a @samp{:}; the parameters themselves should be +separated by @samp{,} or @samp{;}. Stubs must be careful to match the +full packet name, in case packet names have common prefixes. New +packets should not begin with @samp{qP} or @samp{qL}@footnote{The +@samp{qP} and @samp{qL} packets predate these conventions, and don't +have any terminator for the packet name; we suspect they are in +widespread use in places that are difficult to upgrade.}. Like the descriptions of the other packets, each description here has a template showing the packet's overall syntax, followed by an @@ -23252,6 +23257,9 @@ Reply: Returns information on @var{threadid}. Where: @var{mode} is a hex encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. +Don't use this packet; use the @samp{qThreadExtraInfo} query instead +(see below). + Reply: see @code{remote.c:remote_unpack_thread_info_response()}. @item qPart:@var{object}:read:@var{annex}:@var{offset},@var{length} @@ -23263,6 +23271,9 @@ starting at @var{offset} bytes into the encoding of @var{annex} is specific to the object; it can supply additional details about what data to access. +Since this packet is ambiguous with the older @code{qP} packet, we +plan to rename it. + Here are the specific requests of this form defined so far. All @samp{qPart:@var{object}:read:@dots{}} requests use the same reply formats, listed below. @@ -23354,6 +23365,11 @@ Indicate a badly formed request. An empty reply indicates that @samp{qRcmd} is not recognized. @end table +(Note that the @code{qRcmd} packet's name is separated from the +command by a @samp{,}, not a @samp{:}, contrary to the naming +conventions above. Please don't use this packet as a model for new +packets.) + @item qSymbol:: @cindex symbol lookup, remote request @cindex @samp{qSymbol} packet @@ -23414,6 +23430,11 @@ comprising the printable string containi the thread's attributes. @end table +(Note that the @code{qThreadExtraInfo} packet's name is separated from +the command by a @samp{,}, not a @samp{:}, contrary to the naming +conventions above. Please don't use this packet as a model for new +packets.) + @item QTStart @itemx QTStop @itemx QTinit