* annotate.texi: Change edition to 0.5 and date to May 1994.

	Add index.
	(Frames): New node, for frame annotation.
	(Displays): New node, for display annotation.

2 files changed, 295 insertions, 3 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 35c01ca..b17deb5 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,5 +1,10 @@
 Wed May  4 06:26:11 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
 
+	* annotate.texi: Change edition to 0.5 and date to May 1994.
+	Add index.
+	(Frames): New node, for frame annotation.
+	(Displays): New node, for display annotation.
+
 	* remote.texi (MIPS Remote): Say that set timeout doesn't apply
 	when waiting for your program to stop.
 
diff --git a/gdb/doc/annotate.texi b/gdb/doc/annotate.texi
index b05657f..e4f085b 100644
--- a/gdb/doc/annotate.texi
+++ b/gdb/doc/annotate.texi
@@ -5,8 +5,8 @@
 @setchapternewpage off
 @c %**end of header
 
-@set EDITION 0.4
-@set DATE April 1994
+@set EDITION 0.5
+@set DATE May 1994
 
 @ifinfo
 This file documents GDB annotations.
@@ -63,11 +63,15 @@ This is Edition @value{EDITION}, @value{DATE}.
 * General::             What annotations are; the general syntax.
 * Server::              Issuing a command without affecting user state.
 * Values::              Values are marked as such.
-* Prompting::           GDB annotations marking GDB's need for input.
+* Frames::              Stack frames are annotated.
+* Displays::            GDB can be told to display something periodically.
+* Prompting::           Annotations marking GDB's need for input.
 * Errors::              Annotations for error messages.
 * Breakpoint Info::     Information on breakpoints.
 * Invalidation::        Some annotations describe things now invalid.
+* Running::             Whether the program is running, how it stopped, etc.
 * Source::              Annotations describing source code.
+* Index::               Index
 @end menu
 @end ifinfo
 
@@ -132,6 +136,9 @@ use the @code{output} command instead of the @code{print} command.
 When a value is printed in various contexts, GDB uses annotations to
 delimit the value from the surrounding text.
 
+@findex value-history-begin
+@findex value-history-value
+@findex value-history-end
 If a value is printed using @code{print} and added to the value history,
 the annotation looks like
 
@@ -149,6 +156,8 @@ introduces the value to the user, @var{the-value} is the output
 corresponding to the value itself, and @var{value-flags} is @samp{*} for
 a value which can be dereferenced and @samp{-} for a value which cannot.
 
+@findex value-begin
+@findex value-end
 If the value is not added to the value history (it is an invalid float
 or it is printed with the @code{output} command), the annotation is similar:
 
@@ -158,6 +167,10 @@ or it is printed with the @code{output} command), the annotation is similar:
 ^Z^Zvalue-end
 @end example
 
+@findex arg-begin
+@findex arg-name-end
+@findex arg-value
+@findex arg-end
 When GDB prints an argument to a function (for example, in the output
 from the @code{backtrace} command), it annotates it as follows:
 
@@ -177,6 +190,10 @@ for the user's benefit (such as @samp{=}), and @var{value-flags} and
 @var{the-value} have the same meanings as in a
 @code{value-history-begin} annotation.
 
+@findex field-begin
+@findex field-name-end
+@findex field-value
+@findex field-end
 When printing a structure, GDB annotates it as follows:
 
 @example
@@ -205,6 +222,7 @@ annotated and @var{value-flags} has the same meaning as in a
 @code{value-history-begin} annotation.  This is followed by any number
 of elements, where is element can be either a single element:
 
+@findex elt
 @example
 @samp{,} @var{whitespace}         ; @r{omitted for the first element}
 @var{the-value}
@@ -213,6 +231,8 @@ of elements, where is element can be either a single element:
 
 or a repeated element
 
+@findex elt-rep
+@findex elt-rep-end
 @example
 @samp{,} @var{whitespace}         ; @r{omitted for the first element}
 @var{the-value}
@@ -228,6 +248,7 @@ consecutive array elements which contain that value, and
 @var{repetition-string} is a string which is designed to convey to the
 user that repitition is being depicted.
 
+@findex array-section-end
 Once all the array elements have been output, the array annotation is
 ended with
 
@@ -235,6 +256,172 @@ ended with
 ^Z^Zarray-section-end
 @end example
 
