This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
Re: [rfa:doco] Doco problems with level two annotations
Date: Tue, 29 Jul 2003 10:32:37 -0400
From: Andrew Cagney <ac131313@redhat.com>
>
> Okay with me, but don't we have to say that this manual has no
> invariant sections?
Ah! So that's how it works. Do you have an example text I can
copy/paste?
This is from Diffutils v2.8:
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no
Front-Cover Texts, and with no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
Thanks. Attached is what I've checked in (6.0 and mainline) - it even
includes a copy of the FDL now.
Andrew
2003-07-28 Andrew Cagney <cagney@redhat.com>
* Makefile.in (INFO_DEPS): Add annotate.info.
(dvi, ps, html, pdf): Add annotate.
(ANNOTATE_DOC_SOURCE_INCLUDES): New macro.
(ANNOTATE_DOC_BUILD_INCLUDES): New macro.
(ANNOTATE_DOC_FILES): New macro.
(ANNOTATE_TEX_TMPS): New macro.
(annotate.info, annotate_toc.html): Specify dependencies.
(annotate.ps, annotate.pdf, annotate.dvi): Ditto.
* annotate.texinfo: Rename annotate.texi. Get building. Add
"Migrating to GDB/MI" and "Limitations of the Annotation
Interface" chapters. Mention why it is not part of the user
guide. Update copyright notice. Include "fdl.texi".
Index: Makefile.in
===================================================================
RCS file: /cvs/src/src/gdb/doc/Makefile.in,v
retrieving revision 1.30
diff -u -r1.30 Makefile.in
--- Makefile.in 22 Jun 2003 04:27:23 -0000 1.30
+++ Makefile.in 30 Jul 2003 04:08:21 -0000
@@ -67,7 +67,7 @@
TEXINPUTS=${TEXIDIR}:.:$(srcdir):$(READLINE_DIR):$(GDBMI_DIR):$$TEXINPUTS
# Files which should be generated via 'info' and installed by 'install-info'
-INFO_DEPS = gdb.info gdbint.info stabs.info
+INFO_DEPS = gdb.info gdbint.info stabs.info annotate.info
# There may be alternate predefined collections of switches to configure
# the GDB manual. Normally this is not done in synch with the software
@@ -131,16 +131,26 @@
$(STABS_DOC_SOURCE_INCLUDES) \
$(STABS_DOC_BUILD_INCLUDES)
+# Annotate migration document
+ANNOTATE_DOC_SOURCE_INCLUDES = \
+ $(srcdir)/fdl.texi
+ANNOTATE_DOC_BUILD_INCLUDES = \
+ gdb-cfg.texi
+ANNOTATE_DOC_FILES = \
+ $(srcdir)/annotate.texinfo \
+ $(ANNOTATE_DOC_SOURCE_INCLUDES) \
+ $(ANNOTATE_DOC_BUILD_INCLUDES)
+
#### Host, target, and site specific Makefile fragments come in here.
###
all:
info: $(INFO_DEPS)
-dvi: gdb.dvi gdbint.dvi stabs.dvi refcard.dvi
-ps: gdb.ps gdbint.ps stabs.ps refcard.ps
-html: gdb_toc.html gdbint_toc.html stabs_toc.html
-pdf: gdb.pdf gdbint.pdf stabs.pdf
+dvi: gdb.dvi gdbint.dvi stabs.dvi refcard.dvi annotate.dvi
+ps: gdb.ps gdbint.ps stabs.ps refcard.ps annotate.ps
+html: gdb_toc.html gdbint_toc.html stabs_toc.html annotate.html
+pdf: gdb.pdf gdbint.pdf stabs.pdf annotate.pdf
all-doc: info dvi ps # pdf
diststuff: info
@@ -420,6 +430,30 @@
rm -f $(STABS_TEX_TMPS)
$(SET_TEXINPUTS) $(TEXI2DVI) --pdf $(srcdir)/stabs.texinfo
+# Clean these up before each run. Avoids a catch 22 with not being
+# able to re-generate these files (to fix a corruption) because these
+# files contain a corruption.
+ANNOTATE_TEX_TMPS = annotate.aux annotate.cp* annotate.fn* annotate.ky* \
+ annotate.log annotate.pg* annotate.toc annotate.tp* annotate.vr*
+
+# ANNOTATE DOCUMENTATION: TeX dvi file
+annotate.dvi : $(ANNOTATE_DOC_FILES)
+ rm -f $(ANNOTATE_TEX_TMPS)
+ $(SET_TEXINPUTS) $(TEXI2DVI) $(srcdir)/annotate.texinfo
+
+annotate.ps: annotate.dvi
+ $(DVIPS) -o $@ $?
+
+annotate.pdf: $(ANNOTATE_DOC_FILES)
+ rm -f $(ANNOTATE_TEX_TMPS)
+ $(SET_TEXINPUTS) $(TEXI2DVI) --pdf $(srcdir)/annotate.texinfo
+
+annotate.info: $(ANNOTATE_DOC_FILES)
+ $(MAKEINFO) -I $(srcdir) -o annotate.info $(srcdir)/annotate.texinfo
+
+annotate_toc.html: $(ANNOTATE_DOC_FILES)
+ $(MAKEHTML) $(MAKEHTMLFLAGS) $(srcdir)/annotate.texinfo
+
force:
Makefile: Makefile.in $(host_makefile_frag) $(target_makefile_frag) config.status
@@ -434,6 +468,7 @@
rm -f $(GDB_TEX_TMPS)
rm -f $(GDBINT_TEX_TMPS)
rm -f $(STABS_TEX_TMPS)
+ rm -f $(ANNOTATE_TEX_TMPS)
rm -f sedref.dvi sedref.tex tmp.sed
clean: mostlyclean
Index: annotate.texi
===================================================================
RCS file: annotate.texi
diff -N annotate.texi
--- annotate.texi 20 Dec 2002 09:35:03 -0000 1.12
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,741 +0,0 @@
-@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,1995,2000,2001 Free Software Foundation, Inc.
-
-@c Permission is granted to copy, distribute and/or modify this document
-@c under the terms of the GNU Free Documentation License, Version 1.1 or
-@c any later version published by the Free Software Foundation; with no
-@c Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
-@c and with the Back-Cover Texts as in (a) below.
-
-@c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-@c this GNU Manual, like GNU software. Copies published by the Free
-@c Software Foundation raise funds for GNU development.''
-@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,1995,2000,2001 Free Software Foundation
-@c @end titlepage
-
-@c @ifinfo
-@c @node Top
-@c @top GDB Annotations
-
-@c @syncodeindex fn cp
-
-@node Annotations
-@chapter @value{GDBN} Annotations
-
-This chapter describes annotations in @value{GDBN}. 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
-* 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.
-* 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.
-@end menu
-
-@node Annotations Overview
-@section What is an Annotation?
-@cindex annotations
-
-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
-information associated with this annotation, the name of the annotation
-is followed immediately by a newline. If there is additional
-information, the name of the annotation is followed by a space, the
-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 @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 @value{GDBN} with annotations is:
-
-@smallexample
-$ gdb --annotate=2
-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)
-^Z^Zprompt
-quit
-
-^Z^Zpost-prompt
-$
-@end smallexample
-
-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 @value{GDBN}.
-
-@node Server Prefix
-@section The Server Prefix
-@cindex server prefix for annotations
-
-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 @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 Value Annotations
-@section Values
-
-@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
-@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
-
-@smallexample
-^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
-@var{history-string}
-^Z^Zvalue-history-value
-@var{the-value}
-^Z^Zvalue-history-end
-@end smallexample
-
-@noindent
-where @var{history-number} is the number it is getting in the value
-history, @var{history-string} is a string, such as @samp{$5 = }, which
-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:
-
-@smallexample
-^Z^Zvalue-begin @var{value-flags}
-@var{the-value}
-^Z^Zvalue-end
-@end smallexample
-
-@findex arg-begin
-@findex arg-name-end
-@findex arg-value
-@findex arg-end
-When @value{GDBN} prints an argument to a function (for example, in the output
-from the @code{backtrace} command), it annotates it as follows:
-
-@smallexample
-^Z^Zarg-begin
-@var{argument-name}
-^Z^Zarg-name-end
-@var{separator-string}
-^Z^Zarg-value @var{value-flags}
-@var{the-value}
-^Z^Zarg-end
-@end smallexample
-
-@noindent
-where @var{argument-name} is the name of the argument,
-@var{separator-string} 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.
-
-@findex field-begin
-@findex field-name-end
-@findex field-value
-@findex field-end
-When printing a structure, @value{GDBN} annotates it as follows:
-
-@smallexample
-^Z^Zfield-begin @var{value-flags}
-@var{field-name}
-^Z^Zfield-name-end
-@var{separator-string}
-^Z^Zfield-value
-@var{the-value}
-^Z^Zfield-end
-@end smallexample
-
-@noindent
-where @var{field-name} is the name of the field, @var{separator-string}
-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, @value{GDBN} annotates it as follows:
-
-@smallexample
-^Z^Zarray-section-begin @var{array-index} @var{value-flags}
-@end smallexample
-
-@noindent
-where @var{array-index} is the index of the first element being
-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
-@smallexample
-@samp{,} @var{whitespace} ; @r{omitted for the first element}
-@var{the-value}
-^Z^Zelt
-@end smallexample
-
-or a repeated element
-
-@findex elt-rep
-@findex elt-rep-end
-@smallexample
-@samp{,} @var{whitespace} ; @r{omitted for the first element}
-@var{the-value}
-^Z^Zelt-rep @var{number-of-repetitions}
-@var{repetition-string}
-^Z^Zelt-rep-end
-@end smallexample
-
-In both cases, @var{the-value} is the output for the value of the
-element and @var{whitespace} can contain spaces, tabs, and newlines. In
-the repeated case, @var{number-of-repetitions} is the number of
-consecutive array elements which contain that value, and
-@var{repetition-string} is a string which is designed to convey to the
-user that repetition is being depicted.
-
-@findex array-section-end
-Once all the array elements have been output, the array annotation is
-ended with
-
-@smallexample
-^Z^Zarray-section-end
-@end smallexample
-
-@node Frame Annotations
-@section Frames
-
-@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
-The frame annotation begins with
-
-@smallexample
-^Z^Zframe-begin @var{level} @var{address}
-@var{level-string}
-@end smallexample
-
-@noindent
-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. @var{address} is in the form
-@samp{0x} followed by one or more lowercase hex digits (note that this
-does not depend on the language). The frame ends with
-
-@findex frame-end
-@smallexample
-^Z^Zframe-end
-@end smallexample
-
-Between these annotations is the main body of the frame, which can
-consist of
-
-@itemize @bullet
-@item
-@findex function-call
-@smallexample
-^Z^Zfunction-call
-@var{function-call-string}
-@end smallexample
-
-where @var{function-call-string} is text designed to convey to the user
-that this frame is associated with a function call made by @value{GDBN} to a
-function in the program being debugged.
-
-@item
-@findex signal-handler-caller
-@smallexample
-^Z^Zsignal-handler-caller
-@var{signal-handler-caller-string}
-@end smallexample
-
-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
-
-@smallexample
-^Z^Zframe-address
-@var{address}
-^Z^Zframe-address-end
-@var{separator-string}
-@end smallexample
-
-where @var{address} is the address executing in the frame (the same
-address as in the @code{frame-begin} annotation, but printed in a form
-which is intended for user consumption---in particular, the syntax varies
-depending on the language), 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
-
-@smallexample
-^Z^Zframe-function-name
-@var{function-name}
-^Z^Zframe-args
-@var{arguments}
-@end smallexample
-
-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{Value Annotations}).
-
-@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:
-
-@smallexample
-^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 smallexample
-
-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 @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
-
-@smallexample
-^Z^Zframe-where
-@var{information}
-@end smallexample
-
-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 Annotations}) is displayed. Unlike
-most annotations, this is output instead of the normal text which would be
-output, not in addition.
-@end itemize
-
-@node Displays
-@section Displays
-
-@findex display-begin
-@findex display-number-end
-@findex display-format
-@findex display-expression
-@findex display-expression-end
-@findex display-value
-@findex display-end
-@cindex annotations for display
-When @value{GDBN} is told to display something using the @code{display} command,
-the results of the display are annotated:
-
-@smallexample
-^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 smallexample
-
-@noindent
-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
-@section Annotation for @value{GDBN} Input
-
-@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.
-
-Different kinds of input each have a different @dfn{input type}. Each
-input type has three annotations: a @code{pre-} annotation, which
-denotes the beginning of any prompt which is being output, a plain
-annotation, which denotes the end of the prompt, and then a @code{post-}
-annotation which denotes the end of any echo which may (or may not) be
-associated with the input. For example, the @code{prompt} input type
-features the following annotations:
-
-@smallexample
-^Z^Zpre-prompt
-^Z^Zprompt
-^Z^Zpost-prompt
-@end smallexample
-
-The input types are
-
-@table @code
-@findex pre-prompt
-@findex prompt
-@findex post-prompt
-@item 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 @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 @value{GDBN} wants the user to select between various overloaded functions.
-
-@findex pre-query
-@findex query
-@findex post-query
-@item query
-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 @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
-@section Errors
-@cindex annotations for errors, warnings and interrupts
-
-@findex quit
-@smallexample
-^Z^Zquit
-@end smallexample
-
-This annotation occurs right before @value{GDBN} responds to an interrupt.
-
-@findex error
-@smallexample
-^Z^Zerror
-@end smallexample
-
-This annotation occurs right before @value{GDBN} responds to an error.
-
-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 @value{GDBN} is immediately returning all the way
-to the top level.
-
-@findex error-begin
-A quit or error annotation may be preceded by
-
-@smallexample
-^Z^Zerror-begin
-@end smallexample
-
-Any output between that and the quit or error annotation is the error
-message.
-
-Warning messages are not yet annotated.
-@c If we want to change that, need to fix warning(), type_error(),
-@c range_error(), and possibly other places.
-
-@node Breakpoint Info
-@section Information on Breakpoints
-
-@cindex annotations for breakpoints
-The output from the @code{info breakpoints} command is annotated as follows:
-
-@findex breakpoints-headers
-@findex breakpoints-table
-@smallexample
-^Z^Zbreakpoints-headers
-@var{header-entry}
-^Z^Zbreakpoints-table
-@end smallexample
-
-@noindent
-where @var{header-entry} has the same syntax as an entry (see below) but
-instead of containing data, it contains strings which are intended to
-convey the meaning of each field to the user. This is followed by any
-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
-@smallexample
-^Z^Zrecord
-^Z^Zfield 0
-@var{number}
-^Z^Zfield 1
-@var{type}
-^Z^Zfield 2
-@var{disposition}
-^Z^Zfield 3
-@var{enable}
-^Z^Zfield 4
-@var{address}
-^Z^Zfield 5
-@var{what}
-^Z^Zfield 6
-@var{frame}
-^Z^Zfield 7
-@var{condition}
-^Z^Zfield 8
-@var{ignore-count}
-^Z^Zfield 9
-@var{commands}
-@end smallexample
-
-Note that @var{address} is intended for user consumption---the syntax
-varies depending on the language.
-
-The output ends with
-
-@findex breakpoints-table-end
-@smallexample
-^Z^Zbreakpoints-table-end
-@end smallexample
-
-@node Invalidation
-@section Invalidation Notices
-
-@cindex annotations for invalidation messages
-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 Annotations for Running
-@section Running the Program
-@cindex annotations for running programs
-
-@findex starting
-@findex stopping
-When the program starts executing due to a @value{GDBN} command such as
-@code{step} or @code{continue},
-
-@smallexample
-^Z^Zstarting
-@end smallexample
-
-is output. When the program stops,
-
-@smallexample
-^Z^Zstopped
-@end smallexample
-
-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:
-
-@smallexample
-@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 smallexample
-
-@noindent
-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 @value{GDBN} 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 Annotations
-@section Displaying Source
-@cindex annotations for source display
-
-@findex source
-The following annotation is used instead of displaying source code:
-
-@smallexample
-^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
-@end smallexample
-
-where @var{filename} is an absolute file name indicating which source
-file, @var{line} is the line number within that file (where 1 is the
-first line in the file), @var{character} is the character position
-within the file (where 0 is the first character in the file) (for most
-debug formats this will necessarily point to the beginning of a line),
-@var{middle} is @samp{middle} if @var{addr} is in the middle of the
-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. @var{addr} is in the form @samp{0x}
-followed by one or more lowercase hex digits (note that this does not
-depend on the language).
-
-@node TODO
-@section Annotations We Might Want in the Future
-
-@format
- - target-invalid
- the target might have changed (registers, heap contents, or
- execution status). For performance, we might eventually want
- to hit `registers-invalid' and `all-registers-invalid' with
- greater precision
-
- - systematic annotation for set/show parameters (including
- invalidation notices).
-
- - similarly, `info' returns a list of candidates for invalidation
- notices.
-@end format
-
-@ignore
-@node Index
-@unnumbered Index
-
-@printindex fn
-@end ignore
-
-@c @bye
Index: annotate.texinfo
===================================================================
RCS file: annotate.texinfo
diff -N annotate.texinfo
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ annotate.texinfo 30 Jul 2003 04:08:22 -0000
@@ -0,0 +1,824 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename annotate.info
+@c
+@include gdb-cfg.texi
+@c
+@settitle @value{GDBN}'s Obsolete Annotations
+@setchapternewpage off
+@c %**end of header
+
+@set EDITION 1.0
+@set DATE July 2003
+
+@c NOTE: cagney/2003-07-28:
+@c Don't make this migration doccument an appendix of GDB's user guide.
+@c By keeping this separate, the size of the user guide is contained. If
+@c the user guide to get much bigger it would need to switch to a larger,
+@c more expensive, form factor and would drive up the manuals publication
+@c cost. Having a smaller cheaper manual helps the GNU Press with its sales.
+
+@ifinfo
+This file documents @value{GDBN}'s obsolete annotations.
+
+Copyright 1994, 1995, 2000, 2001, 2003 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+
+@end ifinfo
+
+@titlepage
+@title @value{GDBN}'s Obsolete Annotations
+@subtitle Edition @value{EDITION}
+@subtitle @value{DATE}
+@author Free Software Foundation
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1994, 1995, 2000, 2001, 2003 Free Software
+Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end titlepage
+
+@ifinfo
+@node Top
+@top GDB Annotations
+
+This document describes the obsolete level two annotation interface
+implemented in older @value{GDBN} versions.
+
+@ignore
+This is Edition @value{EDITION}, @value{DATE}.
+@end ignore
+@end ifinfo
+
+@menu
+* Annotations Overview:: What annotations are; the general syntax.
+* Limitations:: Limitations of the annotation interface.
+* Migrating to GDB/MI:: Migrating to GDB/MI
+* 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.
+* Annotations for Running::
+ Whether the program is running, how it stopped, etc.
+* Source Annotations:: Annotations describing source code.
+
+* GNU Free Documentation License::
+@end menu
+
+@contents
+
+@node Annotations Overview
+@chapter What is an Annotation?
+@cindex annotations
+
+To produce obsolete level two 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
+information associated with this annotation, the name of the annotation
+is followed immediately by a newline. If there is additional
+information, the name of the annotation is followed by a space, the
+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 @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 @value{GDBN} with annotations is:
+
+@smallexample
+$ gdb --annotate=2
+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)
+^Z^Zprompt
+quit
+
+^Z^Zpost-prompt
+$
+@end smallexample
+
+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 @value{GDBN}.
+
+@node Limitations
+@chapter Limitations of the Annotation Interface
+
+The level two annotations mechanism is known to have a number of
+technical and architectural limitations. As a consequence, in 2001,
+with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi},
+the annotation interface was marked as deprecated.
+
+This chapter discusses the known problems.
+
+@section Dependant on @sc{cli} output
+
+The annotation interface works by interspersing markups with
+@value{GDBN} normal command-line interpreter output. Unfortunatly, this
+makes the annotation client dependant on not just the annotations, but
+also the @sc{cli} output. This is because the client is forced to
+assume that specific @value{GDBN} commands provide specific information.
+Any change to @value{GDBN}'s @sc{cli} output modifies or removes that
+information and, consequently, likely breaks the client.
+
+Since the @sc{gdb/mi} output is independant of the @sc{cli}, it does not
+have this problem.
+
+@section Scalability
+
+The annotation interface relies on value annotations (@pxref{Value
+Annotations}) and the display mechanism as a way of obtaining up-to-date
+value information. These mechanisms are not scalable.
+
+In a graphical environment, where many values can be displayed
+simultaneously, a serious performance problem occurs when the client
+tries to first extract from @value{GDBN}, and then re-display, all those
+values. The client should instead only request and update the values
+that changed.
+
+The @sc{gdb/mi} Variable Objects provide just that mechanism.
+
+@section Correctness
+
+The annotation interface assumes that a variable's value can only be
+changed when the target is running. This assumption is not correct. A
+single assignment to a single variable can result in the entire target,
+and all displayed values, needing an update.
+
+The @sc{gdb/mi} Variable Objects include a mechanism for efficiently
+reporting such changes.
+
+@section Reliability
+
+The @sc{gdb/mi} interface includes a dedicated test directory
+(@file{gdb/gdb.mi}), and any addition or fix to @sc{gdb/mi} must include
+testsuite changes.
+
+@section Maintainability
+
+The annotation mechanism was implemented by interspersing @sc{cli} print
+statements with various annotations. As a consequence, any @sc{cli}
+output change can alter the annotation output.
+
+Since the @sc{gdb/mi} output is independant of the @sc{cli}, and the
+@sc{gdb/mi} is increasingly implemented independant of the @sc{cli}
+code, its long term maintenance is much easier.
+
+@node Migrating to GDB/MI
+@chapter Migrating to @sc{gdb/mi}
+
+By using the @samp{interp mi} command, it is possible for annotation
+clients to invoke @sc{gdb/mi} commands, and hence access the
+@sc{gdb/mi}. By doing this, existing annotation clients have a
+migration path from this obsolete interface to @sc{gdb/mi}.
+
+@node Server Prefix
+@chapter The Server Prefix
+@cindex server prefix for annotations
+
+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 @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 Value Annotations
+@chapter Values
+
+@emph{Value Annotations have been removed. @sc{gdb/mi} instead provides
+Variable Objects.}
+
+@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
+@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
+
+@smallexample
+^Z^Zvalue-history-begin @var{history-number} @var{value-flags}
+@var{history-string}
+^Z^Zvalue-history-value
+@var{the-value}
+^Z^Zvalue-history-end
+@end smallexample
+
+@noindent
+where @var{history-number} is the number it is getting in the value
+history, @var{history-string} is a string, such as @samp{$5 = }, which
+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:
+
+@smallexample
+^Z^Zvalue-begin @var{value-flags}
+@var{the-value}
+^Z^Zvalue-end
+@end smallexample
+
+@findex arg-begin
+@findex arg-name-end
+@findex arg-value
+@findex arg-end
+When @value{GDBN} prints an argument to a function (for example, in the output
+from the @code{backtrace} command), it annotates it as follows:
+
+@smallexample
+^Z^Zarg-begin
+@var{argument-name}
+^Z^Zarg-name-end
+@var{separator-string}
+^Z^Zarg-value @var{value-flags}
+@var{the-value}
+^Z^Zarg-end
+@end smallexample
+
+@noindent
+where @var{argument-name} is the name of the argument,
+@var{separator-string} 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.
+
+@findex field-begin
+@findex field-name-end
+@findex field-value
+@findex field-end
+When printing a structure, @value{GDBN} annotates it as follows:
+
+@smallexample
+^Z^Zfield-begin @var{value-flags}
+@var{field-name}
+^Z^Zfield-name-end
+@var{separator-string}
+^Z^Zfield-value
+@var{the-value}
+^Z^Zfield-end
+@end smallexample
+
+@noindent
+where @var{field-name} is the name of the field, @var{separator-string}
+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, @value{GDBN} annotates it as follows:
+
+@smallexample
+^Z^Zarray-section-begin @var{array-index} @var{value-flags}
+@end smallexample
+
+@noindent
+where @var{array-index} is the index of the first element being
+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
+@smallexample
+@samp{,} @var{whitespace} ; @r{omitted for the first element}
+@var{the-value}
+^Z^Zelt
+@end smallexample
+
+or a repeated element
+
+@findex elt-rep
+@findex elt-rep-end
+@smallexample
+@samp{,} @var{whitespace} ; @r{omitted for the first element}
+@var{the-value}
+^Z^Zelt-rep @var{number-of-repetitions}
+@var{repetition-string}
+^Z^Zelt-rep-end
+@end smallexample
+
+In both cases, @var{the-value} is the output for the value of the
+element and @var{whitespace} can contain spaces, tabs, and newlines. In
+the repeated case, @var{number-of-repetitions} is the number of
+consecutive array elements which contain that value, and
+@var{repetition-string} is a string which is designed to convey to the
+user that repetition is being depicted.
+
+@findex array-section-end
+Once all the array elements have been output, the array annotation is
+ended with
+
+@smallexample
+^Z^Zarray-section-end
+@end smallexample
+
+@node Frame Annotations
+@chapter Frames
+
+@emph{Value Annotations have been removed. @sc{gdb/mi} instead provides
+a number of frame commands.}
+
+@emph{Frame annotations are no longer available. The @sc{gdb/mi}
+provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and
+@samp{-stack-list-frames} commands.}
+
+@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
+The frame annotation begins with
+
+@smallexample
+^Z^Zframe-begin @var{level} @var{address}
+@var{level-string}
+@end smallexample
+
+@noindent
+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. @var{address} is in the form
+@samp{0x} followed by one or more lowercase hex digits (note that this
+does not depend on the language). The frame ends with
+
+@findex frame-end
+@smallexample
+^Z^Zframe-end
+@end smallexample
+
+Between these annotations is the main body of the frame, which can
+consist of
+
+@itemize @bullet
+@item
+@findex function-call
+@smallexample
+^Z^Zfunction-call
+@var{function-call-string}
+@end smallexample
+
+where @var{function-call-string} is text designed to convey to the user
+that this frame is associated with a function call made by @value{GDBN} to a
+function in the program being debugged.
+
+@item
+@findex signal-handler-caller
+@smallexample
+^Z^Zsignal-handler-caller
+@var{signal-handler-caller-string}
+@end smallexample
+
+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
+
+@smallexample
+^Z^Zframe-address
+@var{address}
+^Z^Zframe-address-end
+@var{separator-string}
+@end smallexample
+
+where @var{address} is the address executing in the frame (the same
+address as in the @code{frame-begin} annotation, but printed in a form
+which is intended for user consumption---in particular, the syntax varies
+depending on the language), 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
+
+@smallexample
+^Z^Zframe-function-name
+@var{function-name}
+^Z^Zframe-args
+@var{arguments}
+@end smallexample
+
+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{Value Annotations}).
+
+@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:
+
+@smallexample
+^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 smallexample
+
+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 @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
+
+@smallexample
+^Z^Zframe-where
+@var{information}
+@end smallexample
+
+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 Annotations}) 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
+
+@emph{Display Annotations have been removed. @sc{gdb/mi} instead
+provides Variable Objects.}
+
+@findex display-begin
+@findex display-number-end
+@findex display-format
+@findex display-expression
+@findex display-expression-end
+@findex display-value
+@findex display-end
+@cindex annotations for display
+When @value{GDBN} is told to display something using the @code{display} command,
+the results of the display are annotated:
+
+@smallexample
+^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 smallexample
+
+@noindent
+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 @value{GDBN} Input
+
+@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.
+
+Different kinds of input each have a different @dfn{input type}. Each
+input type has three annotations: a @code{pre-} annotation, which
+denotes the beginning of any prompt which is being output, a plain
+annotation, which denotes the end of the prompt, and then a @code{post-}
+annotation which denotes the end of any echo which may (or may not) be
+associated with the input. For example, the @code{prompt} input type
+features the following annotations:
+
+@smallexample
+^Z^Zpre-prompt
+^Z^Zprompt
+^Z^Zpost-prompt
+@end smallexample
+
+The input types are
+
+@table @code
+@findex pre-prompt
+@findex prompt
+@findex post-prompt
+@item 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 @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 @value{GDBN} wants the user to select between various overloaded functions.
+
+@findex pre-query
+@findex query
+@findex post-query
+@item query
+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 @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
+@cindex annotations for errors, warnings and interrupts
+
+@findex quit
+@smallexample
+^Z^Zquit
+@end smallexample
+
+This annotation occurs right before @value{GDBN} responds to an interrupt.
+
+@findex error
+@smallexample
+^Z^Zerror
+@end smallexample
+
+This annotation occurs right before @value{GDBN} responds to an error.
+
+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 @value{GDBN} is immediately returning all the way
+to the top level.
+
+@findex error-begin
+A quit or error annotation may be preceded by
+
+@smallexample
+^Z^Zerror-begin
+@end smallexample
+
+Any output between that and the quit or error annotation is the error
+message.
+
+Warning messages are not yet annotated.
+@c If we want to change that, need to fix warning(), type_error(),
+@c range_error(), and possibly other places.
+
+@node Breakpoint Info
+@chapter Information on Breakpoints
+
+@emph{Breakpoint Annotations have been removed. @sc{gdb/mi} instead
+provides breakpoint commands.}
+
+@cindex annotations for breakpoints
+The output from the @code{info breakpoints} command is annotated as follows:
+
+@findex breakpoints-headers
+@findex breakpoints-table
+@smallexample
+^Z^Zbreakpoints-headers
+@var{header-entry}
+^Z^Zbreakpoints-table
+@end smallexample
+
+@noindent
+where @var{header-entry} has the same syntax as an entry (see below) but
+instead of containing data, it contains strings which are intended to
+convey the meaning of each field to the user. This is followed by any
+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
+@smallexample
+^Z^Zrecord
+^Z^Zfield 0
+@var{number}
+^Z^Zfield 1
+@var{type}
+^Z^Zfield 2
+@var{disposition}
+^Z^Zfield 3
+@var{enable}
+^Z^Zfield 4
+@var{address}
+^Z^Zfield 5
+@var{what}
+^Z^Zfield 6
+@var{frame}
+^Z^Zfield 7
+@var{condition}
+^Z^Zfield 8
+@var{ignore-count}
+^Z^Zfield 9
+@var{commands}
+@end smallexample
+
+Note that @var{address} is intended for user consumption---the syntax
+varies depending on the language.
+
+The output ends with
+
+@findex breakpoints-table-end
+@smallexample
+^Z^Zbreakpoints-table-end
+@end smallexample
+
+@node Invalidation
+@chapter Invalidation Notices
+
+@cindex annotations for invalidation messages
+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 Annotations for Running
+@chapter Running the Program
+@cindex annotations for running programs
+
+@findex starting
+@findex stopping
+When the program starts executing due to a @value{GDBN} command such as
+@code{step} or @code{continue},
+
+@smallexample
+^Z^Zstarting
+@end smallexample
+
+is output. When the program stops,
+
+@smallexample
+^Z^Zstopped
+@end smallexample
+
+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:
+
+@smallexample
+@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 smallexample
+
+@noindent
+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 @value{GDBN} 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 Annotations
+@chapter Displaying Source
+@cindex annotations for source display
+
+@findex source
+The following annotation is used instead of displaying source code:
+
+@smallexample
+^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
+@end smallexample
+
+where @var{filename} is an absolute file name indicating which source
+file, @var{line} is the line number within that file (where 1 is the
+first line in the file), @var{character} is the character position
+within the file (where 0 is the first character in the file) (for most
+debug formats this will necessarily point to the beginning of a line),
+@var{middle} is @samp{middle} if @var{addr} is in the middle of the
+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. @var{addr} is in the form @samp{0x}
+followed by one or more lowercase hex digits (note that this does not
+depend on the language).
+
+@include fdl.texi
+
+@ignore
+@node Index
+@unnumbered Index
+
+@printindex fn
+@end ignore
+
+@bye