Re: Formatting of packet descriptions in GDB manual

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Fri, 11 Nov 2005 16:24:57 -0800
> From: Jim Blandy <jimb@red-bean.com>
> 
> 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