* gdb.texinfo (main menu): Add Annotations.

	(File Options): Add @cindex entries for each command-line option.
	Document --epoch, --annotate, --async, --interpreter, --write,
	--statistics, and --version.

	* annotate.texi: Convert to a chapter.  Use @value{GDBN} instead
	of GDB.

1 files changed, 145 insertions, 123 deletions

diff --git a/gdb/doc/annotate.texi b/gdb/doc/annotate.texi
index 9d5850d..cd7cdf7 100644
--- a/gdb/doc/annotate.texi
+++ b/gdb/doc/annotate.texi
@@ -1,85 +1,93 @@
-\input texinfo   @c -*-texinfo-*-
-@c %**start of header
-@setfilename annotate.info
-@settitle GDB Annotations
-@setchapternewpage off
-@c %**end of header
-
-@set EDITION 0.5
-@set DATE May 1994
-
-@ifinfo
-This file documents GDB annotations.
-
-This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
-Annotations}.  Copyright 1994 Free Software Foundation
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions.
-@end ifinfo
-
-@titlepage
-@title GDB Annotations
-@subtitle Edition @value{EDITION}
-@subtitle @value{DATE}
-@author Cygnus Support
-@page
-@vskip 0pt plus 1filll
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Copyright @copyright{} 1994 Free Software Foundation
-@end titlepage
-
-@ifinfo
-@node Top
-@top GDB Annotations
-
-This file describes annotations in GDB, the GNU symbolic debugger.
-Annotations are designed to interface GDB to graphical user interfaces
-or other similar programs which want to interact with GDB at a
+@c  \input texinfo   @c -*-texinfo-*-
+@c  @c %**start of header
+@c  @setfilename annotate.info
+@c  @settitle GDB Annotations
+@c  @setchapternewpage off
+@c  @c %**end of header
+
+@c  @set EDITION 0.5
+@c  @set DATE May 1994
+
+@c  @ifinfo
+@c  This file documents GDB annotations.
+
+@c  This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
+@c  Annotations}.  Copyright 1994 Free Software Foundation
+
+@c  Permission is granted to make and distribute verbatim copies of
+@c  this manual provided the copyright notice and this permission notice
+@c  are preserved on all copies.
+@c  @end ignore
+
+@c  @ignore
+@c  Permission is granted to process this file through TeX and print the
+@c  results, provided the printed document carries copying permission
+@c  notice identical to this one except for the removal of this paragraph
+@c  (this paragraph not being relevant to the printed manual).
+
+@c  @end ignore
+@c  Permission is granted to copy and distribute modified versions of this
+@c  manual under the conditions for verbatim copying, provided also that the
+@c  entire resulting derived work is distributed under the terms of a
+@c  permission notice identical to this one.
+
+@c  Permission is granted to copy and distribute translations of this manual
+@c  into another language, under the above conditions for modified versions.
+@c  @end ifinfo
+
+@c  @titlepage
+@c  @title GDB Annotations
+@c  @subtitle Edition @value{EDITION}
+@c  @subtitle @value{DATE}
+@c  @author Cygnus Support
+@c  @page
+@c  @vskip 0pt plus 1filll
+@c  Permission is granted to make and distribute verbatim copies of
+@c  this manual provided the copyright notice and this permission notice
+@c  are preserved on all copies.
+
+@c  Copyright @copyright{} 1994 Free Software Foundation
+@c  @end titlepage
+
+@c  @ifinfo
+@c  @node Top
+@c  @top GDB Annotations
+
+@syncodeindex fn cp
+
+@node Annotations
+@chapter @value{GDBN} Annotations
+
+This chapter describes annotations in @value{GDBN}, the GNU symbolic debugger.
+Annotations are designed to interface @value{GDBN} to graphical user interfaces
+or other similar programs which want to interact with @value{GDBN} at a
 relatively high level.
 
+@ignore
 This is Edition @value{EDITION}, @value{DATE}.
+@end ignore
 
 @menu
-* General::             What annotations are; the general syntax.
-* Server::              Issuing a command without affecting user state.
-* Values::              Values are marked as such.
-* Frames::              Stack frames are annotated.
-* Displays::            GDB can be told to display something periodically.
-* Prompting::           Annotations marking GDB's need for input.
+* Annotations Overview::  What annotations are; the general syntax.
+* Server Prefix::       Issuing a command without affecting user state.
+* Value Annotations::   Values are marked as such.
+* Frame Annotations::   Stack frames are annotated.
+* Displays::            @value{GDBN} can be told to display something periodically.
+* Prompting::           Annotations marking @value{GDBN}'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.
+* Annotations for Running::
+                        Whether the program is running, how it stopped, etc.
+* Source Annotations::  Annotations describing source code.
 * TODO::                Annotations which might be added in the future.
-* Index::               Index
 @end menu
-@end ifinfo
 
