Re: Formatting of packet descriptions in GDB manual

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sat, 12 Nov 2005 00:47:03 -0800
> From: Jim Blandy <jimb@red-bean.com>
> Cc: gdb@sources.redhat.com
> 
> On 11/11/05, Eli Zaretskii <eliz@gnu.org> 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.