This is the mail archive of the gdb-patches@sources.redhat.com 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]

Re: [RFA]: TUI documentation


Hi!

Eli Zaretskii a écrit :
> 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"?
> 

I was wondering whether I could use some specific font, specific character
layout and so on.  It's probably too much a trouble.  I removed it.


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

Ok.  I added a reference but the "Configure Options" chapter does not speak
about --enable-*.  I prefer not to add something there because it would mean
some general description.


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

Ok, it makes sense.  The readline manual is using @key for these.


> 
> > +@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?
I added the list of layouts in the overview.

> 
> > +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"?
yes

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

Here is the new patch.

Is it ok?

	Stephane
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/23 21:09:44
@@ -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,290 @@ 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
+
+@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, 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 TUI is available only when @value{GDBN} is configured
+with the @code{--enable-tui} configure option (@pxref{Configure Options}).
+
+@node TUI Overview
+@section TUI overview
+
+The TUI has two display modes that can be switched while
+@value{GDBN} runs:
+
+@itemize @bullet
+@item
+A curses (or 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 TUI.
+@end itemize
+
+In the 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 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 arranged by the TUI according to several
+layouts.  The layout defines which of these three windows are visible.
+The following layouts are available:
+
+@itemize @bullet
+@item
+source
+
+@item
+assembly
+
+@item
+source and assembly
+
+@item
+source and registers
+
+@item
+assembly and registers
+
+@end itemize
+
+@node TUI Keys
+@section TUI Key Bindings
+@cindex TUI key bindings
+
+The TUI installs several key bindings in the readline keymaps
+(@pxref{Command Line Editing}).
+They allow to leave or enter in the TUI mode or they operate
+directly on the TUI layout and windows.  The following key bindings
+are installed for both TUI mode and the @value{GDBN} standard mode.
+
+@table @kbd
+@kindex C-x C-a
+@item C-x C-a
+@kindex C-x a
+@itemx C-x a
+@kindex C-x A
+@itemx C-x A
+Enter or leave the TUI mode.  When the 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 TUI
+mode is entered, the control is given back to the curses windows.
+The screen is then refreshed.
+
+@kindex C-x 1
+@item C-x 1
+Use a TUI layout with only one window.  The layout will
+either be @samp{source} or @samp{assembly}.  When the TUI mode
+is not active, it will switch to the TUI mode.
+
+Think of this key binding as the Emacs @kbd{C-x 1} binding.
+
+@kindex C-x 2
+@item C-x 2
+Use a 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, one window will always be common to the
+previous layout and the new one.
+
+Think of it as the Emacs @kbd{C-x 2} binding.
+
+@end table
+
+The following key bindings are handled only by the TUI mode:
+
+@table @key
+@kindex PgUp
+@item PgUp
+Scroll the active window one page up.
+
+@kindex PgDn
+@item PgDn
+Scroll the active window one page down.
+
+@kindex Up
+@item Up
+Scroll the active window one line up.
+
+@kindex Down
+@item Down
+Scroll the active window one line down.
+
+@kindex Left
+@item Left
+Scroll the active window one column left.
+
+@kindex Right
+@item Right
+Scroll the active window one column right.
+
+@kindex C-L
+@item C-L
+Refresh the screen.
+
+@end table
+
+In the 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
+@cindex TUI commands
+
+The 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 TUI mode.
+
+@table @code
+@item layout next
+@kindex layout next
+Display the next layout.
+
+@item layout prev
+@kindex layout prev
+Display the previous layout.
+
+@item layout src
+@kindex layout src
+Display the source window only.
+
+@item layout asm
+@kindex layout asm
+Display the assembly window only.
+
+@item layout split
+@kindex layout split
+Display the source and assembly window.
+
+@item layout regs
+@kindex layout regs
+Display the register window together with the source or assembly window.
+
+@item focus next | prev | src | asm | regs | split
+@kindex focus
+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
+@kindex refresh
+Refresh the screen.  This is similar to using @key{C-L} key.
+
+@item update
+@kindex update
+Update the source window and the current execution point.
+
+@item winheight @var{name} +@var{count}
+@itemx winheight @var{name} -@var{count}
+@kindex winheight
+Change the height of the window @var{name} by @var{count}
+lines.  Positive counts increase the height, while negative counts
+decrease it.
+
+@end table
+
+@node TUI Configuration
+@section TUI configuration variables
+@cindex TUI configuration variables
+
+The TUI has several configuration variables that control the
+appearance of windows on the terminal.
+
+@table @code
+@item set tui-border-kind @var{kind}
+@kindex set tui-border-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.  The border is
+drawn using character line graphics if the terminal supports them.
+
+@end table
+
+@item set tui-active-border-mode @var{mode}
+@kindex set tui-active-border-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}
+@kindex set tui-border-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

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