RFA/doc: Add agent expressions chapter

RFA/doc: Add agent expressions chapter

[Daniel Jacobowitz]

We've got some nice documentation for all the tracepoint agent expressions
code, but we don't include it in the manual.  This patch adds that and fixes
a warning in the new chapter.  OK?

-- 
Daniel Jacobowitz                           Carnegie Mellon University
MontaVista Software                         Debian GNU/Linux Developer

2002-08-06  Daniel Jacobowitz  <drow@mvista.com>

	* Makefile.in (SFILES_INCLUDED): Add agentexpr.texi.
	* agentexpr.texi: Retitle section.  Comment out initialization.
	Factor a @var{}.
	* gdb.texinfo: Add Agent Expressions chapter.

Index: Makefile.in
===================================================================
RCS file: /cvs/src/src/gdb/doc/Makefile.in,v
retrieving revision 1.20
diff -u -p -r1.20 Makefile.in
--- Makefile.in	25 Feb 2002 04:32:58 -0000	1.20
+++ Makefile.in	6 Aug 2002 17:34:36 -0000
@@ -99,6 +99,7 @@ DVIPS = dvips
 # Main GDB manual's source files
 SFILES_INCLUDED = gdb-cfg.texi \
 	$(srcdir)/annotate.texi \
+	$(srcdir)/agentexpr.texi \
 	$(srcdir)/fdl.texi \
 	$(srcdir)/gpl.texi
 
Index: agentexpr.texi
===================================================================
RCS file: /cvs/src/src/gdb/doc/agentexpr.texi,v
retrieving revision 1.2
diff -u -p -r1.2 agentexpr.texi
--- agentexpr.texi	16 Feb 2000 04:11:25 -0000	1.2
+++ agentexpr.texi	6 Aug 2002 17:34:36 -0000
@@ -1,13 +1,13 @@
-\input texinfo
+@c \input texinfo
 @c %**start of header
-@setfilename agentexpr.info
-@settitle GDB Agent Expressions
-@setchapternewpage off
+@c @setfilename agentexpr.info
+@c @settitle GDB Agent Expressions
+@c @setchapternewpage off
 @c %**end of header
 
-Revision: $Id: agentexpr.texi,v 1.2 1998/12/09 21:23:46 jimb Exp $
+@c Revision: $Id: agentexpr.texi,v 1.2 1998/12/09 21:23:46 jimb Exp $
 
-@node The GDB Agent Expression Mechanism
+@node Agent Expressions
 @chapter The GDB Agent Expression Mechanism
 
 In some applications, it is not feasable for the debugger to interrupt
@@ -299,7 +299,7 @@ Pop two integers from the stack; let @va
 and @var{b} be the top value.  Shift @var{a} left by @var{b} bits, and
 push the result.
 
-@item @code{rsh_signed} (0x0a): @var{a} @var{b} @result{} @var{@code{(signed)}a>>b}
+@item @code{rsh_signed} (0x0a): @var{a} @var{b} @result{} @code{(signed)}@var{a>>b}
 Pop two integers from the stack; let @var{a} be the next-to-top value,
 and @var{b} be the top value.  Shift @var{a} right by @var{b} bits,
 inserting copies of the top bit at the high end, and push the result.
Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.107
diff -u -p -r1.107 gdb.texinfo
--- gdb.texinfo	3 Aug 2002 23:37:07 -0000	1.107
+++ gdb.texinfo	6 Aug 2002 17:34:40 -0000
@@ -146,6 +146,7 @@ Copyright (C) 1988-2002 Free Software Fo
 * Emacs::                       Using @value{GDBN} under @sc{gnu} Emacs
 * Annotations::                 @value{GDBN}'s annotation interface.
 * GDB/MI::                      @value{GDBN}'s Machine Interface.
+* Agent Expressions::           The GDB Agent Expression Mechanism
 
 * GDB Bugs::                    Reporting bugs in @value{GDBN}
 * Formatting Documentation::    How to format and print @value{GDBN} documentation
@@ -13539,6 +13540,7 @@ each value is printed in its own window.
 
 @include annotate.texi
 @include gdbmi.texinfo
+@include agentexpr.texi
 
 @node GDB Bugs
 @chapter Reporting Bugs in @value{GDBN}

Re: RFA/doc: Add agent expressions chapter

[Andrew Cagney]

> We've got some nice documentation for all the tracepoint agent expressions
> code, but we don't include it in the manual.  This patch adds that and fixes
> a warning in the new chapter.  OK?
> 
I wonder.  New chapter, new appendix (like the remote protocol), or part 
of gdbint?

Andrew

PS: gdb/157 :-)

Re: RFA/doc: Add agent expressions chapter

[Jim Blandy]

Andrew Cagney <ac131313@ges.redhat.com> writes:
> > We've got some nice documentation for all the tracepoint agent expressions
> > code, but we don't include it in the manual.  This patch adds that and fixes
> > a warning in the new chapter.  OK?
> >
> I wonder.  New chapter, new appendix (like the remote protocol), or
> part of gdbint?

The agent expression language is part of the interface between GDB and
a stub that implements tracepoints --- so it's a public interface, in
the same sense that the remote protocol is a public interface.  I
think it should go whereever the remote protocol docs go.

Re: RFA/doc: Add agent expressions chapter

[Daniel Jacobowitz]