-@node General
-@chapter What is an Annotation?
+@node Annotations Overview
+@section What is an Annotation?
+@cindex annotations
 
-To produce annotations, start GDB with the @code{--annotate=2} option.
+To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
 
 Annotations start with a newline character, two @samp{control-z}
 characters, and the name of the annotation.  If there is no additional
@@ -90,20 +98,22 @@ additional information, and a newline.  The additional information
 cannot contain newline characters.
 
 Any output not beginning with a newline and two @samp{control-z}
-characters denotes literal output from GDB.  Currently there is no need
-for GDB to output a newline followed by two @samp{control-z} characters,
+characters denotes literal output from @value{GDBN}.  Currently there is no need
+for @value{GDBN} to output a newline followed by two @samp{control-z} characters,
 but if there was such a need, the annotations could be extended with an
 @samp{escape} annotation which means those three characters as output.
 
-A simple example of starting up GDB with annotations is:
+A simple example of starting up @value{GDBN} with annotations is:
 
-@example
+@smallexample
 $ gdb --annotate=2
-GDB is free software and you are welcome to distribute copies of it
- under certain conditions; type "show copying" to see the conditions.
-There is absolutely no warranty for GDB; type "show warranty" for details.
-GDB 4.12.3 (sparc-sun-sunos4.1.3), 
-Copyright 1994 Free Software Foundation, Inc.
+GNU GDB 5.0
+Copyright 2000 Free Software Foundation, Inc.
+GDB is free software, covered by the GNU General Public License, and you are
+welcome to change it and/or distribute copies of it under certain conditions.
+Type "show copying" to see the conditions.
+There is absolutely no warranty for GDB.  Type "show warranty" for details.
+This GDB was configured as "sparc-sun-sunos4.1.3"
 
 ^Z^Zpre-prompt
 (gdb) 
@@ -112,29 +122,31 @@ quit
 
 ^Z^Zpost-prompt
 $ 
-@end example
+@end smallexample
 
-Here @samp{quit} is input to GDB; the rest is output from GDB.  The three
+Here @samp{quit} is input to @value{GDBN}; the rest is output from @value{GDBN}.  The three
 lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
-character) are annotations; the rest is output from GDB.
+character) are annotations; the rest is output from @value{GDBN}.
 
-@node Server
-@chapter The Server Prefix
+@node Server Prefix
+@section The Server Prefix
+@cindex server prefix for annotations
 
-To issue a command to GDB without affecting certain aspects of the state
+To issue a command to @value{GDBN} without affecting certain aspects of the state
 which is seen by users, prefix it with @samp{server }.  This means that
 this command will not affect the command history, nor will it affect
-GDB's notion of which command to repeat if @key{RET} is pressed on a
+@value{GDBN}'s notion of which command to repeat if @key{RET} is pressed on a
 line by itself.
 
 The server prefix does not affect the recording of values into the value
 history; to print a value without recording it into the value history,
 use the @code{output} command instead of the @code{print} command.
 
-@node Values
-@chapter Values
+@node Value Annotations
+@section Values
 
-When a value is printed in various contexts, GDB uses annotations to
+@cindex annotations for values
+When a value is printed in various contexts, @value{GDBN} uses annotations to
 delimit the value from the surrounding text.
 
 @findex value-history-begin
@@ -172,7 +184,7 @@ or it is printed with the @code{output} command), the annotation is similar:
 @findex arg-name-end
 @findex arg-value
 @findex arg-end
-When GDB prints an argument to a function (for example, in the output
+When @value{GDBN} prints an argument to a function (for example, in the output
 from the @code{backtrace} command), it annotates it as follows:
 
 @example
@@ -195,7 +207,7 @@ for the user's benefit (such as @samp{=}), and @var{value-flags} and
 @findex field-name-end
 @findex field-value
 @findex field-end
-When printing a structure, GDB annotates it as follows:
+When printing a structure, @value{GDBN} annotates it as follows:
 
 @example
 ^Z^Zfield-begin @var{value-flags}
@@ -212,7 +224,7 @@ is text which separates the name from the value 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.
 
-When printing an array, GDB annotates it as follows:
+When printing an array, @value{GDBN} annotates it as follows:
 
 @example
 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
@@ -257,11 +269,12 @@ ended with
 ^Z^Zarray-section-end
 @end example
 
-@node Frames
-@chapter Frames
+@node Frame Annotations
+@section Frames
 
-Whenever GDB prints a frame, it annotates it.  For example, this applies
-to frames printed when GDB stops, output from commands such as
+@cindex annotations for frames
+Whenever @value{GDBN} prints a frame, it annotates it.  For example, this applies
+to frames printed when @value{GDBN} stops, output from commands such as
 @code{backtrace} or @code{up}, etc.
 
 @findex frame-begin
@@ -296,7 +309,7 @@ consist of
 @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
+that this frame is associated with a function call made by @value{GDBN} to a
 function in the program being debugged.
 
 @item
@@ -347,7 +360,7 @@ Then comes
 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}).
