Re: Texinfo doc for GDB-UI

["Eli Zaretskii" <eliz@is.elta.co.il>]

> From: Nick Roberts <nick@nick.uklinux.net>
> Date: Mon, 23 Dec 2002 21:54:28 +0000
> 
> Here is my attempt at writing something for gdb-ui.el for the emacs manual.

Thanks!

A few comments:

> + @item M-x gdba @key{RET} @var{file} @key{RET}
> + @findex gdba
> + Run GDB as a subprocess of Emacs.  This command generates a more extensive
> + user interface than the command gdb. These extra features are described in
> + @xref{GDB-UI}.

First, please don't use @xref except at the beginning of a sentence,
since the text it produces begins with a capitalized "See", and will
look like a typo in the middle of a sentence.

Secondly, an index entry for a command ("@findex gdba" above) should
be where the command is explained in full, not where it's mentioned
for the first time.  So the right place for the index entry is in the
second paragraph of the node GDB-UI.

Finally, please make sure every sentence has either two spaces or a
newline after the period that ends the sentence.  This is so TeX
typesets the sentence separation correctly.

> + with just one or two windows. So, after re-compilation, the window
> + layout for the debugging session can be restored with
> + @code{gdb-restore-windows}.

Please make an @findex entry for every command you mention in the
manual (here gdb-restore-windows).  (There are other places where
commands are mentioned without an @findex entry.)

> + @node Layout
> + @subsubsection Layout

It is generally advisable to make @cindex entries where important
parts of the UI are described, under the assumption that users may
wish to find those details quickly.  For example, this section would
probably benefit from an entry such as "@cindex GDB-UT layout".  The
subsection name is in many cases a good starting point for the
@cindex entry.

> + If @code{gdb-many-windows} is nil (the default value)

`nil' is a symbol, so it should have the @code markup.

> + @verb{+---------------------------------------------------------------------
> +                                GDB Toolbar                           
> + ---------------------------------------------------------------------
> + GUD buffer (I/O of GDB)           | Locals buffer                    

I suggest to make the lines here shorter; anything longer than 64
characters will produce overfull hbox warnings from TeX, and will
spill over to the margin of the page.

> + This buffer allows control of the breakpoints which have been set
> + previously and uses the output from the GDB command @xref{Set Breaks,,
> + info breakpoints, Gdb, The GNU debugger}.

Does this xref really work?  The GDB manual's name is `gdb.info', not
`Gdb.info', so on a case-sensitive filesystem the xref might not work
(but I didn't actually try that, so I might be missing something).

> + grey when it is disabled. Text-only terminals will correspondingly
> + display a `B' or `b'.

Please use @samp{b} and @samp{B}, not `b' and `B' here.

> + This buffer controls the list of expressions set up to display
> + automatically and uses the output from the GDB command @xref{Auto
> + Display,,info display, Gdb, The GNU debugger}. As with the
> + breakpoints the displayed may be enabled/disabled or deleted.

I think the last sentence should say "displayed expressions" or maybe
"displays", not "displayed".