Merge trunk.

Move Tcl_InitSubsystems documentation to its own manpage

3 files changed, 111 insertions, 88 deletions

diff --git a/doc/FindExec.3 b/doc/FindExec.3
index 1b3c7c5..e4b4ed0 100644
--- a/doc/FindExec.3
+++ b/doc/FindExec.3
@@ -8,7 +8,7 @@
 .TH Tcl_FindExecutable 3 8.1 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_FindExecutable, Tcl_GetNameOfExecutable, Tcl_InitSubsystems \- identify or return the name of the binary file containing the application
+Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of the binary file containing the application
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -18,18 +18,11 @@ void
 .sp
 const char *
 \fBTcl_GetNameOfExecutable\fR()
-.sp
-Tcl_Interp *
-\fBTcl_InitSubsystems\fR(\fIflags\fR, \fI...\fR)
 .SH ARGUMENTS
 .AS char *argv0
 .AP char *argv0 in
 The first command-line argument to the program, which gives the
 application's name.
-.AP int flags in
-Any combination of flags which indicate whether a custom panicProc
-is registered and/or a real interpreter is created.
-The value 0 can be used if Tcl is used as utility library only.
 .BE
 
 .SH DESCRIPTION
@@ -65,84 +58,6 @@ internal full path name of the executable file as computed by
 equivalent to the \fBinfo nameofexecutable\fR command.  NULL
 is returned if the internal full path name has not been
 computed or unknown.
-.PP
-The \fBTcl_InitSubsystems\fR can be used as an alternative to
-\fBTcl_FindExecutable\fR, when more flexibility is required.
-Its flags control exactly what is initialized, and what
-additional arguments are expected.
-.PP
-The call \fBTcl_InitSubsystems(0)\fR does the same as
-\fBTcl_FindExecutable(NULL)\fR, except that a Tcl_Interp *
-is returned which can be used only by \fBTcl_InitStubs\fR
-to initialize the stub table. This opens up the Tcl Stub
-technology for Tcl embedders, which now can dynamically
-load the Tcl shared library and use functions in it
-without ever creating an interpreter. E.g. the
-following code can be compiled with -DUSE_TCL_STUBS:
-.CS
-    Tcl_Interp *interp, *(*initSubSystems)(int, ...);
-    const char *version;
-    void *handle = dlopen("libtcl8.6.so", RTLD_NOW|RTLD_LOCAL);
-    initSubSystems = dlsym(handle, "Tcl_InitSubsystems");
-    version = Tcl_InitStubs(initSubSystems(0), NULL, 0);
-    /* At this point, Tcl C API calls without interp are ready for use */
-    interp = Tcl_CreateInterp(); /* Now we have a real interpreter */
-    Tcl_InitStubs(interp, version, 0); /* Initialize the stub table again */
-.CE
-This is equivalent to (without dynamical loading)
-.CS
-    Tcl_Interp *interp;
-    const char *version;
-    version = Tcl_InitStubs(Tcl_InitSubSystems(0), NULL, 0);
-    /* At this point, Tcl C API calls without interp are ready for use */
-    interp = Tcl_CreateInterp(); /* Now we have a real interpreter */
-    Tcl_InitStubs(interp, version, 0); /* Initialize the stub table again */
-.CE
-The function \fBTcl_CreateInterp\fR, or any other Tcl function you
-would like to call, no longer needs to be searched for in the
-shared library. It can be called directly through the stub table.
-Note that the stub table needs to be initialized twice, in order
-to be sure that you can call all functions without limitations
-after the real interpreter is created.
-.PP
-If you supply the flag \fBTCL_INIT_PANIC\fR to \fBTcl_InitSubsystems\fR,
-the function expects an additional argument, a custom panicProc.
-This is equivalent to calling \fBTcl_SetPanicProc\fR immediately
-before \fBTcl_InitSubsystems\fR, except that you possibly cannot do
-that yet if it requires an initialized stub table. Of course you
-could call \fBTcl_SetPanicProc\fR immediately after \fBTcl_InitSubsystems\fR,
-but then panics which could be produced by the initialization
-itself still use the default panic procedure. 
-.PP
-If you supply one of the flags \fBTCL_INIT_CREATE\fR, \fBTCL_INIT_CREATE_UTF8\fR or
-\fBTCL_INIT_CREATE_UNICODE\fR to \fBTcl_InitSubsystems\fR, the function
-gets two additional parameters, argc and argv. Then a real
-Tcl interpreter will be created. If argc > 0 then the variables
-\fBargc\fR and \fBargv\fR will be set in this interpreter. The 3
-variants assume a different encoding for the arguments, except for
-\fIargv[0]\fR which is always assumed to be in the system encoding.
-So, the above example code could be simplified to:
-.CS
-    interp = Tcl_InitSubSystems(TCL_INIT_CREATE, 0, NULL);
-    Tcl_InitStubs(interp, TCL_VERSION, 0); /* initialize the stub table */
-.CE
-.PP
-If the \fBTCL_INIT_PANIC\fR and one of the \fBTCL_INIT_CREATE\fR
-flags are used in combination, the \fBpanicProc\fR argument comes
-before the \fBargc\fR/\fBargv\fR arguments.
-.PP
-The reason for \fBargv0\fR always using the system encoding is that this way,
-argv0 can be derived directly from the main() (or mainw, on Windows)
-arguments without any processing. \fBTCL_INIT_CREATE_UNICODE\fR is really only
-useful on Windows. But on Windows, the argv0 parameter is not used for
-determining the value of [info executable] anyway. Modern UNIX system already
-have UTF-8 as system encoding, so \fBTCL_INIT_CREATE_UTF8\fR would have the same
-effect as \fBTCL_INIT_CREATE\fR, only slightly faster. Other parameters can be
-preprocessed at will by the application, and if the application uses unicode
-or UTF-8 internally there is no need to convert it back to the system encoding.
-.PP
-The interpreter returned by Tcl_InitSubsystems(0) cannot be passed to
-any other function than Tcl_InitStubs(). Tcl functions with an "interp"
-argument can only be called if the function supports passing NULL.
+
 .SH KEYWORDS
 binary, executable file
