[RFA]: TUI documentation

[Stephane Carrez <Stephane dot Carrez at worldnet dot fr>]

Hi!

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?

	Stephane

2001-07-21  Stephane Carrez  <Stephane.Carrez@worldnet.fr>

	* gdb.texinfo (TUI): New chapter, document the TUI.
	(Mode Options): Document the -tui option.
Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.44
diff -u -p -r1.44 gdb.texinfo
--- gdb.texinfo	2001/07/06 04:07:29	1.44
+++ gdb.texinfo	2001/07/21 19:49:50
@@ -137,6 +137,7 @@ Copyright (C) 1988-2001 Free Software Fo
 * Configurations::              Configuration-specific information
 * Controlling GDB::             Controlling @value{GDBN}
 * Sequences::                   Canned sequences of commands
+* TUI::                         @value{GDBN} Text User Interface
 * Emacs::                       Using @value{GDBN} under @sc{gnu} Emacs
 * Annotations::                 @value{GDBN}'s annotation interface.
 * GDB/MI::                      @value{GDBN}'s Machine Interface.
@@ -1026,13 +1027,14 @@ Run using @var{device} for your program'
 @c FIXME: kingdon thinks there is more to -tty.  Investigate.
 
 @c resolve the situation of these eventually
-@c @item -tui
-@c @cindex @code{--tui}
-@c Use a Terminal User Interface.  For information, use your Web browser to
-@c read the file @file{TUI.html}, which is usually installed in the
-@c directory @code{/opt/langtools/wdb/doc} on HP-UX systems.  Do not use
-@c this option if you run @value{GDBN} from Emacs (see @pxref{Emacs, ,Using
-@c @value{GDBN} under @sc{gnu} Emacs}).
+@item -tui
+@cindex @code{--tui}
+Activate the Terminal User Interface when starting. 
+The Terminal User Interface manages several text windows on the terminal,
+showing source, assembly, registers and @value{GDBN} command outputs
+(@pxref{TUI, ,@value{GDBN} Text User Interface}).
+Do not use this option if you run @value{GDBN} from Emacs
+(@pxref{Emacs, ,Using @value{GDBN} under @sc{gnu} Emacs}).
 
 @c @item -xdb
 @c @cindex @code{--xdb}
@@ -12973,6 +12975,244 @@ printf "foo, bar-foo = 0x%x, 0x%x\n", fo
 The only backslash-escape sequences that you can use in the format
 string are the simple ones that consist of backslash followed by a
 letter.
