* annotate.texi: New file, to document annotations.

3 files changed, 367 insertions, 0 deletions

diff --git a/gdb/doc/.Sanitize b/gdb/doc/.Sanitize
index a0786e6..6114a9e 100644
--- a/gdb/doc/.Sanitize
+++ b/gdb/doc/.Sanitize
@@ -32,6 +32,7 @@ ChangeLog
 Makefile.in
 a4rc.sed
 all-cfg.texi
+annotate.texi
 configure.in
 libgdb.texinfo
 gdb.texinfo
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index bac0d93..a8042b3 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,7 @@
+Thu Apr 28 07:44:28 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
+
+	* annotate.texi: New file, to document annotations.
+
 Thu Apr 21 14:20:51 1994  Jim Kingdon  (kingdon@lioth.cygnus.com)
 
 	* Makefile.in (clean): Don't remove GDBvn.texi (apparently on Jan
diff --git a/gdb/doc/annotate.texi b/gdb/doc/annotate.texi
index e69de29..d094534 100644
--- a/gdb/doc/annotate.texi
+++ b/gdb/doc/annotate.texi
@@ -0,0 +1,362 @@
+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename annotate.info
+@settitle GDB Annotations
+@setchapternewpage off
+@c %**end of header
+
+@set EDITION 0.4
+@set DATE April 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}
+@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
+relatively high level.
+
+This is Edition @value{EDITION}, @value{DATE}.
+
+@menu
+* 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.
+* Breakpoint Info::     Information on breakpoints.
+* Invalidation::        Some annotations describe things now invalid.
+* Source::              Annotations describing source code.
+@end menu
+@end ifinfo
+
+@node General
+@chapter What is an Annotation?
+
+To produce annotations, start GDB 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 GDB.  Currently there is no need
+for GDB 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:
+
+@example
+$ 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.
+
+^Z^Zpre-prompt
+(gdb) 
+^Z^Zprompt
+quit
+
+^Z^Zpost-prompt
+$ 
+@end example
+
+Here @samp{quit} is input to GDB; the rest is output from GDB.  The three
+lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
+character) are annotations; the rest is output from GDB.
+
+@node Server
+@chapter The Server Prefix
+
+To issue a command to GDB 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
+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
+
+When a value is printed in various contexts, GDB uses annotations to
+delimit the value from the surrounding text.
+
+If a value is printed using @code{print} and added to the value history,
+the annotation looks like
+
+@example
+^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 example
+
+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.
+
+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:
+
+@example
+^Z^Zvalue-begin @var{value-flags}
+@var{the-value}
+^Z^Zvalue-end
+@end example
+
+When GDB prints an argument to a function (for example, in the output
+from the @code{backtrace} command), it annotates it as follows:
+
+@example
+^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 example
+
+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.
+
+When printing a structure, GDB annotates it as follows:
+
+@example
+^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 example
+
+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, GDB annotates it as follows:
+
+@example
+^Z^Zarray-section-begin @var{array-index} @var{value-flags}
+@end example
+
+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:
+
+@example
+@samp{,} @var{whitespace}         ; @r{omitted for the first element}
+@var{the-value}
+^Z^Zelt
+@end example
+
+or a repeated element
+
+@example
+@samp{,} @var{whitespace}         ; @r{omitted for the first element}
+@var{the-value}
+^Z^Zelt-rep @var{number-of-repititions}
+@var{repetition-string}
+^Z^Zelt-rep-end
+@end example
+
+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-repititons} 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 repitition is being depicted.
+
+Once all the array elements have been output, the array annotation is
+ended with
+
+@example
+^Z^Zarray-section-end
+@end example
+
+@node Prompting
+@chapter Annotation for GDB Input
+
+When GDB 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:
+
+@example
+^Z^Zpre-prompt
+^Z^Zprompt
+^Z^Zpost-prompt
+@end example
+
+The input types are
+
+@table @code
+@item prompt
+When GDB is prompting for a command (the main GDB prompt).
+
+@item commands
+When GDB prompts for a set of commands, like in the @code{commands}
+command.
+
+@item overload-choice
+When GDB wants the user to select between various overloaded functions.
+
+@item query
+When GDB wants the user to confirm a potentially dangerous operation.
+
+@item prompt-for-continue
+When GDB is asking the user to press return to continue.
+@end table
+
+@node Breakpoint Info
+@chapter Information on Breakpoints
+
+The output from the @code{info breakpoints} command is annotated as follows:
+
+@example
+^Z^Zbreakpoints-headers
+@var{headers}
+^Z^Zbreakpoints-table
+@end example
+
+where @var{headers} is a string which is designed to convey to the user
+the order and significance of the fields.  This is followed by any
+number of entries.  Each entry beings with a @code{field 0} annotation.
+Some fields can be omitted if they don't apply for this entry.  Fields
+have trailing whitespace so that if they are printed in order in a
+fixed-width font, they match up with the headers.  The fields for an
+entry are:
+
+@example
+^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 example
+
+The output ends with
+
+@example
+^Z^Zbreakpoints-table-end
+@end example
+
+@node Invalidation
+@chapter Invalidation Notices
+
+The following annotations say that certain pieces of state may have
+changed.
+
+@table @code
+@item ^Z^Zframes-invalid
+
+The frames (for example, output from the @code{backtrace} command) may
+have changed.
+
+@item ^Z^Zbreakpoints-invalid
+
+The breakpoints may have changed.  For example, the user just added or
+deleted a breakpoint.
+@end table
+
+@node Source
+@chapter Displaying Source
+
+The following annotation is used instead of displaying source code:
+
+@example
+^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
+@end example
+
+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.
+
+@bye