new subtree for tcl/tk

1 files changed, 0 insertions, 566 deletions

diff --git a/tcl8.6/doc/tclvars.n b/tcl8.6/doc/tclvars.n
deleted file mode 100644
index adefe40..0000000
--- a/tcl8.6/doc/tclvars.n
+++ /dev/null
@@ -1,566 +0,0 @@
-'\"
-'\" Copyright (c) 1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
-.so man.macros
-.BS
-'\" Note:  do not modify the .SH NAME line immediately below!
-.SH NAME
-argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_nonwordchars, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_precision, tcl_rcFileName, tcl_traceCompile, tcl_traceExec, tcl_wordchars, tcl_version \- Variables used by Tcl
-.BE
-.SH DESCRIPTION
-.PP
-The following global variables are created and managed automatically
-by the Tcl library.  Except where noted below, these variables should
-normally be treated as read-only by application-specific code and by users.
-.TP
-\fBauto_path\fR
-.
-If set, then it must contain a valid Tcl list giving directories to
-search during auto-load operations (including for package index
-files when using the default \fBpackage unknown\fR handler).
-This variable is initialized during startup to contain, in order:
-the directories listed in the \fBTCLLIBPATH\fR environment variable,
-the directory named by the \fBtcl_library\fR global variable,
-the parent directory of \fBtcl_library\fR,
-the directories listed in the \fBtcl_pkgPath\fR variable.
-Additional locations to look for files and package indices should
-normally be added to this variable using \fBlappend\fR.
-.RS
-.PP
-Additional variables relating to package management exist. More
-details are listed in the \fBVARIABLES\fR section of the \fBlibrary\fR
-manual page.
-.RE
-.TP
-\fBenv\fR
-.
-This variable is maintained by Tcl as an array
-whose elements are the environment variables for the process.
-Reading an element will return the value of the corresponding
-environment variable.
-Setting an element of the array will modify the corresponding
-environment variable or create a new one if it does not already
-exist.
-Unsetting an element of \fBenv\fR will remove the corresponding
-environment variable.
-Changes to the \fBenv\fR array will affect the environment
-passed to children by commands like \fBexec\fR.
-If the entire \fBenv\fR array is unset then Tcl will stop
-monitoring \fBenv\fR accesses and will not update environment
-variables.
-.RS
-.PP
-Under Windows, the environment variables PATH and COMSPEC in any
-capitalization are converted automatically to upper case.  For instance, the
-PATH variable could be exported by the operating system as
-.QW path ,
-.QW Path ,
-.QW PaTh ,
-etc., causing otherwise simple Tcl code to have to
-support many special cases.  All other environment variables inherited by
-Tcl are left unmodified.  Setting an env array variable to blank is the
-same as unsetting it as this is the behavior of the underlying Windows OS.
-It should be noted that relying on an existing and empty environment variable
-will not work on Windows and is discouraged for cross-platform usage.
-.PP
-The following elements of \fBenv\fR are special to Tcl:
-.TP
-\fBenv(HOME)\fR
-.
-This environment variable, if set, gives the location of the directory
-considered to be the current user's home directory, and to which a
-call of \fBcd\fR without arguments or with just
-.QW ~
-as an argument will change into. Most platforms set this correctly by
-default; it does not normally need to be set by user code.
-.TP
-\fBenv(TCL_LIBRARY)\fR
-.
-If set, then it specifies the location of the directory containing
-library scripts (the value of this variable will be
-assigned to the \fBtcl_library\fR variable and therefore returned by
-the command \fBinfo library\fR).  If this variable is not set then
-a default value is used.
-.RS
-.PP
-Note that this environment variable should \fInot\fR normally be set.
-.RE
-.TP
-\fBenv(TCLLIBPATH)\fR
-.
-If set, then it must contain a valid Tcl list giving directories to
-search during auto-load operations.  Directories must be specified in
-Tcl format, using
-.QW /
-as the path separator, regardless of platform.
-This variable is only used when initializing the \fBauto_path\fR variable.
-.TP
-\fBenv(TCL_TZ)\fR, \fBenv(TZ)\fR
-.
-These specify the default timezone used for parsing and formatting times and
-dates in the \fBclock\fR command. On many platforms, the TZ environment
-variable is set up by the operating system.
-.TP
-\fBenv(LC_ALL)\fR, \fBenv(LC_MESSAGES)\fR, \fBenv(LANG)\fR
-.
-These environment variables are used by the \fBmsgcat\fR package to
-determine what locale to format messages using.
-.TP
-\fBenv(TCL_INTERP_DEBUG_FRAME)\fR
-.
-If existing, it has the same effect as running \fBinterp debug\fR
-\fB{} -frame 1\fR
-as the very first command of each new Tcl interpreter.
-.RE
-.TP
-\fBerrorCode\fR
-.
-This variable holds the value of the \fB\-errorcode\fR return option
-set by the most recent error that occurred in this interpreter.
-This list value represents additional information about the error
-in a form that is easy to process with programs.
-The first element of the list identifies a general class of
-errors, and determines the format of the rest of the list.
-The following formats for \fB\-errorcode\fR return options
-are used by the Tcl core; individual applications may define
-additional formats.
-.RS
-.TP
-\fBARITH\fI code msg\fR
-.
-This format is used when an arithmetic error occurs (e.g. an attempt
-to divide zero by zero in the \fBexpr\fR command).
-\fICode\fR identifies the precise error and \fImsg\fR provides a
-human-readable description of the error.  \fICode\fR will be either
-DIVZERO (for an attempt to divide by zero),
-DOMAIN (if an argument is outside the domain of a function, such as acos(\-3)),
-IOVERFLOW (for integer overflow),
-OVERFLOW (for a floating-point overflow),
-or UNKNOWN (if the cause of the error cannot be determined).
-.RS
-.PP
-Detection of these errors depends in part on the underlying hardware
-and system libraries.
-.RE
-.TP
-\fBCHILDKILLED\fI pid sigName msg\fR
-.
-This format is used when a child process has been killed because of
-a signal.  The \fIpid\fR element will be the process's identifier (in decimal).
-The \fIsigName\fR element will be the symbolic name of the signal that caused
-the process to terminate; it will be one of the names from the
-include file signal.h, such as \fBSIGPIPE\fR.
-The \fImsg\fR element will be a short human-readable message
-describing the signal, such as
-.QW "write on pipe with no readers"
-for \fBSIGPIPE\fR.
-.TP
-\fBCHILDSTATUS\fI pid code\fR
-.
-This format is used when a child process has exited with a non-zero
-exit status.  The \fIpid\fR element will be the
-process's identifier (in decimal) and the \fIcode\fR element will be the exit
-code returned by the process (also in decimal).
-.TP
-\fBCHILDSUSP\fI pid sigName msg\fR
-.
-This format is used when a child process has been suspended because
-of a signal.
-The \fIpid\fR element will be the process's identifier, in decimal.
-The \fIsigName\fR element will be the symbolic name of the signal that caused
-the process to suspend; this will be one of the names from the
-include file signal.h, such as \fBSIGTTIN\fR.
-The \fImsg\fR element will be a short human-readable message
-describing the signal, such as
-.QW "background tty read"
-for \fBSIGTTIN\fR.
-.TP
-\fBNONE\fR
-.
-This format is used for errors where no additional information is
-available for an error besides the message returned with the
-error.  In these cases the \fB\-errorcode\fR return option
-will consist of a list containing a single element whose
-contents are \fBNONE\fR.
-.TP
-\fBPOSIX \fIerrName msg\fR
-.
-If the first element is \fBPOSIX\fR, then
-the error occurred during a POSIX kernel call.
-The \fIerrName\fR element will contain the symbolic name
-of the error that occurred, such as \fBENOENT\fR; this will
-be one of the values defined in the include file errno.h.
-The \fImsg\fR element will be a human-readable
-message corresponding to \fIerrName\fR, such as
-.QW "no such file or directory"
-for the \fBENOENT\fR case.
-.TP
-\fBTCL\fR ...
-.
-Indicates some sort of problem generated in relation to Tcl itself, e.g. a
-failure to look up a channel or variable.
-.PP
-To set the \fB\-errorcode\fR return option, applications should use library
-procedures such as \fBTcl_SetObjErrorCode\fR, \fBTcl_SetReturnOptions\fR,
-and \fBTcl_PosixError\fR, or they may invoke the \fB\-errorcode\fR
-option of the \fBreturn\fR command.
-If none of these methods for setting the error code has been used,
-the Tcl interpreter will reset the variable to \fBNONE\fR after
-the next error.
-.RE
-.TP
-\fBerrorInfo\fR
-.
-This variable holds the value of the \fB\-errorinfo\fR return option
-set by the most recent error that occurred in this interpreter.
-This string value will contain one or more lines
-identifying the Tcl commands and procedures that were being executed
-when the most recent error occurred.
-Its contents take the form of a stack trace showing the various
-nested Tcl commands that had been invoked at the time of the error.
-.TP
-\fBtcl_library\fR
-.
-This variable holds the name of a directory containing the
-system library of Tcl scripts, such as those used for auto-loading.
-The value of this variable is returned by the \fBinfo library\fR command.
-See the \fBlibrary\fR manual entry for details of the facilities
-provided by the Tcl script library.
-Normally each application or package will have its own application-specific
-script library in addition to the Tcl script library;
-each application should set a global variable with a name like
-\fB$\fIapp\fB_library\fR (where \fIapp\fR is the application's name)
-to hold the network file name for that application's library directory.
-The initial value of \fBtcl_library\fR is set when an interpreter
-is created by searching several different directories until one is
-found that contains an appropriate Tcl startup script.
-If the \fBTCL_LIBRARY\fR environment variable exists, then
-the directory it names is checked first.
-If \fBTCL_LIBRARY\fR is not set or doesn't refer to an appropriate
-directory, then Tcl checks several other directories based on a
-compiled-in default location, the location of the binary containing
-the application, and the current working directory.
-.TP
-\fBtcl_patchLevel\fR
-.
-When an interpreter is created Tcl initializes this variable to
-hold a string giving the current patch level for Tcl, such as
-\fB8.4.16\fR for Tcl 8.4 with the first sixteen official patches, or
-\fB8.5b3\fR for the third beta release of Tcl 8.5.
-The value of this variable is returned by the \fBinfo patchlevel\fR
-command.
-.TP
-\fBtcl_pkgPath\fR
-.
-This variable holds a list of directories indicating where packages are
-normally installed.  It is not used on Windows.  It typically contains
-either one or two entries; if it contains two entries, the first is
-normally a directory for platform-dependent packages (e.g., shared library
-binaries) and the second is normally a directory for platform-independent
-packages (e.g., script files). Typically a package is installed as a
-subdirectory of one of the entries in the \fBtcl_pkgPath\fR
-variable. The directories in the \fBtcl_pkgPath\fR variable are
-included by default in the \fBauto_path\fR
-variable, so they and their immediate subdirectories are automatically
-searched for packages during \fBpackage require\fR commands.  Note:
-\fBtcl_pkgPath\fR is not intended to be modified by the application.  Its
-value is added to \fBauto_path\fR at startup; changes to \fBtcl_pkgPath\fR
-are not reflected in \fBauto_path\fR.  If you want Tcl to search additional
-directories for packages you should add the names of those directories to
-\fBauto_path\fR, not \fBtcl_pkgPath\fR.
-.TP
-\fBtcl_platform\fR
-.
-This is an associative array whose elements contain information about
-the platform on which the application is running, such as the name of
-the operating system, its current release number, and the machine's
-instruction set.  The elements listed below will always
-be defined, but they may have empty strings as values if Tcl could not
-retrieve any relevant information.  In addition, extensions
-and applications may add additional values to the array.  The
-predefined elements are:
-.RS
-.TP
-\fBbyteOrder\fR
-.
-The native byte order of this machine: either \fBlittleEndian\fR or
-\fBbigEndian\fR.
-.TP
-\fBdebug\fR
-.
-If this variable exists, then the interpreter was compiled with and linked
-to a debug-enabled C run-time.  This variable will only exist on Windows,
-so extension writers can specify which package to load depending on the
-C run-time library that is in use.  This is not an indication that this core
-contains symbols.
-.TP
-\fBengine\fR
-.
-The name of the Tcl language implementation.  When the interpreter is first
-created, this is always set to the string \fBTcl\fR.
-.TP
-\fBmachine\fR
-.
-The instruction set executed by this machine, such as
-\fBintel\fR, \fBPPC\fR, \fB68k\fR, or \fBsun4m\fR.  On UNIX machines, this
-is the value returned by \fBuname -m\fR.
-.TP
-\fBos\fR
-.
-The name of the operating system running on this machine,
-such as \fBWindows NT\fR or \fBSunOS\fR.
-On UNIX machines, this is the value returned by \fBuname -s\fR.
-.TP
-\fBosVersion\fR
-.
-The version number for the operating system running on this machine.
-On UNIX machines, this is the value returned by \fBuname -r\fR.
-.TP
-\fBpathSeparator\fR
-.VS 8.6
-'\" Defined by TIP #315
-The character that should be used to \fBsplit\fR PATH-like environment
-variables into their corresponding list of directory names.
-.VE 8.6
-.TP
-\fBplatform\fR
-.
-Either \fBwindows\fR, or \fBunix\fR.  This identifies the
-general operating environment of the machine.
-.TP
-\fBpointerSize\fR
-.
-This gives the size of the native-machine pointer in bytes (strictly, it
-is same as the result of evaluating \fIsizeof(void*)\fR in C.)
-.TP
-\fBthreaded\fR
-.
-If this variable exists, then the interpreter
-was compiled with threads enabled.
-.TP
-\fBuser\fR
-.
-This identifies the
-current user based on the login information available on the platform.
-This value comes from the getuid() and getpwuid() system calls on Unix,
-and the value from the GetUserName() system call on Windows.
-.TP
-\fBwordSize\fR
-.
-This gives the size of the native-machine word in bytes (strictly, it
-is same as the result of evaluating \fIsizeof(long)\fR in C.)
-.RE
-.TP
-\fBtcl_precision\fR
-.
-This variable controls the number of digits to generate
-when converting floating-point values to strings.  It defaults
-to 0.  \fIApplications should not change this value;\fR it is
-provided for compatibility with legacy code.
-.PP
-.RS
-The default value of 0 is special, meaning that Tcl should
-convert numbers using as few digits as possible while still
-distinguishing any floating point number from its nearest
-neighbours.  It differs from using an arbitrarily high value
-for \fItcl_precision\fR in that an inexact number like \fI1.4\fR
-will convert as \fI1.4\fR rather than \fI1.3999999999999999\fR
-even though the latter is nearer to the exact value of the
-binary number.
-.RE
-.PP
-.RS
-If \fBtcl_precision\fR is not zero, then when Tcl converts a floating
-point number, it creates a decimal representation of at most
-\fBtcl_precision\fR significant digits; the result may be shorter if
-the shorter result represents the original number exactly. If no
-result of at most \fBtcl_precision\fR digits is an exact representation
-of the original number, the one that is closest to the original
-number is chosen.
-If the original number lies precisely between two equally accurate
-decimal representations, then the one with an even value for the least
-significant digit is chosen; for instance, if \fBtcl_precision\fR is 3, then
-0.3125 will convert to 0.312, not 0.313, while 0.6875 will convert to
-0.688, not 0.687. Any string of trailing zeroes that remains is trimmed.
-.RE
-.PP
-.RS
-a \fBtcl_precision\fR value of 17 digits is
-.QW perfect
-for IEEE floating-point in that it allows
-double-precision values to be converted to strings and back to
-binary with no loss of information. For this reason, you will often
-see it as a value in legacy code that must run on Tcl versions before
-8.5. It is no longer recommended; as noted above, a zero value is the
-preferred method.
-.RE
-.PP
-.RS
-All interpreters in a thread share a single \fBtcl_precision\fR value:
-changing it in one interpreter will affect all other interpreters as
-well.  Safe interpreters are not allowed to modify the
-variable.
-.RE
-.PP
-.RS
-Valid values for \fBtcl_precision\fR range from 0 to 17.
-.RE
-.TP
-\fBtcl_rcFileName\fR
-.
-This variable is used during initialization to indicate the name of a
-user-specific startup file.  If it is set by application-specific
-initialization, then the Tcl startup code will check for the existence
-of this file and \fBsource\fR it if it exists.  For example, for \fBwish\fR
-the variable is set to \fB~/.wishrc\fR for Unix and \fB~/wishrc.tcl\fR
-for Windows.
-.TP
-\fBtcl_traceCompile\fR
-.
-The value of this variable can be set to control
-how much tracing information
-is displayed during bytecode compilation.
-By default, \fBtcl_traceCompile\fR is zero and no information is displayed.
-Setting \fBtcl_traceCompile\fR to 1 generates a one-line summary in \fBstdout\fR
-whenever a procedure or top-level command is compiled.
-Setting it to 2 generates a detailed listing in \fBstdout\fR of the
-bytecode instructions emitted during every compilation.
-This variable is useful in
-tracking down suspected problems with the Tcl compiler.
-.PP
-.RS
-This variable and functionality only exist if
-\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation.
-.RE
-.TP
-\fBtcl_traceExec\fR
-.
-The value of this variable can be set to control
-how much tracing information
-is displayed during bytecode execution.
-By default, \fBtcl_traceExec\fR is zero and no information is displayed.
-Setting \fBtcl_traceExec\fR to 1 generates a one-line trace in \fBstdout\fR
-on each call to a Tcl procedure.
-Setting it to 2 generates a line of output
-whenever any Tcl command is invoked
-that contains the name of the command and its arguments.
-Setting it to 3 produces a detailed trace showing the result of
-executing each bytecode instruction.
-Note that when \fBtcl_traceExec\fR is 2 or 3,
-commands such as \fBset\fR and \fBincr\fR
-that have been entirely replaced by a sequence
-of bytecode instructions are not shown.
-Setting this variable is useful in
-tracking down suspected problems with the bytecode compiler
-and interpreter.
-.PP
-.RS
-This variable and functionality only exist if
-\fBTCL_COMPILE_DEBUG\fR was defined during Tcl's compilation.
-.RE
-.TP
-\fBtcl_wordchars\fR
-.
-The value of this variable is a regular expression that can be set to
-control what are considered
-.QW word
-characters, for instances like
-selecting a word by double-clicking in text in Tk.  It is platform
-dependent.  On Windows, it defaults to \fB\eS\fR, meaning anything
-but a Unicode space character.  Otherwise it defaults to \fB\ew\fR,
-which is any Unicode word character (number, letter, or underscore).
-.TP
-\fBtcl_nonwordchars\fR
-.
-The value of this variable is a regular expression that can be set to
-control what are considered
-.QW non-word
-characters, for instances like
-selecting a word by double-clicking in text in Tk.  It is platform
-dependent.  On Windows, it defaults to \fB\es\fR, meaning any Unicode space
-character.  Otherwise it defaults to \fB\eW\fR, which is anything but a
-Unicode word character (number, letter, or underscore).
-.TP
-\fBtcl_version\fR
-.
-When an interpreter is created Tcl initializes this variable to
-hold the version number for this version of Tcl in the form \fIx.y\fR.
-Changes to \fIx\fR represent major changes with probable
-incompatibilities and changes to \fIy\fR represent small enhancements and
-bug fixes that retain backward compatibility.
-The value of this variable is returned by the \fBinfo tclversion\fR
-command.
-.SH "OTHER GLOBAL VARIABLES"
-.PP
-The following variables are only guaranteed to exist in \fBtclsh\fR
-and \fBwish\fR executables; the Tcl library does not define them
-itself but many Tcl environments do.
-.TP 6
-\fBargc\fR
-.
-The number of arguments to \fBtclsh\fR or \fBwish\fR.
-.TP 6
-\fBargv\fR
-.
-Tcl list of arguments to \fBtclsh\fR or \fBwish\fR.
-.TP 6
-\fBargv0\fR
-.
-The script that \fBtclsh\fR or \fBwish\fR started executing (if it was
-specified) or otherwise the name by which \fBtclsh\fR or \fBwish\fR
-was invoked.
-.TP 6
-\fBtcl_interactive\fR
-.
-Contains 1 if \fBtclsh\fR or \fBwish\fR is running interactively (no
-script was specified and standard input is a terminal-like device), 0
-otherwise.
-.SH EXAMPLES
-.PP
-To add a directory to the collection of locations searched by
-\fBpackage require\fR, e.g., because of some application-specific
-packages that are used, the \fBauto_path\fR variable needs to be
-updated:
-.PP
-.CS
-lappend ::\fBauto_path\fR [file join [pwd] "theLibDir"]
-.CE
-.PP
-A simple though not very robust way to handle command line arguments
-of the form
-.QW "\-foo 1 \-bar 2"
-is to load them into an array having first loaded in the default settings:
-.CS
-array set arguments {-foo 0 -bar 0 -grill 0}
-array set arguments $::\fBargv\fR
-puts "foo is $arguments(-foo)"
-puts "bar is $arguments(-bar)"
-puts "grill is $arguments(-grill)"
-.CE
-.PP
-The \fBargv0\fR global variable can be used (in conjunction with the
-\fBinfo script\fR command) to determine whether the current script is
-being executed as the main script or loaded as a library.  This is
-useful because it allows a single script to be used as both a library
-and a demonstration of that library:
-.PP
-.CS
-if {$::\fBargv0\fR eq [info script]} {
-    # running as: tclsh example.tcl
-} else {
-    package provide Example 1.0
-}
-.CE
-.SH "SEE ALSO"
-eval(n), library(n), tclsh(1), tkvars(n), wish(1)
-.SH KEYWORDS
-arithmetic, bytecode, compiler, error, environment, POSIX, precision,
-subprocess, user, variables
-'\" Local Variables:
-'\" mode: nroff
-'\" End: