* Documented $tcl_rcFileName and added more

        clarifications about the intended use of Tcl_Main(). [Bug 505651]

1 files changed, 29 insertions, 9 deletions

diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3
index d74d23a..e04b46e 100644
--- a/doc/Tcl_Main.3
+++ b/doc/Tcl_Main.3
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Tcl_Main.3,v 1.7 2002/01/14 15:10:06 dgp Exp $
+'\" RCS: @(#) $Id: Tcl_Main.3,v 1.8 2002/06/05 16:46:15 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures"
@@ -35,17 +35,29 @@ Address of an application-specific event loop procedure.
 
 .SH DESCRIPTION
 .PP
-\fBTcl_Main\fR acts as the main program for most Tcl-based applications.
-Starting with Tcl 7.4 it is not called \fBmain\fR anymore because it 
-is part of the Tcl library and having a function \fBmain\fR
-in a library (particularly a shared library) causes problems on many
-systems.
+\fBTcl_Main\fR can serve as the main program for Tcl-based shell
+applications.  A ``shell application'' is a program
+like tclsh or wish that supports both interactive interpretation
+of Tcl and evaluation of a script contained in a file given as
+a command line argument.  \fBTcl_Main\fR is offered as a convenience
+to developers of shell applications, so they do not have to 
+reproduce all of the code for proper initialization of the Tcl
+library and interactive shell operation.  Other styles of embedding
+Tcl in an application are not supported by \fBTcl_Main\fR.  Those
+must be achieved by calling lower level functions in the Tcl library
+directly.
+
+The \fBTcl_Main\fR function has been offered by the Tcl library
+since release Tcl 7.4.  In older releases of Tcl, the Tcl library
+itself defined a function \fBmain\fR, but that lacks flexibility
+of embedding style and having a function \fBmain\fR in a library
+(particularly a shared library) causes problems on many systems.
 Having \fBmain\fR in the Tcl library would also make it hard to use
 Tcl in C++ programs, since C++ programs must have special C++
 \fBmain\fR functions.
 .PP
-Normally each application contains a small \fBmain\fR function that does
-nothing but invoke \fBTcl_Main\fR.
+Normally each shell application contains a small \fBmain\fR function
+that does nothing but invoke \fBTcl_Main\fR.
 \fBTcl_Main\fR then does all the work of creating and running a
 \fBtclsh\fR-like application.
 .PP
@@ -54,6 +66,10 @@ stub library.  Programs that call \fBTcl_Main\fR must be linked
 against the standard Tcl library.  Extensions (stub-enabled or
 not) are not intended to call \fBTcl_Main\fR.
 .PP
+\fBTcl_Main\fR is not thread-safe.  It should only be called by
+a single master thread of a multi-threaded application.  This
+restriction is not a problem with normal use described above.
+.PP
 \fBTcl_Main\fR and therefore all applications based upon it, like
 \fBtclsh\fR, use \fBTcl_GetStdChannel\fR to initialize the standard
 channels to their default values. See \fBTcl_StandardChannels\fR for
@@ -86,7 +102,11 @@ details on this procedure, see the documentation for \fBTcl_AppInit\fR.
 .PP
 When the \fIappInitProc\fR is finished, \fBTcl_Main\fR enters one
 of its two modes.  If a startup script has been provided, \fBTcl_Main\fR
-attempts to evaluate it.  Otherwise interactive operations begin,
+attempts to evaluate it.  Otherwise, interactive mode begins with
+examination of the variable \fItcl_rcFileName\fR in the master
+interperter.  If that variable exists and holds the name of a readable
+file, the contents of that file are evaluated in the master interpreter.
+Then interactive operations begin,
 with prompts and command evaluation results written to the standard
 output channel, and commands read from the standard input channel
 and then evaluated.  The prompts written to the standard output