+individually as well, @pxref{Value Annotations}).
 
 @findex frame-source-begin
 @findex frame-source-file
@@ -374,7 +387,7 @@ 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
+If @value{GDBN} 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
 
@@ -391,7 +404,7 @@ output, not in addition.
 @end itemize
 
 @node Displays
-@chapter Displays
+@section Displays
 
 @findex display-begin
 @findex display-number-end
@@ -400,7 +413,8 @@ output, not in addition.
 @findex display-expression-end
 @findex display-value
 @findex display-end
-When GDB is told to display something using the @code{display} command,
+@cindex annotations for display
+When @value{GDBN} is told to display something using the @code{display} command,
 the results of the display are annotated:
 
 @example
@@ -428,9 +442,10 @@ 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
+@section Annotation for @value{GDBN} Input
 
-When GDB prompts for input, it annotates this fact so it is possible
+@cindex annotations for prompts
+When @value{GDBN} prompts for input, it annotates this fact so it is possible
 to know when to send output, when the output from a given command is
 over, etc.
 
@@ -455,60 +470,61 @@ The input types are
 @findex prompt
 @findex post-prompt
 @item prompt
-When GDB is prompting for a command (the main GDB prompt).
+When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt).
 
 @findex pre-commands
 @findex commands
 @findex post-commands
 @item commands
-When GDB prompts for a set of commands, like in the @code{commands}
+When @value{GDBN} 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.
+When @value{GDBN} 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.
+When @value{GDBN} 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
+When @value{GDBN} 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
 prompting.  This is because the counting of lines is buggy in the
 presence of annotations.
 @end table
 
 @node Errors
-@chapter Errors
+@section Errors
+@cindex annotations for errors, warnings and interrupts
 
 @findex quit
 @example
 ^Z^Zquit
 @end example
 
-This annotation occurs right before GDB responds to an interrupt.
+This annotation occurs right before @value{GDBN} responds to an interrupt.
 
 @findex error
 @example
 ^Z^Zerror
 @end example
 
-This annotation occurs right before GDB responds to an error.
+This annotation occurs right before @value{GDBN} responds to an error.
 
-Quit and error annotations indicate that any annotations which GDB was
+Quit and error annotations indicate that any annotations which @value{GDBN} was
 in the middle of may end abruptly.  For example, if a
 @code{value-history-begin} annotation is followed by a @code{error}, one
 cannot expect to receive the matching @code{value-history-end}.  One
 cannot expect not to receive it either, however; an error annotation
-does not necessarily mean that GDB is immediately returning all the way
+does not necessarily mean that @value{GDBN} is immediately returning all the way
 to the top level.
 
 @findex error-begin
@@ -526,8 +542,9 @@ Warning messages are not yet annotated.
 @c range_error(), and possibly other places.
 
 @node Breakpoint Info
-@chapter Information on Breakpoints
+@section Information on Breakpoints
 
+@cindex annotations for breakpoints
 The output from the @code{info breakpoints} command is annotated as follows:
 
 @findex breakpoints-headers
@@ -582,8 +599,9 @@ The output ends with
 @end example
 
 @node Invalidation
-@chapter Invalidation Notices
+@section Invalidation Notices
 
+@cindex annotations for invalidation messages
 The following annotations say that certain pieces of state may have
 changed.
 
@@ -601,12 +619,13 @@ The breakpoints may have changed.  For example, the user just added or
 deleted a breakpoint.
 @end table
 
-@node Running
-@chapter Running the Program
+@node Annotations for Running
+@section Running the Program
+@cindex annotations for running programs
 
 @findex starting
 @findex stopping
-When the program starts executing due to a GDB command such as
+When the program starts executing due to a @value{GDBN} command such as
 @code{step} or @code{continue}, 
 
 @example
@@ -657,7 +676,7 @@ 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
+The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is
 just saying that the program received the signal, not that it was
 terminated with it.
 
@@ -670,8 +689,9 @@ The program hit breakpoint number @var{number}.
 The program hit watchpoint number @var{number}.
 @end table
 
-@node Source
-@chapter Displaying Source
+@node Source Annotations
+@section Displaying Source
+@cindex annotations for source display
 
 @findex source
 The following annotation is used instead of displaying source code:
@@ -693,7 +713,7 @@ followed by one or more lowercase hex digits (note that this does not
 depend on the language).
 
 @node TODO
-@chapter Annotations We Might Want in the Future
+@section Annotations We Might Want in the Future
 
 @format
     - target-invalid
@@ -709,9 +729,11 @@ depend on the language).
       notices.
 @end format
 
+@ignore
 @node Index
 @unnumbered Index
 
 @printindex fn
+@end ignore
 
-@bye
+@c @bye