From ea802bf05a1a391f016813437bc85bde1e59b0c9 Mon Sep 17 00:00:00 2001
From: stanton <stanton>
Date: Thu, 6 May 1999 19:14:39 +0000
Subject: merged doc changes from 8.1.0

---
 doc/Access.3       |  2 +-
 doc/Encoding.3     |  2 +-
 doc/InitStubs.3    | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/Notifier.3     |  2 +-
 doc/OpenFileChnl.3 |  2 +-
 doc/Thread.3       |  2 +-
 doc/Utf.3          |  2 +-
 doc/regexp.n       |  2 +-
 8 files changed, 98 insertions(+), 7 deletions(-)
 create mode 100644 doc/InitStubs.3

diff --git a/doc/Access.3 b/doc/Access.3
index bdbbea3..c81cf10 100644
--- a/doc/Access.3
+++ b/doc/Access.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Access.3,v 1.2 1999/04/30 22:45:00 stanton Exp $
+'\" RCS: @(#) $Id: Access.3,v 1.3 1999/05/06 19:14:39 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_Access 3 8.1 Tcl "Tcl Library Procedures"
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index 8d1262b..4628b56 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Encoding.3,v 1.3 1999/04/30 22:45:00 stanton Exp $
+'\" RCS: @(#) $Id: Encoding.3,v 1.4 1999/05/06 19:14:39 stanton Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
diff --git a/doc/InitStubs.3 b/doc/InitStubs.3
new file mode 100644
index 0000000..4701927
--- /dev/null
+++ b/doc/InitStubs.3
@@ -0,0 +1,91 @@
+'\"
+'\" Copyright (c) 1999 Scriptics Corportation
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: InitStubs.3,v 1.4 1999/05/06 19:14:40 stanton Exp $
+'\" 
+.so man.macros
+.TH Tcl_InitStubs 3 8.1 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_InitStubs \- initialize the Tcl stubs mechanism
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+char *
+\fBTcl_InitStubs\fR(\fIinterp, version, exact\fR)
+.SH ARGUMENTS
+.AS Tcl_Interp *interp in
+.AP Tcl_Interp *interp in
+Tcl interpreter handle.
+.AP char *version in
+A version string consisting of one or more decimal numbers
+separated by dots.
+.AP int exact in
+Non-zero means that only the particular version specified by
+\fIversion\fR is acceptable.
+Zero means that versions newer than \fIversion\fR are also
+acceptable as long as they have the same major version number
+as \fIversion\fR.
+.BE
+.SH INTRODUCTION
+.PP
+The Tcl stubs mechanism defines a way to dynamically bind
+extensions to a particular Tcl implementation at run time.
+This provides two significant benefits to Tcl users:
+.IP 1) 5
+Extensions that use the stubs mechanism can be loaded into
+multiple versions of Tcl without being recompiled or
+relinked.
+.IP 2) 5
+Extensions that use the stubs mechanism can be dynamically
+loaded into statically-linked Tcl applications.
+.PP
+The stubs mechanism accomplishes this by exporting function tables
+that define an interface to the Tcl API.  The extension then accesses
+the Tcl API through offsets into the function table, so there are no
+direct references to any of the Tcl library's symbols.  This
+redirection is transparent to the extension, so an extension writer
+can continue to use all public Tcl functions as documented.
+.PP
+The stubs mechanism requires no changes to applications incorporating
+Tcl interpreters.  Only developers creating C-based Tcl extensions
+need to take steps to use the stubs mechanism with their extensions.
+.PP
+Enabling the stubs mechanism for an extension requires the following
+steps:
+.IP 1) 5
+Call \fBTcl_InitStubs\fR in the extension before calling any other
+Tcl functions.
+.IP 2) 5
+Define the USE_TCL_STUBS symbol.  Typically, you would include the
+-DUSE_TCL_STUBS flag when compiling the extension.
+.IP 3) 5
+Link the extension with the Tcl stubs library instead of the standard
+Tcl library.  On Unix platforms, the library name is
+\fIlibtclstub8.1.a\fR; on Windows platforms, the library name is
+\fItclstub81.lib\fR.
+.PP
+If the extension also requires the Tk API, it must also call
+\fBTk_InitStubs\fR to initialize the Tk stubs interface and link
+with the Tk stubs libraries.  See the \fBTk_InitStubs\fR page for
+more information.
+.SH DESCRIPTION
+\fBTcl_InitStubs\fR attempts to initialize the stub table pointers
+and ensure that the correct version of Tcl is loaded.  In addition
+to an interpreter handle, it accepts as arguments a version number
+and a Boolean flag indicating whether the extension requires
+an exact version match or not.  If \fIexact\fR is 0, then the
+extension is indicating that newer versions of Tcl are acceptable
+as long as they have the same major version number as \fIversion\fR;
+non-zero means that only the specified \fIversion\fR is acceptable.
+\fBTcl_InitStubs\fR returns a string containing the actual version
+of Tcl satisfying the request, or NULL if the Tcl version is not
+acceptable, does not support stubs, or any other error condition occurred.
+.SH "SEE ALSO"
+\fBTk_InitStubs\fR
+.SH KEYWORDS
+stubs
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index a6c9280..79d8aca 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Notifier.3,v 1.5 1999/04/30 22:45:00 stanton Exp $
+'\" RCS: @(#) $Id: Notifier.3,v 1.6 1999/05/06 19:14:41 stanton Exp $
 '\" 
 .so man.macros
 .TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index 51be74b..dbcb472 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.4 1999/04/30 22:45:00 stanton Exp $
+'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.5 1999/05/06 19:14:41 stanton Exp $
 .so man.macros
 .TH Tcl_OpenFileChannel 3 8.1 Tcl "Tcl Library Procedures"
 .BS
diff --git a/doc/Thread.3 b/doc/Thread.3
index 8a4c566..e31860e 100644
--- a/doc/Thread.3
+++ b/doc/Thread.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Thread.3,v 1.5 1999/04/30 22:45:00 stanton Exp $
+'\" RCS: @(#) $Id: Thread.3,v 1.6 1999/05/06 19:14:41 stanton Exp $
 '\" 
 .so man.macros
 .TH Threads 3 "8.1" Tcl "Tcl Library Procedures"
diff --git a/doc/Utf.3 b/doc/Utf.3
index 0c331a8..b3b3a4b 100644
--- a/doc/Utf.3
+++ b/doc/Utf.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Utf.3,v 1.4 1999/05/06 18:46:23 stanton Exp $
+'\" RCS: @(#) $Id: Utf.3,v 1.5 1999/05/06 19:14:42 stanton Exp $
 '\" 
 .so man.macros
 .TH Utf 3 "8.1" Tcl "Tcl Library Procedures"
diff --git a/doc/regexp.n b/doc/regexp.n
index e19ae65..2f6c4b6 100644
--- a/doc/regexp.n
+++ b/doc/regexp.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: regexp.n,v 1.4 1999/04/30 22:45:01 stanton Exp $
+'\" RCS: @(#) $Id: regexp.n,v 1.5 1999/05/06 19:14:42 stanton Exp $
 '\" 
 .so man.macros
 .TH regexp n 8.1 Tcl "Tcl Built-In Commands"
-- 
cgit v0.12