First stage of doing GOOBE improvements to documentation now that the html generation works

1 files changed, 187 insertions, 187 deletions

diff --git a/doc/CrtTrace.3 b/doc/CrtTrace.3
index 63db967..80d2b47 100644
--- a/doc/CrtTrace.3
+++ b/doc/CrtTrace.3
@@ -1,187 +1,187 @@
-'\"
-'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\" Copyright (c) 2002 by Kevin B. Kenny.  All rights reserved.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: CrtTrace.3,v 1.10 2004/10/07 15:37:43 dkf Exp $
-'\" 
-.so man.macros
-.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
-.BS
-.SH NAME
-Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-Tcl_Trace
-\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)
-.sp
-Tcl_Trace
-\fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR)
-.sp
-\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
-.SH ARGUMENTS
-.AS Tcl_CmdObjTraceDeleteProc *deleteProc
-.AP Tcl_Interp *interp in
-Interpreter containing command to be traced or untraced.
-.AP int level in
-Only commands at or below this nesting level will be traced unless
-0 is specified.  1 means
-top-level commands only, 2 means top-level commands or those that are
-invoked as immediate consequences of executing top-level commands
-(procedure bodies, bracketed commands, etc.) and so on.
-A value of 0 means that commands at any level are traced.
-.AP int flags in
-Flags governing the trace execution.  See below for details.
-.AP Tcl_CmdObjTraceProc *objProc in
-Procedure to call for each command that's executed.  See below for
-details of the calling sequence.
-.AP Tcl_CmdTraceProc *proc in
-Procedure to call for each command that's executed.  See below for
-details on the calling sequence.
-.AP ClientData clientData in
-Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
-.AP Tcl_CmdObjTraceDeleteProc *deleteProc in
-Procedure to call when the trace is deleted.  See below for details of
-the calling sequence.  A NULL pointer is permissible and results in no
-callback when the trace is deleted.
-.AP Tcl_Trace trace in
-Token for trace to be removed (return value from previous call
-to \fBTcl_CreateTrace\fR).
-.BE
-.SH DESCRIPTION
-.PP
-\fBTcl_CreateObjTrace\fR arranges for command tracing.  After it is
-called, \fIobjProc\fR will be invoked before the Tcl interpreter calls
-any command procedure when evaluating commands in \fIinterp\fR.
-The return value from \fBTcl_CreateObjTrace\fR is a token for the trace,
-which may be passed to \fBTcl_DeleteTrace\fR to remove the trace.
-There may be many traces in effect simultaneously for the same
-interpreter.
-.PP
-\fIobjProc\fR should have arguments and result that match the type,
-\fBTcl_CmdObjTraceProc\fR:
-.CS
-typedef int \fBTcl_CmdObjTraceProc\fR( 
-        \fBClientData\fR \fIclientData\fR,
-        \fBTcl_Interp\fR* \fIinterp\fR,
-        int \fIlevel\fR,
-        const char *\fIcommand\fR,
-        \fBTcl_Command\fR \fIcommandToken\fR,
-        int \fIobjc\fR,
-        \fBTcl_Obj\fR *const \fIobjv\fR[] );
-.CE
-The \fIclientData\fR and \fIinterp\fR parameters are copies of the
-corresponding arguments given to \fBTcl_CreateTrace\fR.
-\fIClientData\fR typically points to an application-specific data
-structure that describes what to do when \fIobjProc\fR is invoked.  The
-\fIlevel\fR parameter gives the nesting level of the command (1 for
-top-level commands passed to \fBTcl_Eval\fR by the application, 2 for
-the next-level commands passed to \fBTcl_Eval\fR as part of parsing or
-interpreting level-1 commands, and so on). The \fIcommand\fR parameter
-points to a string containing the text of the command, before any
-argument substitution.  The \fIcommandToken\fR parameter is a Tcl
-command token that identifies the command to be invoked.  The token
-may be passed to \fBTcl_GetCommandName\fR,
-\fBTcl_GetCommandTokenInfo\fR, or \fBTcl_SetCommandTokenInfo\fR to
-manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR
-parameters designate the final parameter count and parameter vector
-that will be passed to the command, and have had all substitutions
-performed.
-.PP
-The \fIobjProc\fR callback is expected to return a standard Tcl status
-return code.  If this code is \fBTCL_OK\fR (the normal case), then
-the Tcl interpreter will invoke the command.  Any other return code
-is treated as if the command returned that status, and the command is
-\fInot\fR invoked.
-.PP
-The \fIobjProc\fR callback must not modify \fIobjv\fR in any way.  It
-is, however, permissible to change the command by calling
-\fBTcl_SetCommandTokenInfo\fR prior to returning.  Any such change
-takes effect immediately, and the command is invoked with the new
-information.
-.PP
-Tracing will only occur for commands at nesting level less than
-or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
-parameter to \fIobjProc\fR will always be less than or equal to the
-\fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
-.PP
-Tracing has a significant effect on runtime performance because it
-causes the bytecode compiler to refrain from generating in-line code
-for Tcl commands such as \fBif\fR and \fBwhile\fR in order that they
-may be traced.  If traces for the built-in commands are not required,
-the \fIflags\fR parameter may be set to the constant value
-\fBTCL_ALLOW_INLINE_COMPILATION\fR.  In this case, traces on built-in
-commands may or may not result in trace callbacks, depending on the
-state of the interpreter, but run-time performance will be improved
-significantly.  (This functionality is desirable, for example, when
-using \fBTcl_CreateObjTrace\fR to implement an execution time
-profiler.)
-.PP
-Calls to \fIobjProc\fR will be made by the Tcl parser immediately before
-it calls the command procedure for the command (\fIcmdProc\fR).  This
-occurs after argument parsing and substitution, so tracing for
-substituted commands occurs before tracing of the commands
-containing the substitutions.  If there is a syntax error in a
-command, or if there is no command procedure associated with a
-command name, then no tracing will occur for that command.  If a
-string passed to Tcl_Eval contains multiple commands (bracketed, or
-on different lines) then multiple calls to \fIobjProc\fR will occur,
-one for each command.
-.PP
-\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be
-made to the procedure associated with the trace.  After \fBTcl_DeleteTrace\fR
-returns, the caller should never again use the \fItrace\fR token.
-.PP
-When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
-\fIdeleteProc\fR that was passed as a parameter to
-\fBTcl_CreateObjTrace\fR.  The \fIdeleteProc\fR must match the type,
-\fBTcl_CmdObjTraceDeleteProc\fR:
-.CS
-typedef void \fBTcl_CmdObjTraceDeleteProc\fR( 
-        \fBClientData\fR \fIclientData\fR);
-.CE
-The \fIclientData\fR parameter will be the same as the
-\fIclientData\fR parameter that was originally passed to
-\fBTcl_CreateObjTrace\fR.
-.PP
-\fBTcl_CreateTrace\fR is an alternative interface for command tracing,
-\fInot recommended for new applications\fR.  It is provided for backward
-compatibility with code that was developed for older versions of the
-Tcl interpreter.  It is similar to \fBTcl_CreateObjTrace\fR, except
-that its \fIproc\fR parameter should have arguments and result that
-match the type \fBTcl_CmdTraceProc\fR:
-.CS
-typedef void Tcl_CmdTraceProc(
-        ClientData \fIclientData\fR,
-        Tcl_Interp *\fIinterp\fR,
-        int \fIlevel\fR,
-        char *\fIcommand\fR,
-        Tcl_CmdProc *\fIcmdProc\fR,
-        ClientData \fIcmdClientData\fR,
-        int \fIargc\fR,
-        const char *\fIargv\fR[]);
-.CE
-The parameters to the \fIproc\fR callback are similar to those of the
-\fIobjProc\fR callback above. The \fIcommandToken\fR is
-replaced with \fIcmdProc\fR, a pointer to the (string-based) command
-procedure that will be invoked; and \fIcmdClientData\fR, the client
-data that will be passed to the procedure.  The \fIobjc\fR parameter
-is replaced with an \fIargv\fR parameter, that gives the arguments to
-the command as character strings.
-\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
-.PP
-If a trace created with \fBTcl_CreateTrace\fR is in effect, inline
-compilation of Tcl commands such as \fBif\fR and \fBwhile\fR is always
-disabled.  There is no notification when a trace created with
-\fBTcl_CreateTrace\fR is deleted.
-There is no way to be notified when the trace created by
-\fBTcl_CreateTrace\fR is deleted.  There is no way for the \fIproc\fR
-associated with a call to \fBTcl_CreateTrace\fR to abort execution of
-\fIcommand\fR.
-.SH KEYWORDS
-command, create, delete, interpreter, trace
+'\"

