Re: Formatting of packet descriptions in GDB manual

[Jim Blandy <jimb@red-bean.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".  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? 
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@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.

- 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.