diff --git a/doc/InitSubSyst.3 b/doc/InitSubSyst.3
new file mode 100644
index 0000000..efe4861
--- /dev/null
+++ b/doc/InitSubSyst.3
@@ -0,0 +1,108 @@
+'\"
+'\" Copyright (c) 1995-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.
+'\" 
+.so man.macros
+.TH Tcl_InitSubsystems 3 8.6 Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_InitSubsystems \- initialize the Tcl library.
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+Tcl_Interp *
+\fBTcl_InitSubsystems\fR(\fIflags\fR, \fI...\fR)
+.SH ARGUMENTS
+.AS int flags
+.AP int flags in
+Any combination of flags which indicate whether a custom panicProc
+is registered and/or a real interpreter is created.
+The value 0 can be used if Tcl is used as utility library only.
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBfBTcl_InitSubsystems\fR procedure initializes the Tcl
+library. This procedure is typically invoked as the very
+first thing in the application's main program.
+Its \fBflags\fR argument controls exactly what is initialized,
+and what additional arguments are expected.
+.PP
+The call \fBTcl_InitSubsystems(0)\fR does the same as
+\fBTcl_FindExecutable(NULL)\fR, except that a Tcl_Interp *
+is returned which can be used only by \fBTcl_InitStubs\fR
+to initialize the stub table. This opens up the Tcl Stub
+technology for Tcl embedders, which now can dynamically
+load the Tcl shared library and use functions in it
+without ever creating an interpreter. E.g. the
+following code can be compiled with -DUSE_TCL_STUBS:
+.CS
+    Tcl_Interp *interp, *(*initSubSystems)(int, ...);
+    const char *version;
+    void *handle = dlopen("libtcl8.6.so", RTLD_NOW|RTLD_LOCAL);
+    initSubSystems = dlsym(handle, "Tcl_InitSubsystems");
+    version = Tcl_InitStubs(initSubSystems(0), NULL, 0);
+    /* At this point, Tcl C API calls without interp are ready for use */
+    interp = Tcl_CreateInterp(); /* Now we have a real interpreter */
+    Tcl_InitStubs(interp, version, 0); /* Initialize the stub table again */
+.CE
+This is equivalent to (without dynamical loading)
+.CS
+    Tcl_Interp *interp;
+    const char *version;
+    version = Tcl_InitStubs(Tcl_InitSubSystems(0), NULL, 0);
+    /* At this point, Tcl C API calls without interp are ready for use */
+    interp = Tcl_CreateInterp(); /* Now we have a real interpreter */
+    Tcl_InitStubs(interp, version, 0); /* Initialize the stub table again */
+.CE
+The function \fBTcl_CreateInterp\fR, or any other Tcl function you
+would like to call, no longer needs to be searched for in the
+shared library. It can be called directly through the stub table.
+Note that the stub table needs to be initialized twice, in order
+to be sure that you can call all functions without limitations
+after the real interpreter is created.
+.PP
+If you supply the flag \fBTCL_INIT_PANIC\fR to \fBTcl_InitSubsystems\fR,
+the function expects an additional argument, a custom panicProc.
+This is equivalent to calling \fBTcl_SetPanicProc\fR immediately
+before \fBTcl_InitSubsystems\fR, except that you possibly cannot do
+that yet if it requires an initialized stub table. Of course you
+could call \fBTcl_SetPanicProc\fR immediately after \fBTcl_InitSubsystems\fR,
+but then panics which could be produced by the initialization
+itself still use the default panic procedure. 
+.PP
+If you supply one of the flags \fBTCL_INIT_CREATE\fR, \fBTCL_INIT_CREATE_UTF8\fR or
+\fBTCL_INIT_CREATE_UNICODE\fR to \fBTcl_InitSubsystems\fR, the function
+gets two additional parameters, argc and argv. Then a real
+Tcl interpreter will be created. If argc > 0 then the variables
+\fBargc\fR and \fBargv\fR will be set in this interpreter. The 3
+variants assume a different encoding for the arguments, except for
+\fIargv[0]\fR which is always assumed to be in the system encoding.
+So, the above example code could be simplified to:
+.CS
+    Tcl_Interp *interp = Tcl_InitSubSystems(TCL_INIT_CREATE, 0, NULL);
+    Tcl_InitStubs(interp, TCL_VERSION, 0); /* initialize the stub table */
+.CE
+.PP
+If the \fBTCL_INIT_PANIC\fR and one of the \fBTCL_INIT_CREATE\fR
+flags are used in combination, the \fBpanicProc\fR argument comes
+before the \fBargc\fR/\fBargv\fR arguments.
+.PP
+The reason for \fBargv0\fR always using the system encoding is that this way,
+argv0 can be derived directly from the main() (or mainw, on Windows)
+arguments without any processing. \fBTCL_INIT_CREATE_UNICODE\fR is really only
+useful on Windows. But on Windows, the argv0 parameter is not used for
+determining the value of [info executable] anyway. Modern UNIX system already
+have UTF-8 as system encoding, so \fBTCL_INIT_CREATE_UTF8\fR would have the same
+effect as \fBTCL_INIT_CREATE\fR, only slightly faster. Other parameters can be
+preprocessed at will by the application, and if the application uses unicode
+or UTF-8 internally there is no need to convert it back to the system encoding.
+.PP
+The interpreter returned by Tcl_InitSubsystems(0) cannot be passed to
+any other function than Tcl_InitStubs(). Tcl functions with an "interp"
+argument can only be called if the function supports passing NULL.
+.SH KEYWORDS
+binary, executable file
diff --git a/doc/msgcat.n b/doc/msgcat.n
index 57fbb78..47b6bf7 100644
--- a/doc/msgcat.n
+++ b/doc/msgcat.n
@@ -13,7 +13,7 @@ msgcat \- Tcl message catalog
 .SH SYNOPSIS
 \fBpackage require Tcl 8.5\fR
 .sp
-\fBpackage require msgcat 1.5.0\fR
+\fBpackage require msgcat 1.5\fR
 .sp
 \fB::msgcat::mc \fIsrc-string\fR ?\fIarg arg ...\fR?
 .sp