+'\" Copyright (c) 1989-1993 The Regents of the University of California.

+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.

+'\" Copyright (c) 2002 by Kevin B. Kenny.  All rights reserved.

+'\"

+'\" See the file "license.terms" for information on usage and redistribution

+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.

+'\" 

+'\" RCS: @(#) $Id: CrtTrace.3,v 1.11 2007/10/28 14:17:38 dkf Exp $

+'\" 

+.so man.macros

+.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"

+.BS

+.SH NAME

+Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace \- arrange for command execution to be traced

+.SH SYNOPSIS

+.nf

+\fB#include <tcl.h>\fR

+.sp

+Tcl_Trace

+\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)

+.sp

+Tcl_Trace

+\fBTcl_CreateObjTrace\fR(\fIinterp, level, flags, objProc, clientData, deleteProc\fR)

+.sp

+\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)

+.SH ARGUMENTS

+.AS Tcl_CmdObjTraceDeleteProc *deleteProc

+.AP Tcl_Interp *interp in

+Interpreter containing command to be traced or untraced.

+.AP int level in

+Only commands at or below this nesting level will be traced unless

+0 is specified.  1 means

+top-level commands only, 2 means top-level commands or those that are

+invoked as immediate consequences of executing top-level commands

+(procedure bodies, bracketed commands, etc.) and so on.

