From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19124 invoked by alias); 12 Nov 2005 08:47:07 -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 19113 invoked by uid 22791); 12 Nov 2005 08:47:05 -0000 Received: from zproxy.gmail.com (HELO zproxy.gmail.com) (64.233.162.202) by sourceware.org (qpsmtpd/0.30-dev) with ESMTP; Sat, 12 Nov 2005 08:47:05 +0000 Received: by zproxy.gmail.com with SMTP id l1so881036nzf for ; Sat, 12 Nov 2005 00:47:03 -0800 (PST) Received: by 10.36.24.5 with SMTP id 5mr2143171nzx; Sat, 12 Nov 2005 00:47:03 -0800 (PST) Received: by 10.37.2.35 with HTTP; Sat, 12 Nov 2005 00:47:03 -0800 (PST) Message-ID: <8f2776cb0511120047y50b3a273pe17ddd5c53342be1@mail.gmail.com> Date: Sat, 12 Nov 2005 08:47:00 -0000 From: Jim Blandy To: Eli Zaretskii Subject: Re: Formatting of packet descriptions in GDB manual Cc: gdb@sources.redhat.com In-Reply-To: MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Content-Disposition: inline References: <8f2776cb0511111624h4d646cd9i1f86824c5edc613f@mail.gmail.com> X-SW-Source: 2005-11/txt/msg00236.txt.bz2 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". You could put an @r around that, but then the single quotes that go around @code in .info files enclose the entire line, including the English text, which isn't what's wanted. Which leads to my suggestion that we use @table @r, and then put @code around only the packet format, leaving the explanatory text in @r. > 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. Not to prevent others from sharing their thoughts, but can you explain why you yourself feel those characters might need to be distinct?=20 >From my point of view, if it hadn't been typeset that way originally, I don't see why anyone would suggest it. > And what about this monstrocity: > > @item @code{q}@code{M}@var{count}@var{done}@var{argthread}@var{thread@d= ots{}} > > 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. - Expand our metasyntax with some character (say, |) that we can use to separate pieces of a packet format in the documentation, but is not meant to actually appear in the outgoing byte stream. In the printed documentation, this could expand to @bullet or @point or something else clearly non-ASCII. The drawback here is that people might not notice our explanation that this special character isn't really meant to be included in the byte stream, and become confused. > 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. I'll have some time over the next few days.