From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20293 invoked by alias); 16 Nov 2005 07:11:30 -0000 Received: (qmail 20280 invoked by uid 22791); 16 Nov 2005 07:11:27 -0000 Received: from romy.inter.net.il (HELO romy.inter.net.il) (192.114.186.66) by sourceware.org (qpsmtpd/0.30-dev) with ESMTP; Wed, 16 Nov 2005 07:11:27 +0000 Received: from HOME-C4E4A596F7 (IGLD-80-230-53-80.inter.net.il [80.230.53.80]) by romy.inter.net.il (MOS 3.5.8-GR) with ESMTP id CZJ97159 (AUTH halo1); Wed, 16 Nov 2005 09:11:23 +0200 (IST) Date: Wed, 16 Nov 2005 07:21:00 -0000 Message-Id: From: Eli Zaretskii To: Jim Blandy CC: gdb-patches@sources.redhat.com In-reply-to: <8f2776cb0511152152p85abe3pa7ad547043c53c0a@mail.gmail.com> (message from Jim Blandy on Tue, 15 Nov 2005 21:52:06 -0800) Subject: Re: Formatting of packet descriptions in GDB manual Reply-to: Eli Zaretskii References: <8f2776cb0511111624h4d646cd9i1f86824c5edc613f@mail.gmail.com> <8f2776cb0511120047y50b3a273pe17ddd5c53342be1@mail.gmail.com> <20051113171247.GA1945@nevyn.them.org> <20051114022955.GA10567@nevyn.them.org> <20051114134924.GB21373@nevyn.them.org> <8f2776cb0511152147i4c24e43aue46a54332fd4c0f3@mail.gmail.com> <8f2776cb0511152152p85abe3pa7ad547043c53c0a@mail.gmail.com> 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: 2005-11/txt/msg00219.txt.bz2 > Date: Tue, 15 Nov 2005 21:52:06 -0800 > From: Jim Blandy > > Here's a patch that implements the formatting changes to the > description of the remote protocol packets we've been discussing on > gdb@. > > This uses @code for the packet templates, even though in my last > message there I said I thought @samp was more appropriate; @code is > what I've got right now, and I didn't want to go and change everything > twice if the conclusion was that @code was better. But you can see > what was done. Thanks. This is fine, but while at that, let's fix a few more minor problems in the original text: > ! @item b @var{baud} > @cindex @code{b} packet > ! @strong{(deprecated)} > Change the serial line speed to @var{baud}. I have a problem with this "(deprecated)" thing. Can we simply add a sentence saying this is deprecated in favor of whatever substitutions we want people to use instead? > ! @item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]} > @anchor{cycle step packet} > @cindex @code{i} packet > ! @strong{(draft)} > Step the remote target by a single clock cycle. If @code{,}@var{nnn} is > present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle > step starting at that address. Similarly here for "(draft)", but in this case I don't even understand the implications of this packet being ``draft''. Can we spell them out in plain English? (There are more "(deprecated)" and "(draft)" in that section.) Several places use two or more @item's in consecutive lines, then describe them both. This is incorrect Texinfo: all but the first @item should be @itemx. > ! The @code{C}, @code{c}, @code{S}, @code{s} and @code{?} packets can > ! receive any of the below as a reply. In the case of the @code{C}, > ! @code{c}, @code{S} and @code{s} packets, that reply is only returned > ! when the target halts. In the below the exact meaning of ``signal > ! number'' is poorly defined. This ``signal number'' will look better in print and PDF if we use @dfn{signal number}. > @var{AA} = two hex digit signal number; @var{n...} = register number > (hex), @var{r...} = target byte ordered register contents, size defined > ! by @code{DEPRECATED_REGISTER_RAW_SIZE}; @var{n...} = @code{thread}, > @var{r...} = thread process ID, this is a hex integer; @var{n...} = > ! (@code{watch} | @code{rwatch} | @code{awatch}, @var{r...} = data > address, this is a hex integer; @var{n...} = other string not starting > with valid hex digit. @value{GDBN} should ignore this @var{n...}, > @var{r...} pair and go on to the next. This way we can extend the I think this paragraph will read better if we replace the equals signs with ``is'' or ``are'', as appropriate, or with some other English construct. Otherwise, this can go in, after you replace @code with @samp in the @table lines, per your other message. Thanks!