+A value of 0 means that commands at any level are traced.

+.AP int flags in

+Flags governing the trace execution.  See below for details.

+.AP Tcl_CmdObjTraceProc *objProc in

+Procedure to call for each command that is executed.  See below for

+details of the calling sequence.

+.AP Tcl_CmdTraceProc *proc in

+Procedure to call for each command that is executed.  See below for

+details on the calling sequence.

+.AP ClientData clientData in

+Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.

+.AP Tcl_CmdObjTraceDeleteProc *deleteProc in

+Procedure to call when the trace is deleted.  See below for details of

+the calling sequence.  A NULL pointer is permissible and results in no

+callback when the trace is deleted.

+.AP Tcl_Trace trace in

+Token for trace to be removed (return value from previous call

+to \fBTcl_CreateTrace\fR).

+.BE

+.SH DESCRIPTION

+.PP

+\fBTcl_CreateObjTrace\fR arranges for command tracing.  After it is

+called, \fIobjProc\fR will be invoked before the Tcl interpreter calls

+any command procedure when evaluating commands in \fIinterp\fR.

+The return value from \fBTcl_CreateObjTrace\fR is a token for the trace,

+which may be passed to \fBTcl_DeleteTrace\fR to remove the trace.

+There may be many traces in effect simultaneously for the same

+interpreter.

+.PP

+\fIobjProc\fR should have arguments and result that match the type,

+\fBTcl_CmdObjTraceProc\fR:

+.CS

+typedef int \fBTcl_CmdObjTraceProc\fR( 

+        \fBClientData\fR \fIclientData\fR,

+        \fBTcl_Interp\fR* \fIinterp\fR,

+        int \fIlevel\fR,

+        const char *\fIcommand\fR,

+        \fBTcl_Command\fR \fIcommandToken\fR,

+        int \fIobjc\fR,

+        \fBTcl_Obj\fR *const \fIobjv\fR[] );

+.CE

+The \fIclientData\fR and \fIinterp\fR parameters are copies of the

+corresponding arguments given to \fBTcl_CreateTrace\fR.

+\fIClientData\fR typically points to an application-specific data

+structure that describes what to do when \fIobjProc\fR is invoked.  The

+\fIlevel\fR parameter gives the nesting level of the command (1 for

+top-level commands passed to \fBTcl_Eval\fR by the application, 2 for

+the next-level commands passed to \fBTcl_Eval\fR as part of parsing or

+interpreting level-1 commands, and so on). The \fIcommand\fR parameter

+points to a string containing the text of the command, before any

+argument substitution.  The \fIcommandToken\fR parameter is a Tcl

+command token that identifies the command to be invoked.  The token

+may be passed to \fBTcl_GetCommandName\fR,

+\fBTcl_GetCommandTokenInfo\fR, or \fBTcl_SetCommandTokenInfo\fR to

+manipulate the definition of the command. The \fIobjc\fR and \fIobjv\fR

+parameters designate the final parameter count and parameter vector

+that will be passed to the command, and have had all substitutions

+performed.

+.PP

+The \fIobjProc\fR callback is expected to return a standard Tcl status

+return code.  If this code is \fBTCL_OK\fR (the normal case), then

+the Tcl interpreter will invoke the command.  Any other return code

