* gdb.texinfo: Update dates, bump to Eighth Edition (note

expectation of additional changes before release), update
	ISBN, add copy of top-level menu for @ifhtml, remove explicit
	node links, rephrase and/or shorten lines to fix formatting
	problem in both regular and @smallbook formats.
	* annotate.texi: Shorten lines in example, use smallexample
	consistently everywhere.
	* Makefile.in: Add comment about texinfo 4.0 html generation.
	(SFILES_INCLUDED): Add annotate.texi.

gdb/doc/ChangeLog

@@ -1,3 +1,15 @@
+2000-03-28  Stan Shebs  <shebs@apple.com>
+
+	* gdb.texinfo: Update dates, bump to Eighth Edition (note
+	expectation of additional changes before release), update
+	ISBN, add copy of top-level menu for @ifhtml, remove explicit
+	node links, rephrase and/or shorten lines to fix formatting
+	problem in both regular and @smallbook formats.
+	* annotate.texi: Shorten lines in example, use smallexample
+	consistently everywhere.
+	* Makefile.in: Add comment about texinfo 4.0 html generation.
+	(SFILES_INCLUDED): Add annotate.texi.
+
 2000-03-27  Daniel Berlin  <dan@cgsoftware.com>
 
         * gdb.texinfo (Debugging Output): Added new section, documenting

gdb/doc/Makefile.in

@@ -40,6 +40,10 @@ TEXIDIR=${gdbdir}/../texinfo
 # where to find makeinfo, preferably one designed for texinfo-2
 MAKEINFO=makeinfo
 
+# Note that texinfo 4.0's makeinfo --html can only generate a
+# single file, which would be too large, so continue to use
+# texi2html. -sts 2000-03-28
+
 MAKEHTML = texi2html
 MAKEHTMLFLAGS = -glossary -menu -split_chapter
 
@@ -83,7 +87,7 @@ TEXINDEX = texindex
 DVIPS = dvips
 
 # Main GDB manual's source files
-SFILES_INCLUDED = gdb-cfg.texi
+SFILES_INCLUDED = gdb-cfg.texi $(srcdir)/annotate.texi
 
 SFILES_LOCAL = $(srcdir)/gdb.texinfo GDBvn.texi $(SFILES_INCLUDED)
 

gdb/doc/annotate.texi

@@ -60,9 +60,9 @@
 @chapter @value{GDBN} Annotations
 @end ifclear
 
-This chapter describes annotations in @value{GDBN}, the GNU symbolic debugger.
+This chapter describes annotations in @value{GDBN}.  Annotations are
-Annotations are designed to interface @value{GDBN} to graphical user interfaces
+designed to interface @value{GDBN} to graphical user interfaces or other
-or other similar programs which want to interact with @value{GDBN} at a
+similar programs which want to interact with @value{GDBN} at a
 relatively high level.
 
 @ignore
@@ -100,10 +100,11 @@ 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
+characters denotes literal output from @value{GDBN}.  Currently there is
-for @value{GDBN} to output a newline followed by two @samp{control-z} characters,
+no need for @value{GDBN} to output a newline followed by two
-but if there was such a need, the annotations could be extended with an
+@samp{control-z} characters, but if there was such a need, the
-@samp{escape} annotation which means those three characters as output.
+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:
 
@@ -111,10 +112,12 @@ A simple example of starting up @value{GDBN} with annotations is:
 $ 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
+GDB is free software, covered by the GNU General Public License,
-welcome to change it and/or distribute copies of it under certain conditions.
+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.
+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
@@ -126,19 +129,20 @@ quit
 $ 
 @end smallexample
 
-Here @samp{quit} is input to @value{GDBN}; the rest is output from @value{GDBN}.  The three
+Here @samp{quit} is input to @value{GDBN}; the rest is output from
-lines beginning @samp{^Z^Z} (where @samp{^Z} denotes a @samp{control-z}
+@value{GDBN}.  The three lines beginning @samp{^Z^Z} (where @samp{^Z}
-character) are annotations; the rest is output from @value{GDBN}.
+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
+To issue a command to @value{GDBN} without affecting certain aspects of
-which is seen by users, prefix it with @samp{server }.  This means that
+the state which is seen by users, prefix it with @samp{server }.  This
-this command will not affect the command history, nor will it affect
+means that this command will not affect the command history, nor will it
-@value{GDBN}'s notion of which command to repeat if @key{RET} is pressed on a
+affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
-line by itself.
+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,
@@ -148,8 +152,8 @@ use the @code{output} command instead of the @code{print} command.
 @section Values
 
 @cindex annotations for values
-When a value is printed in various contexts, @value{GDBN} uses annotations to
+When a value is printed in various contexts, @value{GDBN} uses
-delimit the value from the surrounding text.
+annotations to delimit the value from the surrounding text.
 
 @findex value-history-begin
 @findex value-history-value
@@ -157,13 +161,13 @@ 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
+@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 example
+@end smallexample
 
 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
@@ -176,11 +180,11 @@ 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
+@smallexample
 ^Z^Zvalue-begin @var{value-flags}
 @var{the-value}
 ^Z^Zvalue-end
-@end example
+@end smallexample
 
 @findex arg-begin
 @findex arg-name-end
@@ -189,7 +193,7 @@ or it is printed with the @code{output} command), the annotation is similar:
 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