+@node Frames
+@chapter Frames
+
+Whenever GDB prints a frame, it annotates it.  For example, this applies
+to frames printed when GDB stops, output from commands such as
+@code{backtrace} or @code{up}, etc.
+
+@findex frame-begin
+The frame annotation begins with
+
+@example
+^Z^Zframe-begin @var{level} @var{address}
+@var{level-string}
+@end example
+
+where @var{level} is the number of the frame (0 is the innermost frame,
+and other frames have positive numbers), @var{address} is the address of
+the code executing in that frame, and @var{level-string} is a string
+designed to convey the level to the user.  The frame ends with
+
+@findex frame-end
+@example
+^Z^Zframe-end
+@end example
+
+Between these annotations is the main body of the frame, which can
+consist of
+
+@itemize @bullet
+@item
+@findex function-call
+@example
+^Z^Zfunction-call
+@var{function-call-string}
+@end example
+
+where @var{function-call-string} is text designed to convey to the user
+that this frame is associated with a function call made by GDB to a
+function in the program being debugged.
+
+@item
+@findex signal-handler-caller
+@example
+^Z^Zsignal-handler-caller
+@var{signal-handler-caller-string}
+@end example
+
+where @var{signal-handler-caller-string} is text designed to convey to
+the user that this frame is associated with whatever mechanism is used
+by this operating system to call a signal handler (it is the frame which
+calls the signal handler, not the frame for the signal handler itself).
+
+@item
+A normal frame.
+
+@findex frame-address
+@findex frame-address-end
+This can optionally (depending on whether this is thought of as
+interesting information for the user to see) begin with
+
+@example
+^Z^Zframe-address
+@var{address}
+^Z^Zframe-address-end
+@var{separator-string}
+@end example
+
+where @var{address} is the address executing in the frame (the same
+address as in the @code{frame-begin} annotation), and
+@var{separator-string} is a string intended to separate this address
+from what follows for the user's benefit.
+
+@findex frame-function-name
+@findex frame-args
+Then comes
+
+@example
+^Z^Zframe-function-name
+@var{function-name}
+^Z^Zframe-args
+@var{arguments}
+@end example
+
+where @var{function-name} is the name of the function executing in the
+frame, or @samp{??} if not known, and @var{arguments} are the arguments
+to the frame, with parentheses around them (each argument is annotated
+individually as well @pxref{Values}).
+
+@findex frame-source-begin
+@findex frame-source-file
+@findex frame-source-file-end
+@findex frame-source-line
+@findex frame-source-end
+If source information is available, a reference to it is then printed:
+
+@example
+^Z^Zframe-source-begin
+@var{source-intro-string}
+^Z^Zframe-source-file
+@var{filename}
+^Z^Zframe-source-file-end
+:
+^Z^Zframe-source-line
+@var{line-number}
+^Z^Zframe-source-end
+@end example
+
+where @var{source-intro-string} separates for the user's benefit the
+reference from the text which precedes it, @var{filename} is the name of
+the source file, and @var{line-number} is the line number within that
+file (the first line is line 1).
+
+@findex frame-where
+If GDB prints some information about where the frame is from (which
+library, which load segment, etc.; currently only done on the RS/6000),
+it is annotated with
+
+@example
+^Z^Zframe-where
+@var{information}
+@end example
+
+Then, if source is to actually be displayed for this frame (for example,
+this is not true for output from the @code{backtrace} command), then a
+@code{source} annotation (@pxref{Source}) is displayed.  Unlike most
+annotations, this is output instead of the normal text which would be
+output, not in addition.
+@end itemize
+
+@node Displays
+@chapter Displays
+
+@findex display-begin
+@findex display-number-end
+@findex display-format
+@findex display-expression
+@findex display-expression-end
+@findex display-value
+@findex display-end
+When GDB is told to display something using the @code{display} command,
+the results of the display are annotated:
+
+@example
+^Z^Zdisplay-begin
+@var{number}
+^Z^Zdisplay-number-end
+@var{number-separator}
+^Z^Zdisplay-format
+@var{format}
+^Z^Zdisplay-expression
+@var{expression}
+^Z^Zdisplay-expression-end
+@var{expression-separator}
+^Z^Zdisplay-value
+@var{value}
+^Z^Zdisplay-end
+@end example
+
+where @var{number} is the number of the display, @var{number-separator}
+is intended to separate the number from what follows for the user,
+@var{format} includes information such as the size, format, or other
+information about how the value is being displayed, @var{expression} is
+the expression being displayed, @var{expression-separator} is intended
+to separate the expression from the text that follows for the user,
+and @var{value} is the actual value being displayed.
+
 @node Prompting
 @chapter Annotation for GDB Input
 
@@ -259,19 +446,34 @@ features the following annotations:
 The input types are
 
 @table @code
+@findex pre-prompt
+@findex prompt
+@findex post-prompt
 @item prompt
 When GDB is prompting for a command (the main GDB prompt).
 
+@findex pre-commands
+@findex commands
+@findex post-commands
 @item commands
 When GDB prompts for a set of commands, like in the @code{commands}
 command.  The annotations are repeated for each command which is input.
 
