Formatting of packet descriptions in GDB manual

Formatting of packet descriptions in GDB manual

[Jim Blandy]

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 rendering in .pdf
files is fine.

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

and renders the same in .pdf.

What do folks think?

Re: Formatting of packet descriptions in GDB manual

[Eli Zaretskii]

> 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

Re: Formatting of packet descriptions in GDB manual

[Jim Blandy]

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.

Re: Formatting of packet descriptions in GDB manual

[Eli Zaretskii]

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

Re: Formatting of packet descriptions in GDB manual

[Jim Blandy]

On 11/12/05, Eli Zaretskii <eliz@gnu.org> wrote:
> > 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.

Bless your heart.  That's what I actually wanted to do, but not badly
enough to bother picking a fight over it.

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

I just see our job as defining a syntax.  There's no tokenization
going on here; those characters must appear in that exact sequence.

> 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

BLANKS???  What's WRONG with you???

Of course --- that'd work perfectly.

Re: Formatting of packet descriptions in GDB manual

[Daniel Jacobowitz]

On Sun, Nov 13, 2005 at 12:53:51AM +0200, Eli Zaretskii wrote:
> > >   @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.

I don't think they need to be typeset separately.  In fact, I don't
want them to be.  You can't search for useful things in the info manual
this way - to use search (rather than index) to reach the particular
packet, you have to know where the quotes are and search for z'`3.
Yuck.

> 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

100% agree.

-- 
Daniel Jacobowitz
CodeSourcery, LLC

Re: Formatting of packet descriptions in GDB manual

[Eli Zaretskii]

> Date: Sun, 13 Nov 2005 12:12:47 -0500
> From: Daniel Jacobowitz <drow@false.org>
> Cc: Jim Blandy <jimb@red-bean.com>, gdb@sources.redhat.com
> 
> On Sun, Nov 13, 2005 at 12:53:51AM +0200, Eli Zaretskii wrote:
> > > >   @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.
> 
> I don't think they need to be typeset separately.  In fact, I don't
> want them to be.  You can't search for useful things in the info manual
> this way - to use search (rather than index) to reach the particular
> packet, you have to know where the quotes are and search for z'`3.
> Yuck.

This is a misunderstanding: by ``typeset separately'' I meant `z 3'
(as opposed to `z3'), not `z'`3'.

Re: Formatting of packet descriptions in GDB manual

[Daniel Jacobowitz]

On Mon, Nov 14, 2005 at 12:10:28AM +0200, Eli Zaretskii wrote:
> > Date: Sun, 13 Nov 2005 12:12:47 -0500
> > From: Daniel Jacobowitz <drow@false.org>
> > Cc: Jim Blandy <jimb@red-bean.com>, gdb@sources.redhat.com
> > 
> > On Sun, Nov 13, 2005 at 12:53:51AM +0200, Eli Zaretskii wrote:
> > > > >   @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.
> > 
> > I don't think they need to be typeset separately.  In fact, I don't
> > want them to be.  You can't search for useful things in the info manual
> > this way - to use search (rather than index) to reach the particular
> > packet, you have to know where the quotes are and search for z'`3.
> > Yuck.
> 
> This is a misunderstanding: by ``typeset separately'' I meant `z 3'
> (as opposed to `z3'), not `z'`3'.

Yes, I understand.  But then you still can't search for the text of the
packet.

-- 
Daniel Jacobowitz
CodeSourcery, LLC

Re: Formatting of packet descriptions in GDB manual

[Eli Zaretskii]

> Date: Sun, 13 Nov 2005 21:29:55 -0500
> From: Daniel Jacobowitz <drow@false.org>
> Cc: gdb@sources.redhat.com, Jim Blandy <jimb@red-bean.com>
> 
> > This is a misunderstanding: by ``typeset separately'' I meant `z 3'
> > (as opposed to `z3'), not `z'`3'.
> 
> Yes, I understand.  But then you still can't search for the text of the
> packet.

Assuming you expect the text of the packet to contain "z3", yes.  If
this assumption holds for many GDB users, then we shouldn't separate
the characters.  That's exactly the kind of information I didn't feel
to possess in order to make a good decision.

Re: Formatting of packet descriptions in GDB manual

[Daniel Jacobowitz]

On Mon, Nov 14, 2005 at 06:29:10AM +0200, Eli Zaretskii wrote:
> > Date: Sun, 13 Nov 2005 21:29:55 -0500
> > From: Daniel Jacobowitz <drow@false.org>
> > Cc: gdb@sources.redhat.com, Jim Blandy <jimb@red-bean.com>
> > 
> > > This is a misunderstanding: by ``typeset separately'' I meant `z 3'
> > > (as opposed to `z3'), not `z'`3'.
> > 
> > Yes, I understand.  But then you still can't search for the text of the
> > packet.
> 
> Assuming you expect the text of the packet to contain "z3", yes.  If
> this assumption holds for many GDB users, then we shouldn't separate
> the characters.  That's exactly the kind of information I didn't feel
> to possess in order to make a good decision.

OK.  In that case, yes, that's what I'd assume; I'd even call it a z3
packet in conversation.

-- 
Daniel Jacobowitz
CodeSourcery, LLC

Re: Formatting of packet descriptions in GDB manual

[Jim Blandy]

Now that we've eliminated the brief summaries from the packets' @item
lines, I'd like to suggest using @samp for packet contents, instead of
@code.  I think this is more consistent with their general use in
Texinfo, and it looks okay in print and on-line.  But it's arguable;
what do folks think?  Aesthetically, I appreciate having the quotes
around the packet contents  when they're mixed in with the text.

From texinfo.info:

9.1.2 `@code'{SAMPLE-CODE}
--------------------------

Use the `@code' command to indicate text that is a piece of a program
and which consists of entire syntactic tokens.  Enclose the text in
braces.

  Thus, you should use `@code' for an expression in a program, for the
name of a variable or function used in a program, or for a keyword in a
programming language.

  Use `@code' for command names in languages that resemble programming
languages, such as Texinfo.  For example, `@code' and `@samp' are
produced by writing `@code{@@code}' and `@code{@@samp}' in the Texinfo
source, respectively.

...

9.1.5 `@samp'{TEXT}
-------------------

Use the `@samp' command to indicate text that is a literal example or
`sample' of a sequence of characters in a file, string, pattern, etc.
Enclose the text in braces.  The argument appears within single
quotation marks in both the Info file and the printed manual; in
addition, it is printed in a fixed-width font.

Re: Formatting of packet descriptions in GDB manual

[Eli Zaretskii]

> Date: Tue, 15 Nov 2005 21:47:37 -0800
> From: Jim Blandy <jimb@red-bean.com>
> 
> Now that we've eliminated the brief summaries from the packets' @item
> lines, I'd like to suggest using @samp for packet contents, instead of
> @code.  I think this is more consistent with their general use in
> Texinfo, and it looks okay in print and on-line.  But it's arguable;
> what do folks think?  Aesthetically, I appreciate having the quotes
> around the packet contents  when they're mixed in with the text.

@code and @samp produce identical results in the Info manual.  In
print and in PDF, @samp uses the same typeface as @code, but it also
encloses the text in single parens.

> Use the `@samp' command to indicate text that is a literal example or
> `sample' of a sequence of characters in a file, string, pattern, etc.

For this reason, it's probably a good idea to use @samp.