This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: Formatting of packet descriptions in GDB manual
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.