[rfa:doco] Doco problems with level two annotations

[Andrew Cagney <ac131313 at redhat dot com>]

Hello,

The attached updates the gdb/doc/annotate.texi file (renaming it to 
annotate.texinfo) so that it is a standalone document that:

- notes the limitations of level two annotations
- points the user at gdb/mi
- mentions the mi features that have replaced level two annotation 
functionality

ok?

Andrew
2003-05-16  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.

--- annotate.texi	Fri May 16 19:13:15 2003
+++ annotate.texinfo	Fri May 16 20:11:24 2003
@@ -1,64 +1,65 @@
-@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.
+\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 0.5
+@set DATE May 1994
+
+@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 the
+Invariant Sections being ``Free Software'' and ``Free Software Needs
+Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below.
+
+(a) The Free Software Foundation's Back-Cover Text is: ``You have
+freedom to copy and modify this GNU Manual, like GNU software.  Copies
+published by the Free Software Foundation raise funds for GNU
+development.''
+@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
+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, 1995, 2000, 2001, 2003 Free Software
+Foundation
+@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.
@@ -70,14 +71,16 @@
 * 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
 
+@contents
+
 @node Annotations Overview
-@section What is an Annotation?
+@chapter What is an Annotation?
 @cindex annotations
 
-To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
+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
@@ -122,8 +125,79 @@
 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 occures 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
-@section The Server Prefix
+@chapter The Server Prefix
 @cindex server prefix for annotations
 
 To issue a command to @value{GDBN} without affecting certain aspects of
@@ -137,7 +211,10 @@
 use the @code{output} command instead of the @code{print} command.
 
 @node Value Annotations
-@section Values
+@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
@@ -268,7 +345,14 @@
 @end smallexample
 
 @node Frame Annotations
-@section Frames
+@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
@@ -403,7 +487,10 @@
 @end itemize
 
 @node Displays
-@section Displays
+@chapter Displays
+
+@emph{Display Annotations have been removed.  @sc{gdb/mi} instead
+provides Variable Objects.}
 
 @findex display-begin
 @findex display-number-end
@@ -442,7 +529,7 @@
 and @var{value} is the actual value being displayed.
 
 @node Prompting
-@section Annotation for @value{GDBN} Input
+@chapter Annotation for @value{GDBN} Input
 
 @cindex annotations for prompts
 When @value{GDBN} prompts for input, it annotates this fact so it is possible
@@ -502,7 +589,7 @@
 @end table
 
 @node Errors
-@section Errors
+@chapter Errors
 @cindex annotations for errors, warnings and interrupts
 
 @findex quit
@@ -542,7 +629,10 @@
 @c range_error(), and possibly other places.
 
 @node Breakpoint Info
-@section Information on Breakpoints
+@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:
@@ -600,7 +690,7 @@
 @end smallexample
 
 @node Invalidation
-@section Invalidation Notices
+@chapter Invalidation Notices
 
 @cindex annotations for invalidation messages
 The following annotations say that certain pieces of state may have
@@ -621,7 +711,7 @@
 @end table
 
 @node Annotations for Running
-@section Running the Program
+@chapter Running the Program
 @cindex annotations for running programs
 
 @findex starting
@@ -692,7 +782,7 @@
 @end table
 
 @node Source Annotations
-@section Displaying Source
+@chapter Displaying Source
 @cindex annotations for source display
 
 @findex source
@@ -714,23 +804,6 @@
 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
@@ -738,4 +811,4 @@
 @printindex fn
 @end ignore
 
-@c @bye
+@bye