+@findex pre-overload-choice
+@findex overload-choice
+@findex post-overload-choice
 @item overload-choice
 When GDB wants the user to select between various overloaded functions.
 
+@findex pre-query
+@findex query
+@findex post-query
 @item query
 When GDB wants the user to confirm a potentially dangerous operation.
 
+@findex pre-prompt-for-continue
+@findex prompt-for-continue
+@findex post-prompt-for-continue
 @item prompt-for-continue
 When GDB is asking the user to press return to continue.  Note: Don't
 expect this to work well; instead use @code{set height 0} to disable
@@ -282,12 +484,14 @@ presence of annotations.
 @node Errors
 @chapter Errors
 
+@findex quit
 @example
 ^Z^Zquit
 @end example
 
 This annotation occurs right before GDB responds to an interrupt.
 
+@findex error
 @example
 ^Z^Zerror
 @end example
@@ -302,6 +506,7 @@ cannot expect not to receive it either, however; an error annotation
 does not necessarily mean that GDB is immediately returning all the way
 to the top level.
 
+@findex error-begin
 A quit or error annotation may be preceded by
 
 @example
@@ -320,6 +525,8 @@ Warning messages are not yet annotated.
 
 The output from the @code{info breakpoints} command is annotated as follows:
 
+@findex breakpoints-headers
+@findex breakpoints-table
 @example
 ^Z^Zbreakpoints-headers
 @var{header-entry}
@@ -333,6 +540,8 @@ number of entries.  If a field does not apply for this entry, it is
 omitted.  Fields may contain trailing whitespace.  Each entry consists
 of:
 
+@findex record
+@findex field
 @example
 ^Z^Zrecord
 ^Z^Zfield 0
@@ -359,6 +568,7 @@ of:
 
 The output ends with
 
+@findex breakpoints-table-end
 @example
 ^Z^Zbreakpoints-table-end
 @end example
@@ -370,20 +580,92 @@ The following annotations say that certain pieces of state may have
 changed.
 
 @table @code
+@findex frames-invalid
 @item ^Z^Zframes-invalid
 
 The frames (for example, output from the @code{backtrace} command) may
 have changed.
 
+@findex breakpoints-invalid
 @item ^Z^Zbreakpoints-invalid
 
 The breakpoints may have changed.  For example, the user just added or
 deleted a breakpoint.
 @end table
 
+@node Running
+@chapter Running the Program
+
+@findex starting
+@findex stopping
+When the program starts executing due to a GDB command such as
+@code{step} or @code{continue}, 
+
+@example
+^Z^Zstarting
+@end example
+
+is output.  When the program stops, 
+
+@example
+^Z^Zstopped
+@end example
+
+is output.  Before the @code{stopped} annotation, a variety of
+annotations describe how the program stopped.
+
+@table @code
+@findex exited
+@item ^Z^Zexited @var{exit-status}
+The program exited, and @var{exit-status} is the exit status (zero for
+successful exit, otherwise nonzero).
+
+@findex signalled
+@findex signal-name
+@findex signal-name-end
+@findex signal-string
+@findex signal-string-end
+@item ^Z^Zsignalled
+The program exited with a signal.  After the @code{^Z^Zsignalled}, the
+annotation continues:
+
+@example
+@var{intro-text}
+^Z^Zsignal-name
+@var{name}
+^Z^Zsignal-name-end
+@var{middle-text}
+^Z^Zsignal-string
+@var{string}
+^Z^Zsignal-string-end
+@var{end-text}
+@end example
+
+where @var{name} is the name of the signal, such as @code{SIGILL} or
+@code{SIGSEGV}, and @var{string} is the explanation of the signal, such
+as @code{Illegal Instruction} or @code{Segmentation fault}.
+@var{intro-text}, @var{middle-text}, and @var{end-text} are for the
+user's benefit and have no particular format.
+
+@findex signal
+@item ^Z^Zsignal
+The syntax of this annotation is just like @code{signalled}, but GDB is
+just saying that the program received the signal, not that it was
+terminated with it.
+
+@findex breakpoint
+@item ^Z^Zbreakpoint @var{number}
+The program hit breakpoint number @var{number}.
+
+@findex watchpoint
+@item ^Z^Zwatchpoint @var{number}
+The program hit watchpoint number @var{number}.
+@end table
+
 @node Source
 @chapter Displaying Source
 
+@findex source
 The following annotation is used instead of displaying source code:
 
 @example
@@ -400,4 +682,9 @@ line, or @samp{beg} if @var{addr} is at the beginning of the line, and
 @var{addr} is the address in the target program associated with the
 source which is being displayed.
 
+@node Index
+@unnumbered Index
+
+@printindex fn
+
 @bye