+@end table
+
+@set TUI TUI
+@node TUI
+@chapter @value{GDBN} Text User Interface
+@cindex Tui
+
+@menu
+* TUI Overview::                TUI overview
+* TUI Keys::                    TUI key bindings
+* TUI Commands::                TUI specific commands
+* TUI Configuration::           TUI configuration variables
+@end menu
+
+The @value{GDBN} Text User Interface, @value{TUI} in short,
+is a terminal interface which uses the @code{curses} library
+to show the source file, the assembly output, the program registers
+and @value{GDBN} commands in separate text windows.
+The @value{TUI} is available only when @value{GDBN} is configured
+with the @code{--enable-tui} configure option.
+
+@node TUI Overview
+@section TUI overview
+
+The @value{TUI} has two display modes that can be switched while
+@value{GDBN} runs:
+
+@itemize @bullet
+@item
+A curses (or @value{TUI}) mode in which it displays several text
+windows on the terminal.
+
+@item
+A standard mode which corresponds to the @value{GDBN} configured without
+the @value{TUI}.
+@end itemize
+
+In the @value{TUI} mode, @value{GDBN} can display several text window
+on the terminal:
+
+@table @emph
+@item command
+This window is the @value{GDBN} command window with the @value{GDBN}
+prompt and the @value{GDBN} outputs.  The @value{GDBN} input is still
+managed using readline but through the @value{TUI}.  The @emph{command}
+window is always visible.
+
+@item source
+The source window shows the source file of the program.  The current
+line as well as active breakpoints are displayed in this window.
+The current program position is shown with the @samp{>} marker and
+active breakpoints are shown with @samp{*} markers.
+
+@item assembly
+The assembly window shows the disassembly output of the program.
+
+@item register
+This window shows the processor registers.  It detects when
+a register is changed and when this is the case, registers that have
+changed are highlighted.
+
+@end table
+
+The source, assembly and register windows are attached to the thread
+and the frame position.  They are updated when the current thread
+changes, when the frame changes or when the program counter changes.
+These three windows are aranged by the @value{TUI} according to several
+layouts.  The layout defines which of these three windows are visible.
+
+@node TUI Keys
+@section TUI Key Bindings
+
+The @value{TUI} installs several key bindings in the readline keymaps
+(@pxref{Command Line Editing}).
+They allow to leave or enter in the @value{TUI} mode or they operate
+directly on the @value{TUI} layout and windows.  The following key bindings
+are installed for both @value{TUI} mode and the @value{GDBN} standard mode.
+
+@table @key
+@item C-x C-a
+@item C-x a
+@item C-x A
+Enter or leave the @value{TUI} mode.  When the @value{TUI} mode is left,
+the curses window management is left and @value{GDBN} operates using
+its standard mode writing on the terminal directly.  When the @value{TUI}
+mode is entered, the control is given back to the curses windows.
+The screen is then refreshed.
+
+@item C-x 1
+Use a @value{TUI} layout with only one window.  The layout will
+either be @samp{source} or @samp{assembly}.  When the @value{TUI} mode
+is not active, it will switch to the @value{TUI} mode.
+
+Think of this key binding as the Emacs @key{C-x 1} binding.
+
+@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.
+When a new layout is chosen, there will always be a common window between
+the previous layout and the new one.
+
+Think of it as the Emacs @key{C-x 2} binding.
+
+@end table
+
+The following key bindings are handled only by the @value{TUI} mode:
+
+@table @key
+@item PgUp
+Scroll the active window one page up.
+
+@item PgDn
+Scroll the active window one page down.
+
+@item Up
+Scroll the active window one line up.
+
+@item Down
+Scroll the active window one line down.
+
+@item Left
+Scroll the active window one column left.
+
+@item Right
+Scroll the active window one column right.
+
+@item C-L
+Refresh the screen.
+
+@end table
+
+In the @value{TUI} mode, the arrow keys are used by the active window
+for scrolling.  This means they are not available for readline.  It is
+necessary to use other readline key bindings such as @key{C-p}, @key{C-n},
+@key{C-b} and @key{C-f}.
+
+@node TUI Commands
+@section TUI specific commands
+
+The @value{TUI} has specific commands to control the text windows.
+These commands are always available, that is they do not depend on
+the current terminal mode in which @value{GDBN} runs.  When @value{GDBN}
+is in the standard mode, using these commands will automatically switch
+in the @value{TUI} mode.
+
+@table @code
+@item layout @var{next | prev | <name>}
+Change the current TUI layout.
+
+@item layout next
+Display the next layout.
+
+@item layout prev
+Display the previous layout.
+
+@item layout src
+Display the source window only.
+
+@item layout asm
+Display the assembly window only.
+
+@item layout split
+Display the source and assembly window.
+
+@item regs
+Display the register window together with the source or assembly window.
+
+@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.
+
+@item refresh
+Refresh the screen.  This is similar to using @key{C-L} key.
+
+@item update
+Update the source window and the current execution point.
+
+@item winheight @var{name} +@var{count}
+@itemx winheight @var{name} -@var{count}
+Change the height of a window.
+
+@end table
+
+@node TUI Configuration
+@section TUI configuration variables
+
+The @value{TUI} has several configuration variables that control the
+appearance of windows on the terminal.
+
+@table @code
+@item set tui-border-kind @var{kind}
+Select the border appearance for the source, assembly and register windows.
+The possible values are the following:
+@table @code
+@item space
+Use a space character to draw the border.
+
+@item ascii
+Use ascii characters + - and | to draw the border.
+
+@item acs
+Use the Alternate Character Set to draw the border.
+
+@end table
+
+@item set tui-active-border-mode @var{mode}
+Select the attributes to display the border of the active window.
+The possible values are @code{normal}, @code{standout}, @code{reverse},
+@code{half}, @code{half-standout}, @code{bold} and @code{bold-standout}.
+
+@item set tui-border-mode @var{mode}
+Select the attributes to display the border of other windows.
+The @var{mode} can be one of the following:
+@table @code
+@item normal
+Use normal attributes to display the border.
+
+@item standout
+Use standout mode.
+
+@item reverse
+Use reverse video mode.
+
+@item half
+Use half bright mode.
+
+@item half-standout
+Use half bright and standout mode.
+
+@item bold
+Use extra bright or bold mode.
+
+@item bold-standout
+Use extra bright or bold and standout mode.
+
+@end table
+
 @end table
 
 @node Emacs