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

1 files changed, 125 insertions, 125 deletions

diff --git a/doc/Interp.3 b/doc/Interp.3
index c61ae40..9ee66f9 100644
--- a/doc/Interp.3
+++ b/doc/Interp.3
@@ -1,125 +1,125 @@
-'\"
-'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\" 
-'\" RCS: @(#) $Id: Interp.3,v 1.9 2005/05/10 18:33:56 kennykb Exp $
-'\" 
-.so man.macros
-.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
-.BS
-.SH NAME
-Tcl_Interp \- client-visible fields of interpreter structures
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-typedef struct {
-        char *\fIresult\fR;
-        Tcl_FreeProc *\fIfreeProc\fR;
-        int \fIerrorLine\fR;
-} Tcl_Interp;
-
-typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
-.BE
-
-.SH DESCRIPTION
-.PP
-The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
-structure.  This pointer is then passed into other Tcl procedures
-to process commands in the interpreter and perform other operations
-on the interpreter.  Interpreter structures contain many fields
-that are used by Tcl, but only three that may be accessed by
-clients:  \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
-.PP
-\fBNote that access to the \fIresult\fB and \fIfreeProc\fB fields is\fR
-\fBdeprecated.\fR  Use \fBTcl_SetResult\fR and \fBTcl_GetResult\fR instead.
-.PP
-The \fIresult\fR and \fIfreeProc\fR fields are used to return
-results or error messages from commands.
-This information is returned by command procedures back to \fBTcl_Eval\fR,
-and by \fBTcl_Eval\fR back to its callers.
-The \fIresult\fR field points to the string that represents the
-result or error message, and the \fIfreeProc\fR field tells how
-to dispose of the storage for the string when it isn't needed anymore.
-The easiest way for command procedures to manipulate these
-fields is to call procedures like \fBTcl_SetResult\fR
-or \fBTcl_AppendResult\fR;  they
-will hide all the details of managing the fields.
-The description below is for those procedures that manipulate the
-fields directly.
-.PP
-Whenever a command procedure returns, it must ensure
-that the \fIresult\fR field of its interpreter points to the string
-being returned by the command.
-The \fIresult\fR field must always point to a valid string.
-If a command wishes to return no result then \fIinterp->result\fR
-should point to an empty string.
-Normally, results are assumed to be statically allocated,
-which means that the contents will not change before the next time
-\fBTcl_Eval\fR is called or some other command procedure is invoked.
-In this case, the \fIfreeProc\fR field must be zero.
-Alternatively, a command procedure may dynamically
-allocate its return value (e.g. using \fBTcl_Alloc\fR)
-and store a pointer to it in \fIinterp->result\fR.
-In this case, the command procedure must also set \fIinterp->freeProc\fR
-to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR
-if the storage was allocated directly by Tcl or by a call to
-\fBTcl_Alloc\fR. 
-If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
-to free the space pointed to by \fIinterp->result\fR before it
-invokes the next command.
-If a client procedure overwrites \fIinterp->result\fR when
-\fIinterp->freeProc\fR is non-zero, then it is responsible for calling
-\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR
-macro should be used for this purpose).
-.PP
-\fIFreeProc\fR should have arguments and result that match the
-\fBTcl_FreeProc\fR declaration above:  it receives a single
-argument which is a pointer to the result value to free.
-In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
-used for \fIfreeProc\fR.
-However, an application may store a different procedure address
-in \fIfreeProc\fR in order to use an alternate memory allocator
-or in order to do other cleanup when the result memory is freed.
-.PP
-As part of processing each command, \fBTcl_Eval\fR initializes
-\fIinterp->result\fR
-and \fIinterp->freeProc\fR just before calling the command procedure for
-the command.  The \fIfreeProc\fR field will be initialized to zero,
-and \fIinterp->result\fR will point to an empty string.  Commands that
-do not return any value can simply leave the fields alone.
-Furthermore, the empty string pointed to by \fIresult\fR is actually
-part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
-If a command wishes to return a short string, it can simply copy
-it to the area pointed to by \fIinterp->result\fR.  Or, it can use
-the sprintf procedure to generate a short result string at the location
-pointed to by \fIinterp->result\fR.
-.PP
-It is a general convention in Tcl-based applications that the result
-of an interpreter is normally in the initialized state described
-in the previous paragraph.
-Procedures that manipulate an interpreter's result (e.g. by
-returning an error) will generally assume that the result
-has been initialized when the procedure is called.
-If such a procedure is to be called after the result has been
-changed, then \fBTcl_ResetResult\fR should be called first to
-reset the result to its initialized state.  The direct use of
-\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR).
-.PP
-The \fIerrorLine\fR
-field is valid only after \fBTcl_Eval\fR returns
-a \fBTCL_ERROR\fR return code.  In this situation the \fIerrorLine\fR
-field identifies the line number of the command being executed when
-the error occurred.  The line numbers are relative to the command
-being executed:  1 means the first line of the command passed to
-\fBTcl_Eval\fR, 2 means the second line, and so on.
-The \fIerrorLine\fR field is typically used in conjunction with
-\fBTcl_AddErrorInfo\fR to report information about where an error
-occurred.
-\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR.
-
-.SH KEYWORDS
-free, initialized, interpreter, malloc, result
+'\"

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

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

