Re: [RFA]: TUI documentation

[Eli Zaretskii <eliz at is dot elta dot co dot il>]

On Sat, 21 Jul 2001, Stephane Carrez wrote:

> The following patch adds a new chapter to gdb documentation to describe
> the TUI.  It also document the -tui option.
> I have verified the patch with:
> 
> 	make gdb.dvi
> 	make gdb.info
> 	xdvi/info
> 
> Can you approve this patch?

Thanks for working on this

The patch is approved, provided that you fix the following minor 
problems:

> +@set TUI TUI

Why did you need this, and why did you need to use @value{TUI} later,
instead of the literal "TUI"?

> +@cindex Tui

All the @cindex entries in the GDB manual begin with a lower-case
letter.  So this should either be "TUI" or "tui", but not capitalized.

> +The @value{TUI} is available only when @value{GDBN} is configured
> +with the @code{--enable-tui} configure option.

A cross-reference to the "Configure Options" node would be useful
here.  Maybe --enable-tui should be mentioned in that node as well, if
you think it is important enough.

> +These three windows are aranged by the @value{TUI} according to several
                           ^^^^^^^
"arranged".

> +@node TUI Keys
> +@section TUI Key Bindings

Please add a @cindex entry for "TUI key bindings".

> +@table @key

This should be @kbd, not @key.  The latter will typeset the key
sequences in a frame that's intended to produce a picture of a
keyboard key, which is not what you want, since "C-x C-a" is not a
single key.

> +@item C-x C-a
> +@item C-x a
> +@item C-x A

You cannot have more than one @item in a row; use @itemx for all but
the first one.  Otherwise, the result will look as if the following
text refers only to the last @item.

Also, these keys (as well as all the other key sequences you mention)
should all be indexed, like this:

  @kindex C-x C-a
  @item C-x C-a

> +Think of this key binding as the Emacs @key{C-x 1} binding.

This should use @kbd as well, not @key.

> +@item C-x 2
> +Use a @value{TUI} layout with at least two windows.  When the current
> +layout shows already two windows, a next layout with two windows is used.

The "next layout" part is confusing, I think.  What exactly is the
meaning of "next" here?

> +When a new layout is chosen, there will always be a common window between
> +the previous layout and the new one.

I suggest to reword (assuming I understood your intent ;-) like this:

  When a new layout is chosen, one window will always be common to the
  previous layout and the new one.

> +@node TUI Commands
> +@section TUI specific commands

Please add "@cindex TUI commands" here.

> +@item layout @var{next | prev | <name>}

@var is not an appropriate markup here.  It should be used for
meta-syntactic variables, which stand for something else.  In this
case, the only part which doesn't stand for itself is "<name>".  So
I'd replace this with

  @item layout next | prev | @var{name}

However, I wonder: can `name' really be anything, or only one of the
fixed number of strings ("src", "asm" "split", and "regs")?  If the
latter, perhaps @var{name} isn't the right thing here.

Also, please add @kindex for each of the individual layout commands
(as well as all other commands you mention).

> +@item regs
> +Display the register window together with the source or assembly window.

Is it "regs" or "layout regs"?

> +@item focus @var{next | prev | <win>}
> +Set the focus to the named window.
> +This command allows to change the active window so that scrolling keys
> +can be affected to another window.

Same comments as before about @var.  In addition, this doesn't explain
what can I type instead of <win>.

> +@item winheight @var{name} +@var{count}
> +@itemx winheight @var{name} -@var{count}
> +Change the height of a window.

I'd say "Change the height of the window @var{name} by @var{count}
lines.  Positive counts increase the height, while negative counts
decrease it."

> +@item acs
> +Use the Alternate Character Set to draw the border.

I think this begs for an explanation of what that ACS is.