From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14378 invoked by alias); 12 Nov 2005 22:53:57 -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 14352 invoked by uid 22791); 12 Nov 2005 22:53:55 -0000 Received: from nitzan.inter.net.il (HELO nitzan.inter.net.il) (192.114.186.20) by sourceware.org (qpsmtpd/0.30-dev) with ESMTP; Sat, 12 Nov 2005 22:53:55 +0000 Received: from HOME-C4E4A596F7 (IGLD-80-230-89-144.inter.net.il [80.230.89.144]) by nitzan.inter.net.il (MOS 3.6.5-GR) with ESMTP id BXY98134 (AUTH halo1); Sun, 13 Nov 2005 00:53:45 +0200 (IST) Date: Sat, 12 Nov 2005 22:53:00 -0000 Message-Id: From: Eli Zaretskii To: Jim Blandy CC: gdb@sources.redhat.com In-reply-to: <8f2776cb0511120047y50b3a273pe17ddd5c53342be1@mail.gmail.com> (message from Jim Blandy on Sat, 12 Nov 2005 00:47:03 -0800) Subject: Re: Formatting of packet descriptions in GDB manual Reply-to: Eli Zaretskii References: <8f2776cb0511111624h4d646cd9i1f86824c5edc613f@mail.gmail.com> <8f2776cb0511120047y50b3a273pe17ddd5c53342be1@mail.gmail.com> X-SW-Source: 2005-11/txt/msg00238.txt.bz2 > Date: Sat, 12 Nov 2005 00:47:03 -0800 > From: Jim Blandy > Cc: gdb@sources.redhat.com > > On 11/11/05, Eli Zaretskii wrote: > > 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 tried that first --- but notice that each @item has explanatory text > after the packet, like "--- remove hardware breakpoint". This is a @table, so that text should be in the next line, not on the @item line. In many cases, this text is redundant anyway, since what follows the @item line repeats the explanation. > > @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. > > Not to prevent others from sharing their thoughts, but can you explain > why you yourself feel those characters might need to be distinct? Because each individual character might be of some importance, mnemonic if not anything else. But that's a guess, I really don't have a good answer for this question. > > @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? > > Yes, that one really is a mess. Two ideas: > > - Replace the variable portion with a single metavariable, say > @var{args}. In the English text below, explain the structure of > @var{args} as the concatenation of these things: blah blah blah. This would just move the problematic part into the text, won't it? Because "blah blah blah" will be something like @var{count}@var{done}@var{argthread}@var{thread}, right? Perhaps we should use blanks between those @var's, but explain in the text that there shouldn't be blanks in the real packet, and give an example to demonstrate that > I'll have some time over the next few days. Thanks.