From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 6479 invoked by alias); 12 Nov 2005 07:07:00 -0000 Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org Received: (qmail 6467 invoked by uid 22791); 12 Nov 2005 07:06:58 -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; Sat, 12 Nov 2005 07:06:58 +0000 Received: from HOME-C4E4A596F7 (IGLD-80-230-68-181.inter.net.il [80.230.68.181]) by romy.inter.net.il (MOS 3.5.8-GR) with ESMTP id CYR95870 (AUTH halo1); Sat, 12 Nov 2005 09:06:54 +0200 (IST) Date: Sat, 12 Nov 2005 07:07:00 -0000 Message-Id: From: Eli Zaretskii To: Jim Blandy CC: gdb@sources.redhat.com In-reply-to: <8f2776cb0511111624h4d646cd9i1f86824c5edc613f@mail.gmail.com> (message from Jim Blandy on Fri, 11 Nov 2005 16:24:57 -0800) Subject: Re: Formatting of packet descriptions in GDB manual Reply-to: Eli Zaretskii References: <8f2776cb0511111624h4d646cd9i1f86824c5edc613f@mail.gmail.com> X-SW-Source: 2005-11/txt/msg00234.txt.bz2 > Date: Fri, 11 Nov 2005 16:24:57 -0800 > From: Jim Blandy > > The way gdb.texinfo describes packet formats is pretty wierd. The > .texinfo says stuff like: > > @table @r > ... > @item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info > > which is rendered in .info files as: > > `q'`ThreadExtraInfo'`,'ID -- extra thread info > > Those quotes aren't helping anything at all. The packets' markup, and in particular the huge table in that section, is on my todo since I took the responsibility of the manual, I just didn't have time to do that, since it's a huge section that needs to be done all at once. In general, I'd say that whoever wrote that section didn't know that @var{} typesets correctly even if it is inside @code. Thus, if I'd work to fix that section, I'd first modify "@table @r" into "@table @code", and then remove all the @code's in the @item's. > I'd much rather see: > > @table @r > ... > @item @code{qThreadExtraInfo,@var{id}} --- extra thread info > > which renders in .info as: > > `qThreadExtraInfo,ID' -- extra thread info That'd be fine with me, but there are several other minor problems to consider. For example, in a packet like this: @code{z}@code{3}@code{,}@var{addr}@code{,}@var{length} is it important to have `z', `3', and the comma typeset as 3 separate characters, or is it okay to see a single string `z3,'? At the time I looked at this section, the answer was not clear to me. You seem to indicate that it's okay to produce a single string here, but what do others think. And what about this monstrocity: @item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@dots{}} Is it okay to typeset the arguments in @var without any whitespace between them and the surrounding text? There is no whitespace when this is sent on the wire, but what about the human reader of the manual? We need to try several possible markups and see which one is the best. Then we can rewrite this section to look better (and also not produce overfull hbox warnings from TeX). If you can find time to work on this, I will gratefully provide any help and advice I can, given my limited time. TIA