This is the mail archive of the gdb@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]