+@smallexample
 ^Z^Zarg-begin
 @var{argument-name}
 ^Z^Zarg-name-end
@@ -197,7 +201,7 @@ from the @code{backtrace} command), it annotates it as follows:
 ^Z^Zarg-value @var{value-flags}
 @var{the-value}
 ^Z^Zarg-end
-@end example
+@end smallexample
 
 where @var{argument-name} is the name of the argument,
 @var{separator-string} is text which separates the name from the value
@@ -211,7 +215,7 @@ for the user's benefit (such as @samp{=}), and @var{value-flags} and
 @findex field-end
 When printing a structure, @value{GDBN} annotates it as follows:
 
-@example
+@smallexample
 ^Z^Zfield-begin @var{value-flags}
 @var{field-name}
 ^Z^Zfield-name-end
@@ -219,7 +223,7 @@ When printing a structure, @value{GDBN} annotates it as follows:
 ^Z^Zfield-value
 @var{the-value}
 ^Z^Zfield-end
-@end example
+@end smallexample
 
 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
@@ -228,9 +232,9 @@ same meanings as in a @code{value-history-begin} annotation.
 
 When printing an array, @value{GDBN} annotates it as follows:
 
-@example
+@smallexample
 ^Z^Zarray-section-begin @var{array-index} @var{value-flags}
-@end example
+@end smallexample
 
 where @var{array-index} is the index of the first element being
 annotated and @var{value-flags} has the same meaning as in a
@@ -238,23 +242,23 @@ annotated and @var{value-flags} has the same meaning as in a
 of elements, where is element can be either a single element:
 
 @findex elt
-@example
+@smallexample
 @samp{,} @var{whitespace}         ; @r{omitted for the first element}
 @var{the-value}
 ^Z^Zelt
-@end example
+@end smallexample
 
 or a repeated element
 
 @findex elt-rep
 @findex elt-rep-end
-@example
+@smallexample
 @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
+@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
@@ -267,9 +271,9 @@ user that repitition is being depicted.
 Once all the array elements have been output, the array annotation is
 ended with
 
-@example
+@smallexample
 ^Z^Zarray-section-end
-@end example
+@end smallexample
 
 @node Frame Annotations
 @section Frames
@@ -282,10 +286,10 @@ to frames printed when @value{GDBN} stops, output from commands such as
 @findex frame-begin
 The frame annotation begins with
 
-@example
+@smallexample
 ^Z^Zframe-begin @var{level} @var{address}
 @var{level-string}
-@end example
+@end smallexample
 
 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
@@ -295,9 +299,9 @@ designed to convey the level to the user.  @var{address} is in the form
 does not depend on the language).  The frame ends with
 
 @findex frame-end
-@example
+@smallexample
 ^Z^Zframe-end
-@end example
+@end smallexample
 
 Between these annotations is the main body of the frame, which can
 consist of
@@ -305,10 +309,10 @@ consist of
 @itemize @bullet
 @item
 @findex function-call
-@example
+@smallexample
 ^Z^Zfunction-call
 @var{function-call-string}
-@end example
+@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
@@ -316,10 +320,10 @@ function in the program being debugged.
 
 @item
 @findex signal-handler-caller
-@example
+@smallexample
 ^Z^Zsignal-handler-caller
 @var{signal-handler-caller-string}
-@end example
+@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
@@ -334,12 +338,12 @@ A normal frame.
 This can optionally (depending on whether this is thought of as
 interesting information for the user to see) begin with
 
-@example
+@smallexample
 ^Z^Zframe-address
 @var{address}
 ^Z^Zframe-address-end
 @var{separator-string}
-@end example
+@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
@@ -352,12 +356,12 @@ benefit.
 @findex frame-args
 Then comes
 
-@example
+@smallexample
 ^Z^Zframe-function-name
 @var{function-name}
 ^Z^Zframe-args
 @var{arguments}