On Tue, Aug 13, 2002 at 03:40:06PM -0500, Jim Blandy wrote:
> 
> Andrew Cagney <ac131313@ges.redhat.com> writes:
> > > We've got some nice documentation for all the tracepoint agent expressions
> > > code, but we don't include it in the manual.  This patch adds that and fixes
> > > a warning in the new chapter.  OK?
> > >
> > I wonder.  New chapter, new appendix (like the remote protocol), or
> > part of gdbint?
> 
> The agent expression language is part of the interface between GDB and
> a stub that implements tracepoints --- so it's a public interface, in
> the same sense that the remote protocol is a public interface.  I
> think it should go whereever the remote protocol docs go.

Got distracted, never finished this.  The consensus was to put this
after the Remote Protocol appendix, and turn it into an appendix just
like the remote protocol docs.  Here's a patch which does that; OK?

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

2003-06-21  Daniel Jacobowitz  <drow@mvista.com>

	* Makefile.in (SFILES_INCLUDED): Add agentexpr.texi.
	* agentexpr.texi: Retitle section, and change it to an appendix.
	Comment out texinfo initialization.  Factor a @var{} into two
	pieces to prevent makeinfo warnings.
	* gdb.texinfo: Add Agent Expressions appendix.

Index: doc/Makefile.in
===================================================================
RCS file: /cvs/src/src/gdb/doc/Makefile.in,v
retrieving revision 1.29
diff -u -p -r1.29 Makefile.in
--- doc/Makefile.in	10 May 2003 15:32:39 -0000	1.29
+++ doc/Makefile.in	21 Jun 2003 18:00:20 -0000
@@ -1,4 +1,4 @@
-##Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1999, 2000, 2002
+##Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1999, 2000, 2002, 2003
 ##Free Software Foundation, Inc.
 
 # Makefile for GDB documentation.
@@ -100,6 +100,7 @@ DVIPS = dvips
 GDB_DOC_SOURCE_INCLUDES = \
 	$(srcdir)/fdl.texi \
 	$(srcdir)/gpl.texi \
+	$(srcdir)/agentexpr.texi \
 	$(READLINE_DIR)/rluser.texinfo \
 	$(READLINE_DIR)/inc-hist.texinfo
 GDB_DOC_BUILD_INCLUDES = \
Index: doc/agentexpr.texi
===================================================================
RCS file: /cvs/src/src/gdb/doc/agentexpr.texi,v
retrieving revision 1.3
diff -u -p -r1.3 agentexpr.texi
--- doc/agentexpr.texi	20 Dec 2002 09:35:03 -0000	1.3
+++ doc/agentexpr.texi	21 Jun 2003 18:00:20 -0000
@@ -1,14 +1,14 @@
-\input texinfo
+@c \input texinfo
 @c %**start of header
-@setfilename agentexpr.info
-@settitle GDB Agent Expressions
-@setchapternewpage off
+@c @setfilename agentexpr.info
+@c @settitle GDB Agent Expressions
+@c @setchapternewpage off
 @c %**end of header
 
-Revision: $Id: agentexpr.texi,v 1.2 1998/12/09 21:23:46 jimb Exp $
+@c Revision: $Id: agentexpr.texi,v 1.2 1998/12/09 21:23:46 jimb Exp $
 
-@node The GDB Agent Expression Mechanism
-@chapter The GDB Agent Expression Mechanism
+@node Agent Expressions
+@appendix The GDB Agent Expression Mechanism
 
 In some applications, it is not feasable for the debugger to interrupt
 the program's execution long enough for the developer to learn anything
@@ -299,7 +299,7 @@ Pop two integers from the stack; let @va
 and @var{b} be the top value.  Shift @var{a} left by @var{b} bits, and
 push the result.
 
-@item @code{rsh_signed} (0x0a): @var{a} @var{b} @result{} @var{@code{(signed)}a>>b}
+@item @code{rsh_signed} (0x0a): @var{a} @var{b} @result{} @code{(signed)}@var{a>>b}
 Pop two integers from the stack; let @var{a} be the next-to-top value,
 and @var{b} be the top value.  Shift @var{a} right by @var{b} bits,
 inserting copies of the top bit at the high end, and push the result.
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.165
diff -u -p -r1.165 gdb.texinfo
--- doc/gdb.texinfo	19 Jun 2003 01:31:47 -0000	1.165
+++ doc/gdb.texinfo	21 Jun 2003 18:00:23 -0000
@@ -156,6 +156,7 @@ Copyright (C) 1988-2003 Free Software Fo
 * Installing GDB::              Installing GDB
 * Maintenance Commands::        Maintenance Commands
 * Remote Protocol::             GDB Remote Serial Protocol
+* Agent Expressions::           The GDB Agent Expression Mechanism
 * Copying::			GNU General Public License says
                                 how you can copy and share GDB
 * GNU Free Documentation License::  The license for this documentation
@@ -21719,6 +21720,8 @@ host is called:
 -> @code{X1234,6:XXXXXX}
 <- @code{T02}
 @end smallexample
+
+@include agentexpr.texi
 
 @include gpl.texi
 

Re: RFA/doc: Add agent expressions chapter

[Eli Zaretskii]

> Date: Sat, 21 Jun 2003 14:04:26 -0400
> From: Daniel Jacobowitz <drow@mvista.com>
> 
> Got distracted, never finished this.  The consensus was to put this
> after the Remote Protocol appendix, and turn it into an appendix just
> like the remote protocol docs.  Here's a patch which does that; OK?

Okay with me.  Thanks.