+'\"

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

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

+'\" 

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

+'\" 

+.so man.macros

+.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"

+.BS

+.SH NAME

+Tcl_Interp \- client-visible fields of interpreter structures

+.SH SYNOPSIS

+.nf

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

+.sp

+typedef struct {

+        char *\fIresult\fR;

+        Tcl_FreeProc *\fIfreeProc\fR;

+        int \fIerrorLine\fR;

+} Tcl_Interp;

+

+typedef void Tcl_FreeProc(char *\fIblockPtr\fR);

+.BE

+

+.SH DESCRIPTION

+.PP

+The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp

+structure.  This pointer is then passed into other Tcl procedures

+to process commands in the interpreter and perform other operations

+on the interpreter.  Interpreter structures contain many fields

+that are used by Tcl, but only three that may be accessed by

+clients:  \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.

+.PP

+\fBNote that access to the \fIresult\fB and \fIfreeProc\fB fields is\fR

+\fBdeprecated.\fR  Use \fBTcl_SetResult\fR and \fBTcl_GetResult\fR instead.

+.PP

+The \fIresult\fR and \fIfreeProc\fR fields are used to return

+results or error messages from commands.

+This information is returned by command procedures back to \fBTcl_Eval\fR,

+and by \fBTcl_Eval\fR back to its callers.

+The \fIresult\fR field points to the string that represents the

+result or error message, and the \fIfreeProc\fR field tells how

+to dispose of the storage for the string when it is not needed anymore.

+The easiest way for command procedures to manipulate these

+fields is to call procedures like \fBTcl_SetResult\fR

+or \fBTcl_AppendResult\fR;  they

+will hide all the details of managing the fields.

+The description below is for those procedures that manipulate the

+fields directly.

+.PP

+Whenever a command procedure returns, it must ensure

+that the \fIresult\fR field of its interpreter points to the string

+being returned by the command.

+The \fIresult\fR field must always point to a valid string.

+If a command wishes to return no result then \fIinterp->result\fR

+should point to an empty string.

+Normally, results are assumed to be statically allocated,

+which means that the contents will not change before the next time

+\fBTcl_Eval\fR is called or some other command procedure is invoked.

+In this case, the \fIfreeProc\fR field must be zero.

+Alternatively, a command procedure may dynamically

+allocate its return value (e.g. using \fBTcl_Alloc\fR)

+and store a pointer to it in \fIinterp->result\fR.

+In this case, the command procedure must also set \fIinterp->freeProc\fR

+to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR

+if the storage was allocated directly by Tcl or by a call to

+\fBTcl_Alloc\fR. 

+If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR

+to free the space pointed to by \fIinterp->result\fR before it

+invokes the next command.

+If a client procedure overwrites \fIinterp->result\fR when

+\fIinterp->freeProc\fR is non-zero, then it is responsible for calling

+\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR

+macro should be used for this purpose).

+.PP

+\fIFreeProc\fR should have arguments and result that match the

+\fBTcl_FreeProc\fR declaration above:  it receives a single

+argument which is a pointer to the result value to free.

+In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever

+used for \fIfreeProc\fR.

+However, an application may store a different procedure address

+in \fIfreeProc\fR in order to use an alternate memory allocator

+or in order to do other cleanup when the result memory is freed.

+.PP

+As part of processing each command, \fBTcl_Eval\fR initializes

+\fIinterp->result\fR

+and \fIinterp->freeProc\fR just before calling the command procedure for

+the command.  The \fIfreeProc\fR field will be initialized to zero,

+and \fIinterp->result\fR will point to an empty string.  Commands that

+do not return any value can simply leave the fields alone.

+Furthermore, the empty string pointed to by \fIresult\fR is actually

+part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).

+If a command wishes to return a short string, it can simply copy

+it to the area pointed to by \fIinterp->result\fR.  Or, it can use

+the sprintf procedure to generate a short result string at the location

+pointed to by \fIinterp->result\fR.

+.PP

+It is a general convention in Tcl-based applications that the result

+of an interpreter is normally in the initialized state described

+in the previous paragraph.

+Procedures that manipulate an interpreter's result (e.g. by

+returning an error) will generally assume that the result

+has been initialized when the procedure is called.

+If such a procedure is to be called after the result has been

+changed, then \fBTcl_ResetResult\fR should be called first to

+reset the result to its initialized state.  The direct use of

+\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR).

+.PP

+The \fIerrorLine\fR

+field is valid only after \fBTcl_Eval\fR returns

+a \fBTCL_ERROR\fR return code.  In this situation the \fIerrorLine\fR

+field identifies the line number of the command being executed when

+the error occurred.  The line numbers are relative to the command

+being executed:  1 means the first line of the command passed to

+\fBTcl_Eval\fR, 2 means the second line, and so on.

+The \fIerrorLine\fR field is typically used in conjunction with

+\fBTcl_AddErrorInfo\fR to report information about where an error

+occurred.

+\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR.

+

+.SH KEYWORDS

+free, initialized, interpreter, malloc, result