-@end example
+@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
@@ -371,7 +375,7 @@ individually as well, @pxref{Value Annotations}).
 @findex frame-source-end
 If source information is available, a reference to it is then printed:
 
-@example
+@smallexample
 ^Z^Zframe-source-begin
 @var{source-intro-string}
 ^Z^Zframe-source-file
@@ -381,7 +385,7 @@ If source information is available, a reference to it is then printed:
 ^Z^Zframe-source-line
 @var{line-number}
 ^Z^Zframe-source-end
-@end example
+@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
@@ -393,10 +397,10 @@ 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
 
-@example
+@smallexample
 ^Z^Zframe-where
 @var{information}
-@end example
+@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
@@ -419,7 +423,7 @@ output, not in addition.
 When @value{GDBN} is told to display something using the @code{display} command,
 the results of the display are annotated:
 
-@example
+@smallexample
 ^Z^Zdisplay-begin
 @var{number}
 ^Z^Zdisplay-number-end
@@ -433,7 +437,7 @@ the results of the display are annotated:
 ^Z^Zdisplay-value
 @var{value}
 ^Z^Zdisplay-end
-@end example
+@end smallexample
 
 where @var{number} is the number of the display, @var{number-separator}
 is intended to separate the number from what follows for the user,
@@ -459,11 +463,11 @@ 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
+@smallexample
 ^Z^Zpre-prompt
 ^Z^Zprompt
 ^Z^Zpost-prompt
-@end example
+@end smallexample
 
 The input types are
 
@@ -508,16 +512,16 @@ presence of annotations.
 @cindex annotations for errors, warnings and interrupts
 
 @findex quit
-@example
+@smallexample
 ^Z^Zquit
-@end example
+@end smallexample
 
 This annotation occurs right before @value{GDBN} responds to an interrupt.
 
 @findex error
-@example
+@smallexample
 ^Z^Zerror
-@end example
+@end smallexample
 
 This annotation occurs right before @value{GDBN} responds to an error.
 
@@ -532,9 +536,9 @@ to the top level.
 @findex error-begin
 A quit or error annotation may be preceded by
 
-@example
+@smallexample
 ^Z^Zerror-begin
-@end example
+@end smallexample
 
 Any output between that and the quit or error annotation is the error
 message.
@@ -551,11 +555,11 @@ The output from the @code{info breakpoints} command is annotated as follows:
 
 @findex breakpoints-headers
 @findex breakpoints-table
-@example
+@smallexample
 ^Z^Zbreakpoints-headers
 @var{header-entry}
 ^Z^Zbreakpoints-table
-@end example
+@end smallexample
 
 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
@@ -566,7 +570,7 @@ of:
 
 @findex record
 @findex field
-@example
+@smallexample
 ^Z^Zrecord
 ^Z^Zfield 0
 @var{number}
@@ -588,7 +592,7 @@ of:
 @var{ignore-count}
 ^Z^Zfield 9
 @var{commands}
-@end example
+@end smallexample
 
 Note that @var{address} is intended for user consumption---the syntax
 varies depending on the language.
@@ -596,9 +600,9 @@ varies depending on the language.
 The output ends with
 
 @findex breakpoints-table-end
-@example
+@smallexample
 ^Z^Zbreakpoints-table-end
-@end example
+@end smallexample
 
 @node Invalidation
 @section Invalidation Notices
@@ -630,15 +634,15 @@ deleted a breakpoint.
 When the program starts executing due to a @value{GDBN} command such as
 @code{step} or @code{continue}, 
 
-@example
+@smallexample
 ^Z^Zstarting
-@end example
+@end smallexample
 
 is output.  When the program stops, 
 
-@example
+@smallexample
 ^Z^Zstopped
-@end example
+@end smallexample
 
 is output.  Before the @code{stopped} annotation, a variety of
 annotations describe how the program stopped.
@@ -658,7 +662,7 @@ successful exit, otherwise nonzero).
 The program exited with a signal.  After the @code{^Z^Zsignalled}, the
 annotation continues:
 
-@example
+@smallexample
 @var{intro-text}
 ^Z^Zsignal-name
 @var{name}
@@ -668,7 +672,7 @@ annotation continues:
 @var{string}
 ^Z^Zsignal-string-end
 @var{end-text}
-@end example
+@end smallexample
 
 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
@@ -698,9 +702,9 @@ The program hit watchpoint number @var{number}.
 @findex source
 The following annotation is used instead of displaying source code:
 
-@example
+@smallexample
 ^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr}
-@end example
+@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