+is treated as if the command returned that status, and the command is

+\fInot\fR invoked.

+.PP

+The \fIobjProc\fR callback must not modify \fIobjv\fR in any way.  It

+is, however, permissible to change the command by calling

+\fBTcl_SetCommandTokenInfo\fR prior to returning.  Any such change

+takes effect immediately, and the command is invoked with the new

+information.

+.PP

+Tracing will only occur for commands at nesting level less than

+or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR

+parameter to \fIobjProc\fR will always be less than or equal to the

+\fIlevel\fR parameter to \fBTcl_CreateTrace\fR).

+.PP

+Tracing has a significant effect on runtime performance because it

+causes the bytecode compiler to refrain from generating in-line code

+for Tcl commands such as \fBif\fR and \fBwhile\fR in order that they

+may be traced.  If traces for the built-in commands are not required,

+the \fIflags\fR parameter may be set to the constant value

+\fBTCL_ALLOW_INLINE_COMPILATION\fR.  In this case, traces on built-in

+commands may or may not result in trace callbacks, depending on the

+state of the interpreter, but run-time performance will be improved

+significantly.  (This functionality is desirable, for example, when

+using \fBTcl_CreateObjTrace\fR to implement an execution time

+profiler.)

+.PP

+Calls to \fIobjProc\fR will be made by the Tcl parser immediately before

+it calls the command procedure for the command (\fIcmdProc\fR).  This

+occurs after argument parsing and substitution, so tracing for

+substituted commands occurs before tracing of the commands

+containing the substitutions.  If there is a syntax error in a

+command, or if there is no command procedure associated with a

+command name, then no tracing will occur for that command.  If a

+string passed to Tcl_Eval contains multiple commands (bracketed, or

+on different lines) then multiple calls to \fIobjProc\fR will occur,

+one for each command.

+.PP

+\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be

+made to the procedure associated with the trace.  After \fBTcl_DeleteTrace\fR

+returns, the caller should never again use the \fItrace\fR token.

+.PP

+When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the

+\fIdeleteProc\fR that was passed as a parameter to

+\fBTcl_CreateObjTrace\fR.  The \fIdeleteProc\fR must match the type,

+\fBTcl_CmdObjTraceDeleteProc\fR:

+.CS

+typedef void \fBTcl_CmdObjTraceDeleteProc\fR( 

+        \fBClientData\fR \fIclientData\fR);

+.CE

+The \fIclientData\fR parameter will be the same as the

+\fIclientData\fR parameter that was originally passed to

+\fBTcl_CreateObjTrace\fR.

+.PP

+\fBTcl_CreateTrace\fR is an alternative interface for command tracing,

+\fInot recommended for new applications\fR.  It is provided for backward

+compatibility with code that was developed for older versions of the

+Tcl interpreter.  It is similar to \fBTcl_CreateObjTrace\fR, except

+that its \fIproc\fR parameter should have arguments and result that

+match the type \fBTcl_CmdTraceProc\fR:

+.CS

+typedef void Tcl_CmdTraceProc(

+        ClientData \fIclientData\fR,

+        Tcl_Interp *\fIinterp\fR,

+        int \fIlevel\fR,

+        char *\fIcommand\fR,

+        Tcl_CmdProc *\fIcmdProc\fR,

+        ClientData \fIcmdClientData\fR,

+        int \fIargc\fR,

+        const char *\fIargv\fR[]);

+.CE

+The parameters to the \fIproc\fR callback are similar to those of the

+\fIobjProc\fR callback above. The \fIcommandToken\fR is

+replaced with \fIcmdProc\fR, a pointer to the (string-based) command

+procedure that will be invoked; and \fIcmdClientData\fR, the client

+data that will be passed to the procedure.  The \fIobjc\fR parameter

+is replaced with an \fIargv\fR parameter, that gives the arguments to

+the command as character strings.

+\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.

+.PP

+If a trace created with \fBTcl_CreateTrace\fR is in effect, inline

+compilation of Tcl commands such as \fBif\fR and \fBwhile\fR is always

+disabled.  There is no notification when a trace created with

+\fBTcl_CreateTrace\fR is deleted.

+There is no way to be notified when the trace created by

+\fBTcl_CreateTrace\fR is deleted.  There is no way for the \fIproc\fR

+associated with a call to \fBTcl_CreateTrace\fR to abort execution of

+\fIcommand\fR.

+.SH KEYWORDS

+command, create, delete, interpreter, trace