Tcl Source Code

Check-in [b67e3f215e]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:
* changes: Updated for 8.5b2 release.
* doc/*.1: Revert doc changes that broke * doc/*.3: `make html` so we can get the release * doc/*.n: out the door.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk | core-8-5-b2
Files: files | file ages | folders
SHA1: b67e3f215e5ed2c3abc44b48bd54a2c3a7ad948a
User & Date: dgp 2007-10-26 20:11:50
Context
2007-10-26
23:52
Make the man->HTML scraper work better. check-in: 84dfc4343b user: dkf tags: trunk
20:11
* changes: Updated for 8.5b2 release.
* doc/*.1: Revert d...
check-in: b67e3f215e user: dgp tags: trunk, core-8-5-b2
16:54
tag: 8.5b2 check-in: 3b4a8c5724 user: dgp tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to ChangeLog.

     1      1   2007-10-26  Don Porter	<[email protected]>
     2      2   
     3      3   	*** 8.5b2 TAGGED FOR RELEASE ***
     4      4   
     5      5   	* changes:		Updated for 8.5b2 release.
            6  +
            7  +	* doc/*.1:		Revert doc changes that broke
            8  +	* doc/*.3:		`make html` so we can get the release
            9  +	* doc/*.n:		out the door.
     6     10   
     7     11   	* README:		Bump version number to 8.5b2.
     8     12   	* generic/tcl.h:
     9     13   	* library/init.tcl:
    10     14   	* tools/tcl.wse.in:
    11     15   	* unix/configure.in:
    12     16   	* unix/tcl.spec:

Changes to changes.

     1      1   Recent user-visible changes to Tcl:
     2      2   
     3         -RCS: @(#) $Id: changes,v 1.120 2007/10/26 15:53:43 dgp Exp $
            3  +RCS: @(#) $Id: changes,v 1.121 2007/10/26 20:11:50 dgp Exp $
     4      4   
     5      5   1. No more [command1] [command2] construct for grouping multiple
     6      6   commands on a single command line.
     7      7   
     8      8   2. Semi-colon now available for grouping commands on a line.
     9      9   
    10     10   3. For a command to span multiple lines, must now use backslash-return
................................................................................
  7031   7031   
  7032   7032   2007-10-11 (bug fix)[1805887] [string is int -failindex] for 0o, 0b (porter)
  7033   7033   
  7034   7034   2007-10-15 (bug fix)[1813528] Tcl_ParseBraces read past buffer (mistachkin)
  7035   7035   
  7036   7036   2007-10-25 (bug fix)[1726873] intermittent crash in threads (vasiljevic)
  7037   7037   
  7038         -New doc macros for improved formatting.  Docs updated to use. (fellows)
  7039         -
  7040   7038   --- Released 8.5b2, October 26, 2007 --- See ChangeLog for details ---

Changes to doc/AppInit.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: AppInit.3,v 1.6 2007/10/24 14:29:37 dkf Exp $
            8  +'\" RCS: @(#) $Id: AppInit.3,v 1.7 2007/10/26 20:11:51 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_AppInit \- perform application-specific initialization
    15     15   .SH SYNOPSIS
................................................................................
    22     22   .AS Tcl_Interp *interp
    23     23   .AP Tcl_Interp *interp in
    24     24   Interpreter for the application.
    25     25   .BE
    26     26   
    27     27   .SH DESCRIPTION
    28     28   .PP
    29         -\fBTcl_AppInit\fR is a
    30         -.QW hook
    31         -procedure that is invoked by
           29  +\fBTcl_AppInit\fR is a ``hook'' procedure that is invoked by
    32     30   the main programs for Tcl applications such as \fBtclsh\fR and \fBwish\fR.
    33     31   Its purpose is to allow new Tcl applications to be created without
    34     32   modifying the main programs provided as part of Tcl and Tk.
    35     33   To create a new application you write a new version of
    36     34   \fBTcl_AppInit\fR to replace the default version provided by Tcl,
    37     35   then link your new \fBTcl_AppInit\fR with the Tcl library.
    38     36   .PP

Changes to doc/BackgdErr.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1992-1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: BackgdErr.3,v 1.5 2007/10/24 14:29:37 dkf Exp $
            8  +'\" RCS: @(#) $Id: BackgdErr.3,v 1.6 2007/10/26 20:11:51 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_BackgroundError \- report Tcl error that occurred in background processing
    15     15   .SH SYNOPSIS
................................................................................
    22     22   .AP Tcl_Interp *interp in
    23     23   Interpreter in which the error occurred.
    24     24   .BE
    25     25   
    26     26   .SH DESCRIPTION
    27     27   .PP
    28     28   This procedure is typically invoked when a Tcl error occurs during
    29         -.QW "background processing"
    30         -such as executing an event handler.
           29  +``background processing'' such as executing an event handler.
    31     30   When such an error occurs, the error condition is reported to Tcl
    32     31   or to a widget or some other C code, and there is not usually any
    33     32   obvious way for that code to report the error to the user.
    34     33   In these cases the code calls \fBTcl_BackgroundError\fR with an
    35     34   \fIinterp\fR argument identifying the interpreter in which the
    36     35   error occurred.  At the time \fBTcl_BackgroundError\fR is invoked,
    37     36   the interpreter's result is expected to contain an error message.

Changes to doc/CrtChannel.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
     3      3   '\" Copyright (c) 1997-2000 Ajuba Solutions.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\"
     8         -'\" RCS: @(#) $Id: CrtChannel.3,v 1.36 2007/10/24 14:29:37 dkf Exp $
            8  +'\" RCS: @(#) $Id: CrtChannel.3,v 1.37 2007/10/26 20:11:51 dgp Exp $
     9      9   .so man.macros
    10     10   .TH Tcl_CreateChannel 3 8.4 Tcl "Tcl Library Procedures"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption, Tcl_ChannelName, Tcl_ChannelVersion, Tcl_ChannelBlockModeProc, Tcl_ChannelCloseProc, Tcl_ChannelClose2Proc, Tcl_ChannelInputProc, Tcl_ChannelOutputProc, Tcl_ChannelSeekProc, Tcl_ChannelWideSeekProc, Tcl_ChannelTruncateProc, Tcl_ChannelSetOptionProc, Tcl_ChannelGetOptionProc, Tcl_ChannelWatchProc, Tcl_ChannelGetHandleProc, Tcl_ChannelFlushProc, Tcl_ChannelHandlerProc, Tcl_ChannelThreadActionProc, Tcl_IsChannelShared, Tcl_IsChannelRegistered, Tcl_CutChannel, Tcl_SpliceChannel, Tcl_IsChannelExisting, Tcl_ClearChannelHandlers, Tcl_GetChannelThread, Tcl_ChannelBuffered \- procedures for creating and manipulating channels
    15     15   .SH SYNOPSIS
................................................................................
   869    869   .CS
   870    870       bad option "-blah": should be one of -blocking,
   871    871       -buffering, -buffersize, -eofchar, -translation,
   872    872       -peername, or -sockname
   873    873   .CE
   874    874   when called with \fIoptionList\fR="peername sockname"
   875    875   .PP
   876         -.QW blah
   877         -is the \fIoptionName\fR argument and
   878         -.QW "<specific options>"
          876  +``blah'' is the \fIoptionName\fR argument and ``<specific options>''
   879    877   is a space separated list of specific option words.
   880    878   The function takes good care of inserting minus signs before
   881         -each option, commas after, and an
   882         -.QW or
   883         -before the last option.
          879  +each option, commas after, and an ``or'' before the last option.
   884    880   .SH "OLD CHANNEL TYPES"
   885    881   The original (8.3.1 and below) \fBTcl_ChannelType\fR structure contains
   886    882   the following fields:
   887    883   .PP
   888    884   .CS
   889    885   typedef struct Tcl_ChannelType {
   890    886           char *\fItypeName\fR;

Changes to doc/CrtSlave.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: CrtSlave.3,v 1.17 2007/10/24 14:29:37 dkf Exp $
            7  +'\" RCS: @(#) $Id: CrtSlave.3,v 1.18 2007/10/26 20:11:51 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
    11     11   .BS
    12     12   .SH NAME
    13     13   Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands
    14     14   .SH SYNOPSIS
................................................................................
    57     57   .SH ARGUMENTS
    58     58   .AS "const char *const" **targetInterpPtr out
    59     59   .AP Tcl_Interp *interp in
    60     60   Interpreter in which to execute the specified command.
    61     61   .AP "const char" *slaveName in
    62     62   Name of slave interpreter to create or manipulate.
    63     63   .AP int isSafe in
    64         -If non-zero, a
    65         -.QW safe
    66         -slave that is suitable for running untrusted code
           64  +If non-zero, a ``safe'' slave that is suitable for running untrusted code
    67     65   is created, otherwise a trusted slave is created.
    68     66   .AP Tcl_Interp *slaveInterp in
    69     67   Interpreter to use for creating the source command for an alias (see
    70     68   below).
    71     69   .AP "const char" *slaveCmd in
    72     70   Name of source command for alias.
    73     71   .AP Tcl_Interp *targetInterp in
................................................................................
   124    122   then the \fBresult\fR field of the interpreter contains an error message.
   125    123   .PP
   126    124   \fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR.
   127    125   It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which 
   128    126   allows \fIinterp\fR to manipulate the new slave. 
   129    127   If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
   130    128   code has access to all the Tcl commands.
   131         -If it is \fB1\fR, the command creates a
   132         -.QW safe
   133         -slave in which Tcl code has access only to set of Tcl commands defined as
   134         -.QW "Safe Tcl" ;
   135         -see the manual entry for the Tcl \fBinterp\fR command for details.
          129  +If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code
          130  +has access only to set of Tcl commands defined as ``Safe Tcl''; see the
          131  +manual entry for the Tcl \fBinterp\fR command for details.
   136    132   If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
   137    133   .PP
   138         -\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is
   139         -.QW safe
   140         -(was created with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
          134  +\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created
          135  +with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
   141    136   \fB0\fR otherwise.
   142    137   .PP
   143         -\fBTcl_MakeSafe\fR marks \fIinterp\fR as
   144         -.QW safe ,
   145         -so that future
          138  +\fBTcl_MakeSafe\fR marks \fIinterp\fR as ``safe'', so that future
   146    139   calls to \fBTcl_IsSafe\fR will return 1.  It also removes all known
   147    140   potentially-unsafe core functionality (both commands and variables)
   148    141   from \fIinterp\fR.  However, it cannot know what parts of an extension
   149    142   or application are safe and does not make any attempt to remove those
   150    143   parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
   151    144   Callers will want to take care with their use of \fBTcl_MakeSafe\fR
   152    145   to avoid false claims of safety.  For many situations, \fBTcl_CreateSlave\fR

Changes to doc/DString.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: DString.3,v 1.14 2007/10/24 14:29:37 dkf Exp $
            8  +'\" RCS: @(#) $Id: DString.3,v 1.15 2007/10/26 20:11:51 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
    15     15   .SH SYNOPSIS
................................................................................
    89     89   \fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR
    90     90   except that it doesn't take a \fIlength\fR argument (it appends
    91     91   all of \fIelement\fR) and it converts the string to a proper list element
    92     92   before appending.
    93     93   \fBTcl_DStringAppendElement\fR adds a separator space before the
    94     94   new list element unless the new list element is the first in a
    95     95   list or sub-list (i.e. either the current string is empty, or it
    96         -contains the single character
    97         -.QW { ,
    98         -or the last two characters of the current string are
    99         -.QW " {" ).
           96  +contains the single character ``{'', or the last two characters of
           97  +the current string are `` {'').
   100     98   \fBTcl_DStringAppendElement\fR returns a pointer to the
   101     99   characters of the new string.
   102    100   .PP
   103    101   \fBTcl_DStringStartSublist\fR and \fBTcl_DStringEndSublist\fR can be
   104    102   used to create nested lists.
   105    103   To append a list element that is itself a sublist, first
   106    104   call \fBTcl_DStringStartSublist\fR, then call \fBTcl_DStringAppendElement\fR

Changes to doc/Encoding.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1997-1998 Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: Encoding.3,v 1.26 2007/10/24 14:29:37 dkf Exp $
            7  +'\" RCS: @(#) $Id: Encoding.3,v 1.27 2007/10/26 20:11:51 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
    11     11   .BS
    12     12   .SH NAME
    13     13   Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtf, Tcl_UtfToExternalDString, Tcl_UtfToExternal, Tcl_WinTCharToUtf, Tcl_WinUtfToTChar, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath, Tcl_GetDefaultEncodingDir, Tcl_SetDefaultEncodingDir \- procedures for creating and using encodings
    14     14   .SH SYNOPSIS
................................................................................
   453    453   ignored.
   454    454   .PP
   455    455   \fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR
   456    456   are obsolete interfaces best replaced with calls to
   457    457   \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR.
   458    458   They are called to access and set the first element of the \fIsearchPath\fR
   459    459   list.  Since Tcl searches \fIsearchPath\fR for encoding data files in
   460         -list order, these routines establish the
   461         -.QW default
   462         -directory in which to find encoding data files.
          460  +list order, these routines establish the ``default'' directory in which
          461  +to find encoding data files.
   463    462   .VE 8.5
   464    463   .SH "ENCODING FILES"
   465    464   Space would prohibit precompiling into Tcl every possible encoding
   466    465   algorithm, so many encodings are stored on disk as dynamically-loadable
   467    466   encoding files.  This behavior also allows the user to create additional
   468    467   encoding files that can be loaded using the same mechanism.  These
   469    468   encoding files contain information about the tables and/or escape
   470    469   sequences used to map between an external encoding and Unicode.  The
   471    470   external encoding may consist of single-byte, multi-byte, or double-byte
   472    471   characters.  
   473    472   .PP
   474    473   Each dynamically-loadable encoding is represented as a text file.  The
   475         -initial line of the file, beginning with a
   476         -.QW #
   477         -symbol, is a comment
          474  +initial line of the file, beginning with a ``#'' symbol, is a comment
   478    475   that provides a human-readable description of the file.  The next line
   479    476   identifies the type of encoding file.  It can be one of the following
   480    477   letters:
   481    478   .IP "[1] \fBS\fR"
   482    479   A single-byte encoding, where one character is always one byte long in the
   483    480   encoding.  An example is \fBiso8859-1\fR, used by many European languages.
   484    481   .IP "[2] \fBD\fR"
................................................................................
   583    580   .PP
   584    581   In the file, the first column represents an option and the second column
   585    582   is the associated value.  \fBinit\fR is a string to emit or expect before
   586    583   the first character is converted, while \fBfinal\fR is a string to emit
   587    584   or expect after the last character.  All other options are names of
   588    585   table-based encodings; the associated value is the escape-sequence that
   589    586   marks that encoding.  Tcl syntax is used for the values; in the above
   590         -example, for instance,
   591         -.QW \fB{}\fR
   592         -represents the empty string and
   593         -.QW \fB\ex1b\fR
   594         -represents character 27.
          587  +example, for instance, ``\fB{}\fR'' represents the empty string and
          588  +``\fB\\x1b\fR'' represents character 27.
   595    589   .PP
   596    590   When \fBTcl_GetEncoding\fR encounters an encoding \fIname\fR that has not
   597    591   been loaded, it attempts to load an encoding file called \fIname\fB.enc\fR
   598    592   from the \fBencoding\fR subdirectory of each directory that Tcl searches
   599    593   for its script library.  If the encoding file exists, but is
   600    594   malformed, an error message will be left in \fIinterp\fR.
   601    595   .SH KEYWORDS
   602    596   utf, encoding, convert

Changes to doc/Eval.3.

     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2000 Scriptics Corporation.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: Eval.3,v 1.24 2007/10/24 14:29:37 dkf Exp $
            9  +'\" RCS: @(#) $Id: Eval.3,v 1.25 2007/10/26 20:11:51 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH Tcl_Eval 3 8.1 Tcl "Tcl Library Procedures"
    13     13   .BS
    14     14   .SH NAME
    15     15   Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx, Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA \- execute Tcl scripts
    16     16   .SH SYNOPSIS
................................................................................
    97     97   .PP
    98     98   \fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
    99     99   its contents as a Tcl script.  It returns the same information as
   100    100   \fBTcl_EvalObjEx\fR.
   101    101   If the file couldn't be read then a Tcl error is returned to describe
   102    102   why the file couldn't be read.
   103    103   The eofchar for files is '\\32' (^Z) for all platforms.
   104         -If you require a
   105         -.QW ^Z
   106         -in code for string comparison, you can use
   107         -.QW \e032
   108         -or
   109         -.QW \eu001a ,
   110         -which will be safely substituted by the Tcl interpreter into
   111         -.QW ^Z .
          104  +If you require a ``^Z'' in code for string comparison, you can use
          105  +``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
          106  +interpreter into ``^Z''.
   112    107   .PP
   113    108   \fBTcl_EvalObjv\fR executes a single pre-parsed command instead of a
   114    109   script.  The \fIobjc\fR and \fIobjv\fR arguments contain the values
   115    110   of the words for the Tcl command, one word in each object in
   116    111   \fIobjv\fR.  \fBTcl_EvalObjv\fR evaluates the command and returns
   117    112   a completion code and result just like \fBTcl_EvalObjEx\fR.
   118    113   The caller of \fBTcl_EvalObjv\fR has to manage the reference count of the

Changes to doc/ExprLong.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: ExprLong.3,v 1.12 2007/10/24 14:29:37 dkf Exp $
            8  +'\" RCS: @(#) $Id: ExprLong.3,v 1.13 2007/10/26 20:11:51 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString \- evaluate an expression
    15     15   .SH SYNOPSIS
................................................................................
    87     87   an error is returned.
    88     88   .PP
    89     89   \fBTcl_ExprBoolean\fR stores a 0/1 integer value at \fI*booleanPtr\fR.
    90     90   If the expression's actual value is an integer or floating-point
    91     91   number, then they store 0 at \fI*booleanPtr\fR if
    92     92   the value was zero and 1 otherwise.
    93     93   If the expression's actual value is a non-numeric string then
    94         -it must be one of the values accepted by \fBTcl_GetBoolean\fR such as
    95         -.QW yes
    96         -or
    97         -.QW no ,
    98         -or else an error occurs.
           94  +it must be one of the values accepted by \fBTcl_GetBoolean\fR
           95  +such as ``yes'' or ``no'', or else an error occurs.
    99     96   .PP
   100     97   \fBTcl_ExprString\fR returns the value of the expression as a
   101     98   string stored in the interpreter's result.
   102     99   
   103    100   .SH "SEE ALSO"
   104    101   Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj
   105    102   
   106    103   .SH KEYWORDS
   107    104   boolean, double, evaluate, expression, integer, object, string

Changes to doc/ExprLongObj.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: ExprLongObj.3,v 1.6 2007/10/24 14:29:37 dkf Exp $
            7  +'\" RCS: @(#) $Id: ExprLongObj.3,v 1.7 2007/10/26 20:11:51 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures"
    11     11   .BS
    12     12   .SH NAME
    13     13   Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj \- evaluate an expression
    14     14   .SH SYNOPSIS
................................................................................
    83     83   an error is returned.
    84     84   .PP
    85     85   \fBTcl_ExprBooleanObj\fR stores a 0/1 integer value at \fI*booleanPtr\fR.
    86     86   If the expression's actual value is an integer or floating-point
    87     87   number, then they store 0 at \fI*booleanPtr\fR if
    88     88   the value was zero and 1 otherwise.
    89     89   If the expression's actual value is a non-numeric string then
    90         -it must be one of the values accepted by \fBTcl_GetBoolean\fR such as
    91         -.QW yes
    92         -or
    93         -.QW no ,
    94         -or else an error occurs.
           90  +it must be one of the values accepted by \fBTcl_GetBoolean\fR
           91  +such as ``yes'' or ``no'', or else an error occurs.
    95     92   .PP
    96     93   If \fBTcl_ExprObj\fR successfully evaluates the expression,
    97     94   it stores a pointer to the Tcl object
    98     95   containing the expression's value at \fI*resultPtrPtr\fR.
    99     96   In this case, the caller is responsible for calling
   100     97   \fBTcl_DecrRefCount\fR to decrement the object's reference count
   101     98   when it is finished with the object.
   102     99   
   103    100   .SH "SEE ALSO"
   104    101   Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult
   105    102   
   106    103   .SH KEYWORDS
   107    104   boolean, double, evaluate, expression, integer, object, string

Changes to doc/FileSystem.3.

     1      1   '\"
     2      2   '\" Copyright (c) 2001 Vincent Darley
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: FileSystem.3,v 1.58 2007/10/24 14:29:37 dkf Exp $
            7  +'\" RCS: @(#) $Id: FileSystem.3,v 1.59 2007/10/26 20:11:51 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
    11     11   .BS
    12     12   .SH NAME
    13     13   Tcl_FSRegister, Tcl_FSUnregister, Tcl_FSData, Tcl_FSMountsChanged, Tcl_FSGetFileSystemForPath, Tcl_FSGetPathType, Tcl_FSCopyFile, Tcl_FSCopyDirectory, Tcl_FSCreateDirectory, Tcl_FSDeleteFile, Tcl_FSRemoveDirectory, Tcl_FSRenameFile, Tcl_FSListVolumes, Tcl_FSEvalFile, Tcl_FSEvalFileEx, Tcl_FSLoadFile, Tcl_FSMatchInDirectory, Tcl_FSLink, Tcl_FSLstat, Tcl_FSUtime, Tcl_FSFileAttrsGet, Tcl_FSFileAttrsSet, Tcl_FSFileAttrStrings, Tcl_FSStat, Tcl_FSAccess, Tcl_FSOpenFileChannel, Tcl_FSGetCwd, Tcl_FSChdir, Tcl_FSPathSeparator, Tcl_FSJoinPath, Tcl_FSSplitPath, Tcl_FSEqualPaths, Tcl_FSGetNormalizedPath, Tcl_FSJoinToPath, Tcl_FSConvertToPathType, Tcl_FSGetInternalRep, Tcl_FSGetTranslatedPath, Tcl_FSGetTranslatedStringPath, Tcl_FSNewNativePath, Tcl_FSGetNativePath, Tcl_FSFileSystemInfo, Tcl_AllocStatBuf \- procedures to interact with any filesystem
    14     14   .SH SYNOPSIS
................................................................................
   348    348   its contents as a Tcl script.  It returns the same information as
   349    349   \fBTcl_EvalObjEx\fR.
   350    350   If \fIencodingName\fR is NULL, the system encoding is used for
   351    351   reading the file contents.
   352    352   If the file couldn't be read then a Tcl error is returned to describe
   353    353   why the file couldn't be read.
   354    354   The eofchar for files is '\\32' (^Z) for all platforms.
   355         -If you require a
   356         -.QW ^Z
   357         -in code for string comparison, you can use
   358         -.QW \e032
   359         -or
   360         -.QW \eu001a ,
   361         -which will be safely substituted by the Tcl interpreter into
   362         -.QW ^Z .
          355  +If you require a ``^Z'' in code for string comparison, you can use
          356  +``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
          357  +interpreter into ``^Z''.
   363    358   \fBTcl_FSEvalFile\fR is a simpler version of
   364    359   \fBTcl_FSEvalFileEx\fR that always uses the system encoding
   365    360   when reading the file.
   366    361   .VE 8.5
   367    362   .PP
   368    363   \fBTcl_FSLoadFile\fR dynamically loads a binary code file into memory and
   369    364   returns the addresses of two procedures within that file, if they are
................................................................................
   846    841   a particular filesystem with a file path, and deal with the internal
   847    842   handling of path representations, for example copying and freeing such
   848    843   representations.
   849    844   .SS TYPENAME
   850    845   .PP
   851    846   The \fItypeName\fR field contains a null-terminated string that
   852    847   identifies the type of the filesystem implemented, e.g.
   853         -.QW native ,
   854         -.QW zip
   855         -or
   856         -.QW vfs .
          848  +``native'' or ``zip'' or ```vfs''.
   857    849   .SS "STRUCTURE LENGTH"
   858    850   .PP
   859    851   The \fIstructureLength\fR field is generally implemented as
   860    852   \fIsizeof(Tcl_Filesystem)\fR, and is there to allow easier
   861    853   binary backwards compatibility if the size of the structure
   862    854   changes in a future Tcl release.
   863    855   .SS VERSION

Changes to doc/GetInt.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: GetInt.3,v 1.11 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: GetInt.3,v 1.12 2007/10/26 20:11:51 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, double, or boolean
    15     15   .SH SYNOPSIS
................................................................................
    51     51   desired type then \fBTCL_ERROR\fR is returned, an error message is left
    52     52   in the interpreter's result, and nothing is stored at *\fIintPtr\fR
    53     53   or *\fIdoublePtr\fR or *\fIboolPtr\fR.
    54     54   .PP
    55     55   \fBTcl_GetInt\fR expects \fIsrc\fR to consist of a collection
    56     56   of integer digits, optionally signed and optionally preceded by
    57     57   white space.  If the first two characters of \fIsrc\fR
    58         -after the optional white space and sign are
    59         -.QW 0x
           58  +after the optional white space and sign are ``0x''
    60     59   then \fIsrc\fR is expected to be in hexadecimal form;  otherwise,
    61         -if the first such character is
    62         -.QW 0
    63         -then \fIsrc\fR
           60  +if the first such character is ``0'' then \fIsrc\fR
    64     61   is expected to be in octal form;  otherwise, \fIsrc\fR is
    65     62   expected to be in decimal form.
    66     63   .PP
    67     64   \fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
    68     65   number, which is:  white space;  a sign; a sequence of digits;  a
    69         -decimal point;  a sequence of digits;  the letter
    70         -.QW e ;
    71         -a signed decimal exponent ; and more white space.
           66  +decimal point;  a sequence of digits;  the letter ``e'';  a
           67  +signed decimal exponent ; and more white space.
    72     68   Any of the fields may be omitted, except that
    73     69   the digits either before or after the decimal point must be present
    74         -and if the
    75         -.QW e
    76         -is present then it must be followed by the exponent number.
           70  +and if the ``e'' is present then it must be followed by the
           71  +exponent number.
    77     72   .PP
    78     73   \fBTcl_GetBoolean\fR expects \fIsrc\fR to specify a boolean
    79     74   value.  If \fIsrc\fR is any of \fB0\fR, \fBfalse\fR,
    80     75   \fBno\fR, or \fBoff\fR, then \fBTcl_GetBoolean\fR stores a zero
    81     76   value at \fI*boolPtr\fR.
    82     77   If \fIsrc\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
    83     78   then 1 is stored at \fI*boolPtr\fR.
    84     79   Any of these values may be abbreviated, and upper-case spellings
    85     80   are also acceptable.
    86     81   
    87     82   .SH KEYWORDS
    88     83   boolean, conversion, double, floating-point, integer

Changes to doc/Hash.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: Hash.3,v 1.22 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: Hash.3,v 1.23 2007/10/26 20:11:51 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_InitHashTable, Tcl_InitCustomHashTable, Tcl_InitObjHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables
    15     15   .SH SYNOPSIS
................................................................................
    84     84   may have the same value.  Keys can take one of four forms: strings,
    85     85   one-word values, integer arrays, or custom keys defined by a
    86     86   Tcl_HashKeyType structure (See section \fBTHE TCL_HASHKEYTYPE
    87     87   STRUCTURE\fR below). All of the keys in a given table have the same
    88     88   form, which is specified when the table is initialized.
    89     89   .PP
    90     90   The value of a hash table entry can be anything that fits in the same
    91         -space as a
    92         -.QW "char *"
    93         -pointer.  Values for hash table entries are
           91  +space as a ``char *'' pointer.  Values for hash table entries are
    94     92   managed entirely by clients, not by the hash module itself.  Typically
    95     93   each entry's value is a pointer to a data structure managed by client
    96     94   code.
    97     95   .PP
    98     96   Hash tables grow gracefully as the number of entries increases, so
    99     97   that there are always less than three entries per hash bucket, on
   100     98   average. This allows for fast lookups regardless of the number of
................................................................................
   122    120   \fIKeyType\fR must have one of the following values:
   123    121   .IP \fBTCL_STRING_KEYS\fR 25
   124    122   Keys are null-terminated strings.
   125    123   They are passed to hashing routines using the address of the
   126    124   first character of the string.
   127    125   .IP \fBTCL_ONE_WORD_KEYS\fR 25
   128    126   Keys are single-word values;  they are passed to hashing routines
   129         -and stored in hash table entries as
   130         -.QW "char *"
   131         -values.
          127  +and stored in hash table entries as ``char *'' values.
   132    128   The pointer value is the key;  it need not (and usually doesn't)
   133    129   actually point to a string.
   134    130   .IP \fBTCL_CUSTOM_TYPE_KEYS\fR 25
   135    131   Keys are of arbitrary type, and are stored in the entry. Hashing
   136    132   and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType 
   137    133   structure is described in the section 
   138    134   \fBTHE TCL_HASHKEYTYPE STRUCTURE\fR below.
................................................................................
   140    136   Keys are pointers to an arbitrary type, and are stored in the entry. Hashing
   141    137   and comparison is determined by \fItypePtr\fR. The Tcl_HashKeyType 
   142    138   structure is described in the section 
   143    139   \fBTHE TCL_HASHKEYTYPE STRUCTURE\fR below.
   144    140   .IP \fIother\fR 25
   145    141   If \fIkeyType\fR is not one of the above,
   146    142   then it must be an integer value greater than 1.
   147         -In this case the keys will be arrays of
   148         -.QW int
   149         -values, where \fIkeyType\fR gives the number of ints in each key.
          143  +In this case the keys will be arrays of ``int'' values, where
          144  +\fIkeyType\fR gives the number of ints in each key.
   150    145   This allows structures to be used as keys.
   151    146   All keys must have the same size.
   152    147   Array keys are passed into hashing functions using the address
   153    148   of the first int in the array.
   154    149   .PP
   155    150   \fBTcl_DeleteHashTable\fR deletes all of the entries in a hash
   156    151   table and frees up the memory associated with the table's
................................................................................
   183    178   .PP
   184    179   \fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR
   185    180   except that it doesn't create a new entry if the key doesn't exist;
   186    181   instead, it returns NULL as result.
   187    182   .PP
   188    183   \fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to
   189    184   read and write an entry's value, respectively.
   190         -Values are stored and retrieved as type
   191         -.QW ClientData ,
   192         -which is
          185  +Values are stored and retrieved as type ``ClientData'', which is
   193    186   large enough to hold a pointer value.  On almost all machines this is
   194    187   large enough to hold an integer value too.
   195    188   .PP
   196    189   \fBTcl_GetHashKey\fR returns the key for a given hash table entry,
   197         -either as a pointer to a string, a one-word (e.g.
   198         -.QW "char *" )
   199         -key, or as a pointer to the first word of an array of integers, depending
          190  +either as a pointer to a string, a one-word (``char *'') key, or
          191  +as a pointer to the first word of an array of integers, depending
   200    192   on the \fIkeyType\fR used to create a hash table.
   201    193   In all cases \fBTcl_GetHashKey\fR returns a result with type
   202         -.QW "char *" .
          194  +``char *''.
   203    195   When the key is a string or array, the result of \fBTcl_GetHashKey\fR
   204    196   points to information in the table entry;  this information will
   205    197   remain valid until the entry is deleted or its table is deleted.
   206    198   .PP
   207    199   \fBTcl_FirstHashEntry\fR and \fBTcl_NextHashEntry\fR may be used
   208         -to scan all of the entries in a hash table. A structure of type
   209         -.QW Tcl_HashSearch ,
   210         -provided by the client, is used to keep track of progress through the
   211         -table. \fBTcl_FirstHashEntry\fR initializes the search record and
          200  +to scan all of the entries in a hash table.
          201  +A structure of type ``Tcl_HashSearch'', provided by the client,
          202  +is used to keep track of progress through the table.
          203  +\fBTcl_FirstHashEntry\fR initializes the search record and
   212    204   returns the first entry in the table (or NULL if the table is
   213    205   empty).
   214    206   Each subsequent call to \fBTcl_NextHashEntry\fR returns the
   215    207   next entry in the table or
   216    208   NULL if the end of the table has been reached.
   217    209   A call to \fBTcl_FirstHashEntry\fR followed by calls to
   218    210   \fBTcl_NextHashEntry\fR will return each of the entries in

Changes to doc/LinkVar.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: LinkVar.3,v 1.13 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: LinkVar.3,v 1.14 2007/10/26 20:11:51 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
    15     15   .SH SYNOPSIS
................................................................................
   162    162   '\" FIXME! Use bignums instead.
   163    163   attempts to write non-integer values into \fIvarName\fR will be
   164    164   rejected with Tcl errors.
   165    165   .VE 8.5
   166    166   .TP
   167    167   \fBTCL_LINK_BOOLEAN\fR
   168    168   The C variable is of type \fBint\fR.
   169         -If its value is zero then it will read from Tcl as
   170         -.QW 0 ;
   171         -otherwise it will read from Tcl as
   172         -.QW 1 .
          169  +If its value is zero then it will read from Tcl as ``0'';
          170  +otherwise it will read from Tcl as ``1''.
   173    171   Whenever \fIvarName\fR is
   174    172   modified, the C variable will be set to a 0 or 1 value.
   175    173   Any value written into the Tcl variable must have a proper boolean
   176    174   form acceptable to \fBTcl_GetBooleanFromObj\fR;  attempts to write
   177    175   non-boolean values into \fIvarName\fR will be rejected with
   178    176   Tcl errors.
   179    177   .TP
................................................................................
   181    179   The C variable is of type \fBchar *\fR.
   182    180   If its value is not NULL then it must be a pointer to a string
   183    181   allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
   184    182   Whenever the Tcl variable is modified the current C string will be
   185    183   freed and new memory will be allocated to hold a copy of the variable's
   186    184   new value.
   187    185   If the C variable contains a NULL pointer then the Tcl variable
   188         -will read as
   189         -.QW NULL .
          186  +will read as ``NULL''.
   190    187   .PP
   191    188   If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
   192    189   variable will be read-only from Tcl, so that its value can only be
   193    190   changed by modifying the C variable.
   194    191   Attempts to write the variable from Tcl will be rejected with errors.
   195    192   .PP
   196    193   \fBTcl_UnlinkVar\fR removes the link previously set up for the

Changes to doc/Notifier.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1998-1999 Scriptics Corporation
     3      3   '\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: Notifier.3,v 1.18 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: Notifier.3,v 1.19 2007/10/26 20:11:51 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces
    15     15   .SH SYNOPSIS
................................................................................
   450    450   \fBTcl_InitNotifier\fR initializes the notifier state and returns
   451    451   a handle to the notifier state.  Tcl calls this
   452    452   procedure when initializing a Tcl interpreter.  Similarly,
   453    453   \fBTcl_FinalizeNotifier\fR shuts down the notifier, and is
   454    454   called by \fBTcl_Finalize\fR when shutting down a Tcl interpreter.
   455    455   .PP
   456    456   \fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
   457         -it is responsible for waiting for an
   458         -.QW interesting
   459         -event to occur or
          457  +it is responsible for waiting for an ``interesting'' event to occur or
   460    458   for a given time to elapse.  Before \fBTcl_WaitForEvent\fR is invoked,
   461    459   each of the event sources' setup procedure will have been invoked.
   462    460   The \fItimePtr\fR argument to
   463    461   \fBTcl_WaitForEvent\fR gives the maximum time to block for an event,
   464    462   based on calls to \fBTcl_SetMaxBlockTime\fR made by setup procedures
   465    463   and on other information (such as the \fBTCL_DONT_WAIT\fR bit in
   466    464   \fIflags\fR).

Changes to doc/PrintDbl.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: PrintDbl.3,v 1.8 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: PrintDbl.3,v 1.9 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_PrintDouble \- Convert floating value to string
    15     15   .SH SYNOPSIS
................................................................................
    32     32   .BE
    33     33   
    34     34   .SH DESCRIPTION
    35     35   .PP
    36     36   \fBTcl_PrintDouble\fR generates a string that represents the value
    37     37   of \fIvalue\fR and stores it in memory at the location given by
    38     38   \fIdst\fR.  It uses \fB%g\fR format to generate the string, with one
    39         -special twist: the string is guaranteed to contain either a
    40         -.QW .
    41         -or an
    42         -.QW e
    43         -so that it doesn't look like an integer. Where \fB%g\fR would generate
    44         -an integer with no decimal point, \fBTcl_PrintDouble\fR adds
    45         -.QW .0 .
           39  +special twist: the string is guaranteed to contain either
           40  +a ``.'' or an ``e'' so that it doesn't look like an integer.  Where
           41  +\fB%g\fR would generate an integer with no decimal point, \fBTcl_PrintDouble\fR
           42  +adds ``.0''.
    46     43   .VS 8.5
    47     44   .PP
    48     45   If the \fBtcl_precision\fR value is non-zero, the result will have
    49     46   precisely that many digits of significance.  If the value is zero
    50     47   (the default), the result will have the fewest digits needed to
    51     48   represent the number in such a way that \fBTcl_NewDoubleObj\fR
    52     49   will generate the same number when presented with the given string.
    53     50   IEEE semantics of rounding to even apply to the conversion.
    54     51   .VE
    55     52   
    56     53   .SH KEYWORDS
    57     54   conversion, double-precision, floating-point, string

Changes to doc/RegExp.3.

     2      2   '\" Copyright (c) 1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 1998-1999 Scriptics Corporation
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: RegExp.3,v 1.24 2007/10/24 14:29:38 dkf Exp $
            9  +'\" RCS: @(#) $Id: RegExp.3,v 1.25 2007/10/26 20:11:52 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH Tcl_RegExpMatch 3 8.1 Tcl "Tcl Library Procedures"
    13     13   .BS
    14     14   .SH NAME
    15     15   Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange, Tcl_GetRegExpFromObj, Tcl_RegExpMatchObj, Tcl_RegExpExecObj, Tcl_RegExpGetInfo \- Pattern matching with regular expressions
    16     16   .SH SYNOPSIS
................................................................................
   182    182   long as the internal representation of \fIpatObj\fR refers to the
   183    183   compiled form.  The \fIeflags\fR argument is a bit-wise OR of
   184    184   zero or more of the following flags that control the compilation of
   185    185   \fIpatObj\fR:
   186    186   .RS 2
   187    187   .TP
   188    188   \fBTCL_REG_ADVANCED\fR
   189         -Compile advanced regular expressions
   190         -.PQ ARE s .
   191         -This mode corresponds to the normal regular expression syntax accepted by the
   192         -Tcl \fBregexp\fR and \fBregsub\fR commands.
          189  +Compile advanced regular expressions (`AREs').  This mode corresponds to
          190  +the normal regular expression syntax accepted by the Tcl \fBregexp\fR and
          191  +\fBregsub\fR commands.
   193    192   .TP
   194    193   \fBTCL_REG_EXTENDED\fR
   195         -Compile extended regular expressions
   196         -.PQ ERE s .
   197         -This mode corresponds to the regular expression syntax recognized by Tcl 8.0
   198         -and earlier versions. 
          194  +Compile extended regular expressions (`EREs').  This mode corresponds
          195  +to the regular expression syntax recognized by Tcl 8.0 and earlier
          196  +versions. 
   199    197   .TP
   200    198   \fBTCL_REG_BASIC\fR
   201         -Compile basic regular expressions
   202         -.PQ BRE s .
   203         -This mode corresponds to the regular expression syntax recognized by common
   204         -Unix utilities like \fBsed\fR and \fBgrep\fR.  This is the default if no flags
   205         -are specified.
          199  +Compile basic regular expressions (`BREs').  This mode corresponds
          200  +to the regular expression syntax recognized by common Unix utilities
          201  +like \fBsed\fR and \fBgrep\fR.  This is the default if no flags are
          202  +specified.
   206    203   .TP
   207    204   \fBTCL_REG_EXPANDED\fR
   208    205   Compile the regular expression (basic, extended, or advanced) using an
   209    206   expanded syntax that allows comments and whitespace.  This mode causes
   210    207   non-backslashed non-bracket-expression white
   211    208   space and #-to-end-of-line comments to be ignored.
   212    209   .TP
................................................................................
   215    212   .TP
   216    213   \fBTCL_REG_NOCASE\fR
   217    214   Compile for matching that ignores upper/lower case distinctions.
   218    215   .TP
   219    216   \fBTCL_REG_NEWLINE\fR
   220    217   Compile for newline-sensitive matching.  By default, newline is a
   221    218   completely ordinary character with no special meaning in either
   222         -regular expressions or strings.  With this flag,
   223         -.QW [^
   224         -bracket expressions and
   225         -.QW .
   226         -never match newline,
   227         -.QW ^
   228         -matches an empty string
   229         -after any newline in addition to its normal function, and
   230         -.QW $
   231         -matches an empty string before any newline in addition to its normal
   232         -function. \fBREG_NEWLINE\fR is the bit-wise OR of \fBREG_NLSTOP\fR and
          219  +regular expressions or strings.  With this flag, `[^' bracket
          220  +expressions and `.' never match newline, `^' matches an empty string
          221  +after any newline in addition to its normal function, and `$' matches
          222  +an empty string before any newline in addition to its normal function.
          223  +\fBREG_NEWLINE\fR is the bit-wise OR of \fBREG_NLSTOP\fR and
   233    224   \fBREG_NLANCH\fR.
   234    225   .TP
   235    226   \fBTCL_REG_NLSTOP\fR
   236         -Compile for partial newline-sensitive matching, with the behavior of
   237         -.QW [^
   238         -bracket expressions and
   239         -.QW .
   240         -affected, but not the behavior of
   241         -.QW ^
   242         -and
   243         -.QW $ .
   244         -In this mode,
   245         -.QW [^
   246         -bracket expressions and
   247         -.QW .
   248         -never match newline.
          227  +Compile for partial newline-sensitive matching,
          228  +with the behavior of
          229  +`[^' bracket expressions and `.' affected,
          230  +but not the behavior of `^' and `$'.  In this mode, `[^' bracket
          231  +expressions and `.' never match newline.
   249    232   .TP
   250    233   \fBTCL_REG_NLANCH\fR
   251         -Compile for inverse partial newline-sensitive matching, with the behavior of
   252         -.QW ^
   253         -and
   254         -.QW $
   255         -(the
   256         -.QW anchors )
   257         -affected, but not the behavior of
   258         -.QW [^
   259         -bracket expressions and
   260         -.QW . .
   261         -In this mode
   262         -.QW ^
   263         -matches an empty string after any newline in addition to its normal function,
   264         -and
   265         -.QW $
   266         -matches an empty string before any newline in addition to its normal function.
          234  +Compile for inverse partial newline-sensitive matching,
          235  +with the behavior
          236  +of `^' and `$' (the ``anchors'') affected, but not the behavior of
          237  +`[^' bracket expressions and `.'.  In this mode `^' matches an empty string
          238  +after any newline in addition to its normal function, and `$' matches
          239  +an empty string before any newline in addition to its normal function.
   267    240   .TP
   268    241   \fBTCL_REG_NOSUB\fR
   269    242   Compile for matching that reports only success or failure,
   270    243   not what was matched.  This reduces compile overhead and may improve
   271    244   performance.  Subsequent calls to \fBTcl_RegExpGetInfo\fR or
   272    245   \fBTcl_RegExpRange\fR will not report any match information.
   273    246   .TP
................................................................................
   298    271   offset value.  Instead the behavior of the anchors is explicitly
   299    272   controlled by the \fIeflags\fR argument, which is a bit-wise OR of
   300    273   zero or more of the following flags:
   301    274   .RS 2
   302    275   .TP
   303    276   \fBTCL_REG_NOTBOL\fR
   304    277   The starting character will not be treated as the beginning of a
   305         -line or the beginning of the string, so
   306         -.QW ^
   307         -will not match there. Note that this flag has no effect on how
   308         -.QW \fB\eA\fR
   309         -matches.
          278  +line or the beginning of the string, so `^' will not match there.
          279  +Note that this flag has no effect on how `\fB\eA\fR' matches.
   310    280   .TP
   311    281   \fBTCL_REG_NOTEOL\fR
   312    282   The last character in the string will not be treated as the end of a
   313         -line or the end of the string, so
   314         -.QW $
   315         -will not match there. Note that this flag has no effect on how
   316         -.QW \fB\eZ\fR
   317         -matches.
          283  +line or the end of the string, so '$' will not match there.
          284  +Note that this flag has no effect on how `\fB\eZ\fR' matches.
   318    285   .RE
   319    286   .PP
   320    287   \fBTcl_RegExpGetInfo\fR retrieves information about the last match
   321    288   performed with a given regular expression \fIregexp\fR.  The
   322    289   \fIinfoPtr\fR argument contains a pointer to a structure that is
   323    290   defined as follows:
   324    291   .PP

Changes to doc/SetResult.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: SetResult.3,v 1.15 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: SetResult.3,v 1.16 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_FreeResult \- manipulate Tcl result
    15     15   .SH SYNOPSIS
................................................................................
   159    159   \fIelement\fR will be extracted as a single element.
   160    160   Under normal conditions, \fBTcl_AppendElement\fR will add a space
   161    161   character to \fIinterp\fR's result just before adding the new
   162    162   list element, so that the list elements in the result are properly
   163    163   separated.
   164    164   However if the new list element is the first in a list or sub-list
   165    165   (i.e. \fIinterp\fR's current result is empty, or consists of the
   166         -single character
   167         -.QW { ,
   168         -or ends in the characters
   169         -.QW " {" )
   170         -then no space is added.
          166  +single character ``{'', or ends in the characters `` {'') then no
          167  +space is added.
   171    168   .PP
   172    169   \fBTcl_FreeResult\fR performs part of the work
   173    170   of \fBTcl_ResetResult\fR.
   174    171   It frees up the memory associated with \fIinterp\fR's result.
   175    172   It also sets \fIinterp->freeProc\fR to zero, but doesn't
   176    173   change \fIinterp->result\fR or clear error state.
   177    174   \fBTcl_FreeResult\fR is most commonly used when a procedure

Changes to doc/SetVar.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: SetVar.3,v 1.13 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: SetVar.3,v 1.14 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_SetVar 3 8.1 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_SetVar2Ex, Tcl_SetVar, Tcl_SetVar2, Tcl_ObjSetVar2, Tcl_GetVar2Ex, Tcl_GetVar, Tcl_GetVar2, Tcl_ObjGetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables
    15     15   .SH SYNOPSIS
................................................................................
   203    203   .TP
   204    204   \fBTCL_LIST_ELEMENT\fR
   205    205   If this bit is set, then \fInewValue\fR is converted to a valid
   206    206   Tcl list element before setting (or appending to) the variable.
   207    207   A separator space is appended before the new list element unless
   208    208   the list element is going to be the first element in a list or
   209    209   sublist (i.e. the variable's current value is empty, or contains
   210         -the single character
   211         -.QW { ,
   212         -or ends in
   213         -.QW " }" ).
          210  +the single character ``{'', or ends in `` }'').
   214    211   When appending, the original value of the variable must also be
   215    212   a valid list, so that the operation is the appending of a new
   216    213   list element onto a list.
   217    214   .PP
   218    215   \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR
   219    216   return the current value of a variable.
   220    217   The arguments to these procedures are treated in the same way

Changes to doc/SplitList.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: SplitList.3,v 1.10 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: SplitList.3,v 1.11 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_SplitList 3 8.0 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement, Tcl_ScanCountedElement, Tcl_ConvertCountedElement \- manipulate Tcl lists
    15     15   .SH SYNOPSIS
................................................................................
   165    165   used to generate a portion of an argument for a Tcl command.
   166    166   In this case, surrounding \fIsrc\fR with curly braces would cause
   167    167   the command not to be parsed correctly.
   168    168   .PP
   169    169   .VS 8.5
   170    170   By default, \fBTcl_ConvertElement\fR will use quoting in its output
   171    171   to be sure the first character of an element is not the hash
   172         -character (i.e.
   173         -.QW # ).
   174         -This is to be sure the first element of any list
          172  +character (``#'').  This is to be sure the first element of any list
   175    173   passed to \fBeval\fR is not mis-parsed as the beginning of a comment.
   176    174   When a list element is not the first element of a list, this quoting
   177    175   is not necessary.  When the caller can be sure that the element is
   178    176   not the first element of a list, it can disable quoting of the leading
   179    177   hash character by OR-ing the flag value returned by \fBTcl_ScanElement\fR
   180    178   with \fBTCL_DONT_QUOTE_HASH\fR.
   181    179   .VE 8.5

Changes to doc/StdChannels.3.

     1      1   '\"
     2      2   '\" Copyright (c) 2001 by ActiveState Corporation
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: StdChannels.3,v 1.11 2007/10/24 14:29:38 dkf Exp $
            7  +'\" RCS: @(#) $Id: StdChannels.3,v 1.12 2007/10/26 20:11:52 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH "Standard Channels" 3 7.5 Tcl "Tcl Library Procedures"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   Tcl_StandardChannels \- How the Tcl library deals with the standard channels
................................................................................
    38     38   .PP
    39     39   Standard channels are initialized by the Tcl library in three cases:
    40     40   when explicitly requested, when implicitly required before returning
    41     41   channel information, or when implicitly required during registration
    42     42   of a new channel.
    43     43   .PP
    44     44   These cases differ in how they handle unavailable platform- specific
    45         -standard channels.  (A channel is not
    46         -.QW available
    47         -if it could not be successfully opened; for example, in a Tcl
    48         -application run as a Windows NT service.)
           45  +standard channels.  (A channel is not ``available'' if it could not be
           46  +successfully opened; for example, in a Tcl application run as a
           47  +Windows NT service.)
    49     48   .TP
    50     49   1)
    51     50   A single standard channel is initialized when it is explicitly
    52     51   specified in a call to \fBTcl_SetStdChannel\fR.  The states of the
    53     52   other standard channels are unaffected.
    54     53   .RS
    55     54   .PP

Changes to doc/StrMatch.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: StrMatch.3,v 1.10 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: StrMatch.3,v 1.11 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_StringMatch 3 8.1 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_StringMatch, Tcl_StringCaseMatch \- test whether a string matches a pattern
    15     15   .SH SYNOPSIS
................................................................................
    34     34   .BE
    35     35   
    36     36   .SH DESCRIPTION
    37     37   .PP
    38     38   This utility procedure determines whether a string matches
    39     39   a given pattern.  If it does, then \fBTcl_StringMatch\fR returns
    40     40   1.  Otherwise \fBTcl_StringMatch\fR returns 0.  The algorithm
    41         -used for matching is the same algorithm used in the
    42         -.QW "string match"
           41  +used for matching is the same algorithm used in the ``string match''
    43     42   Tcl command and is similar to the algorithm used by the C-shell
    44     43   for file name matching;  see the Tcl manual entry for details.
    45     44   .PP
    46     45   In \fBTcl_StringCaseMatch\fR, the algorithm is the same, but you have
    47     46   the option to make the matching case-insensitive.  If you choose this
    48     47   (by passing \fBnocase\fR as 1), then the string and pattern are
    49     48   essentially matched in the lower case.
    50     49   
    51     50   .SH KEYWORDS
    52     51   match, pattern, string

Changes to doc/SubstObj.3.

     1      1   '\"
     2      2   '\" Copyright (c) 2001 Donal K. Fellows
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: SubstObj.3,v 1.4 2007/10/24 14:29:38 dkf Exp $
            7  +'\" RCS: @(#) $Id: SubstObj.3,v 1.5 2007/10/26 20:11:52 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH Tcl_SubstObj 3 8.4 Tcl "Tcl Library Procedures"
    11     11   .BS
    12     12   .SH NAME
    13     13   Tcl_SubstObj \- perform substitutions on Tcl objects
    14     14   .SH SYNOPSIS
................................................................................
    51     51   .PP
    52     52   When the \fBTCL_SUBST_VARIABLES\fR bit is set in \fIflags\fR,
    53     53   sequences that look like variable substitutions for Tcl commands are
    54     54   replaced by the contents of the named variable.
    55     55   .PP
    56     56   When the \fBTCL_SUBST_COMMANDS\fR bit is set in \fIflags\fR, sequences
    57     57   that look like command substitutions for Tcl commands are replaced by
    58         -the result of evaluating that script.  Where an uncaught
    59         -.QW "continue exception"
    60         -occurs during the evaluation of a command substitution, an
    61         -empty string is substituted for the command.  Where an uncaught
    62         -.QW "break exception"
    63         -occurs during the evaluation of a command substitution, the
           58  +the result of evaluating that script.  Where an uncaught `continue
           59  +exception' occurs during the evaluation of a command substitution, an
           60  +empty string is substituted for the command.  Where an uncaught `break
           61  +exception' occurs during the evaluation of a command substitution, the
    64     62   result of the whole substitution on \fIobjPtr\fR will be truncated at
    65     63   the point immediately before the start of the command substitution,
    66     64   and no characters will be added to the result or substitutions
    67     65   performed after that point.
    68     66   
    69     67   .SH "SEE ALSO"
    70     68   subst(n)
    71     69   
    72     70   .SH KEYWORDS
    73     71   backslash substitution, command substitution, variable substitution

Changes to doc/TCL_MEM_DEBUG.3.

     1      1   '\" 
     2      2   '\" Copyright (c) 1992-1999 Karl Lehenbauer and Mark Diekhans.
     3      3   '\" Copyright (c) 2000 by Scriptics Corporation.
     4      4   '\" All rights reserved.
     5      5   '\" 
     6         -'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.8 2007/10/24 14:29:38 dkf Exp $
            6  +'\" RCS: @(#) $Id: TCL_MEM_DEBUG.3,v 1.9 2007/10/26 20:11:52 dgp Exp $
     7      7   '\" 
     8      8   .so man.macros
     9      9   .TH TCL_MEM_DEBUG 3 8.1 Tcl "Tcl Library Procedures"
    10     10   .BS
    11     11   .SH NAME
    12     12   TCL_MEM_DEBUG \- Compile-time flag to enable Tcl memory debugging
    13     13   .BE
................................................................................
    37     37   and the Tcl \fBmemory\fR command can be used to validate and examine
    38     38   memory usage.
    39     39   
    40     40   .SH "GUARD ZONES"
    41     41   .PP
    42     42   When memory debugging is enabled, whenever a call to \fBckalloc\fR is
    43     43   made, slightly more memory than requested is allocated so the memory debugging
    44         -code can keep track of the allocated memory, and eight-byte
    45         -.QW "guard zones"
    46         -are placed in front of and behind the space that will be
           44  +code can keep track of the allocated memory, and eight-byte ``guard
           45  +zones'' are placed in front of and behind the space that will be
    47     46   returned to the caller.  (The sizes of the guard zones are defined by the
    48     47   C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR
    49     48   in the file \fIgeneric/tclCkalloc.c\fR -- it can
    50     49   be extended if you suspect large overwrite problems, at some cost in
    51     50   performance.)  A known pattern is written into the guard zones and, on
    52     51   a call to \fBckfree\fR, the guard zones of the space being freed are
    53     52   checked to see if either zone has been modified in any way.  If one
    54     53   has been, the guard bytes and their new contents are identified, and a
    55         -.QW "low guard failed"
    56         -or
    57         -.QW "high guard failed"
    58         -message is issued.  The
    59         -.QW "guard failed"
    60         -message includes the address of the memory packet and
           54  +``low guard failed'' or ``high guard failed'' message is issued.  The
           55  +``guard failed'' message includes the address of the memory packet and
    61     56   the file name and line number of the code that called \fBckfree\fR.
    62     57   This allows you to detect the common sorts of one-off problems, where
    63     58   not enough space was allocated to contain the data written, for
    64     59   example.
    65     60   
    66     61   .SH "DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS"
    67     62   .PP

Changes to doc/Tcl.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: Tcl.n,v 1.15 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: Tcl.n,v 1.16 2007/10/26 20:11:52 dgp Exp $
     9      9   '\"
    10     10   .so man.macros
    11     11   .TH Tcl n "8.5" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl \- Tool Command Language
    15     15   .SH SYNOPSIS
................................................................................
    37     37   in any way it likes, such as an integer, variable name, list,
    38     38   or Tcl script.
    39     39   Different commands interpret their words differently.
    40     40   .IP "[3] \fBWords.\fR"
    41     41   Words of a command are separated by white space (except for
    42     42   newlines, which are command separators).
    43     43   .IP "[4] \fBDouble quotes.\fR"
    44         -If the first character of a word is double-quote
    45         -.PQ \N'34'
    46         -then the word is terminated by the next double-quote character.
           44  +If the first character of a word is double-quote (``"'') then
           45  +the word is terminated by the next double-quote character.
    47     46   If semi-colons, close brackets, or white space characters
    48     47   (including newlines) appear between the quotes then they are treated
    49     48   as ordinary characters and included in the word.
    50     49   Command substitution, variable substitution, and backslash substitution
    51     50   are performed on the characters between the quotes as described below.
    52     51   The double-quotes are not retained as part of the word.
    53     52   .VS 8.5 br
    54     53   .IP "[5] \fBArgument expansion.\fR"
    55         -If a word starts with the string
    56         -.QW {*}
    57         -followed by a non-whitespace character, then the leading
    58         -.QW {*}
    59         -is removed and the rest of the word is parsed and substituted as any
    60         -other word. After substitution, the word is parsed again without
           54  +If a word starts with the string ``{*}'' followed by a 
           55  +non-whitespace character, then the leading ``{*}'' is removed
           56  +and the rest of the word is parsed and substituted as any other  
           57  +word. After substitution, the word is parsed again without
    61     58   substitutions, and its words are added to the command being
    62         -substituted. For instance,
    63         -.QW "cmd a {*}{b c} d {*}{e f}"
    64         -is equivalent to
    65         -.QW "cmd a b c d e f" . 
           59  +substituted. For instance, ``cmd a {*}{b c} d {*}{e f}'' is
           60  +equivalent to ``cmd a b c d e f''. 
    66     61   .VE 8.5
    67     62   .IP "[6] \fBBraces.\fR"
    68         -If the first character of a word is an open brace
    69         -.PQ {
    70         -and rule [5] does not apply, then
    71         -the word is terminated by the matching close brace
    72         -.PQ } "" .
           63  +If the first character of a word is an open brace (``{'') and
           64  +rule [5] does not apply, then
           65  +the word is terminated by the matching close brace (``}'').
    73     66   Braces nest within the word: for each additional open
    74     67   brace there must be an additional close brace (however,
    75     68   if an open brace or close brace within the word is
    76     69   quoted with a backslash then it is not counted in locating the
    77     70   matching close brace).
    78     71   No substitutions are performed on the characters between the
    79     72   braces except for backslash-newline substitutions described
    80     73   below, nor do semi-colons, newlines, close brackets,
    81     74   or white space receive any special interpretation.
    82     75   The word will consist of exactly the characters between the
    83     76   outer braces, not including the braces themselves.
    84     77   .IP "[7] \fBCommand substitution.\fR"
    85         -If a word contains an open bracket
    86         -.PQ [
    87         -then Tcl performs \fIcommand substitution\fR.
           78  +If a word contains an open bracket (``['') then Tcl performs
           79  +\fIcommand substitution\fR.
    88     80   To do this it invokes the Tcl interpreter recursively to process
    89     81   the characters following the open bracket as a Tcl script.
    90     82   The script may contain any number of commands and must be terminated
    91         -by a close bracket
    92         -.PQ ] "" .
           83  +by a close bracket (``]'').
    93     84   The result of the script (i.e. the result of its last command) is
    94     85   substituted into the word in place of the brackets and all of the
    95     86   characters between them.
    96     87   There may be any number of command substitutions in a single word.
    97     88   Command substitution is not performed on words enclosed in braces.
    98     89   .IP "[8] \fBVariable substitution.\fR"
    99         -If a word contains a dollar-sign
   100         -.PQ $
   101         -followed by one of the forms described below, then Tcl performs \fIvariable
           90  +If a word contains a dollar-sign (``$'') followed by one of the forms
           91  +described below, then Tcl performs \fIvariable
   102     92   substitution\fR:  the dollar-sign and the following characters are
   103     93   replaced in the word by the value of a variable.
   104     94   Variable substitution may take any of the following forms:
   105     95   .RS
   106     96   .TP 15
   107     97   \fB$\fIname\fR
   108     98   \fIName\fR is the name of a scalar variable;  the name is a sequence
................................................................................
   121    111   \fIName\fR is the name of a scalar variable.  It may contain any
   122    112   characters whatsoever except for close braces.
   123    113   .LP
   124    114   There may be any number of variable substitutions in a single word.
   125    115   Variable substitution is not performed on words enclosed in braces.
   126    116   .RE
   127    117   .IP "[9] \fBBackslash substitution.\fR"
   128         -If a backslash
   129         -.PQ \e
   130         -appears within a word then \fIbackslash substitution\fR occurs.
          118  +If a backslash (``\e'') appears within a word then
          119  +\fIbackslash substitution\fR occurs.
   131    120   In all cases but those described below the backslash is dropped and
   132    121   the following character is treated as an ordinary
   133    122   character and included in the word.
   134    123   This allows characters such as double quotes, close brackets,
   135    124   and dollar signs to be included in words without triggering
   136    125   special processing.
   137    126   The following table lists the backslash sequences that are
................................................................................
   165    154   and tabs after the newline.  This backslash sequence is unique in that it
   166    155   is replaced in a separate pre-pass before the command is actually parsed.
   167    156   This means that it will be replaced even when it occurs between braces,
   168    157   and the resulting space will be treated as a word separator if it isn't
   169    158   in braces or quotes.
   170    159   .TP 7
   171    160   \e\e
   172         -Backslash
   173         -.PQ \e "" .
          161  +Backslash (``\e'').
   174    162   .TP 7
   175    163   \e\fIooo\fR 
   176    164   .
   177    165   The digits \fIooo\fR (one, two, or three of them) give an eight-bit octal 
   178    166   value for the Unicode character that will be inserted.  The upper bits of the
   179    167   Unicode character will be 0.
   180    168   .TP 7
................................................................................
   192    180   sixteen-bit hexadecimal value for the Unicode character that will be
   193    181   inserted.
   194    182   .LP
   195    183   Backslash substitution is not performed on words enclosed in braces,
   196    184   except for backslash-newline as described above.
   197    185   .RE
   198    186   .IP "[10] \fBComments.\fR"
   199         -If a hash character
   200         -.PQ #
   201         -appears at a point where Tcl is
          187  +If a hash character (``#'') appears at a point where Tcl is
   202    188   expecting the first character of the first word of a command,
   203    189   then the hash character and the characters that follow it, up
   204    190   through the next newline, are treated as a comment and ignored.
   205    191   The comment character only has significance when it appears
   206    192   at the beginning of a command.
   207    193   .IP "[11] \fBOrder of substitution.\fR"
   208    194   Each character is processed exactly once by the Tcl interpreter

Changes to doc/Tcl_Main.3.

     2      2   '\" Copyright (c) 1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2000 Ajuba Solutions.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: Tcl_Main.3,v 1.12 2007/10/24 14:29:38 dkf Exp $
            9  +'\" RCS: @(#) $Id: Tcl_Main.3,v 1.13 2007/10/26 20:11:52 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures"
    13     13   .BS
    14     14   .SH NAME
    15     15   Tcl_Main, Tcl_SetMainLoop \- main program and event loop definition for Tcl-based applications
    16     16   .SH SYNOPSIS
................................................................................
    32     32   .AP Tcl_MainLoopProc *mainLoopProc in
    33     33   Address of an application-specific event loop procedure.
    34     34   .BE
    35     35   
    36     36   .SH DESCRIPTION
    37     37   .PP
    38     38   \fBTcl_Main\fR can serve as the main program for Tcl-based shell
    39         -applications.  A
    40         -.QW "shell application"
    41         -is a program like tclsh or wish that supports both interactive interpretation
           39  +applications.  A ``shell application'' is a program
           40  +like tclsh or wish that supports both interactive interpretation
    42     41   of Tcl and evaluation of a script contained in a file given as
    43     42   a command line argument.  \fBTcl_Main\fR is offered as a convenience
    44     43   to developers of shell applications, so they do not have to 
    45     44   reproduce all of the code for proper initialization of the Tcl
    46     45   library and interactive shell operation.  Other styles of embedding
    47     46   Tcl in an application are not supported by \fBTcl_Main\fR.  Those
    48     47   must be achieved by calling lower level functions in the Tcl library
................................................................................
    88     87   .PP
    89     88   In either mode, \fBTcl_Main\fR will define in its master interpreter
    90     89   the Tcl variables \fIargc\fR, \fIargv\fR, \fIargv0\fR, and
    91     90   \fItcl_interactive\fR, as described in the documentation for \fBtclsh\fR.
    92     91   .PP
    93     92   When it has finished its own initialization, but before it processes
    94     93   commands, \fBTcl_Main\fR calls the procedure given by the
    95         -\fIappInitProc\fR argument.  This procedure provides a
    96         -.QW hook
    97         -for the application to perform its own initialization of the interpreter
           94  +\fIappInitProc\fR argument.  This procedure provides a ``hook'' for
           95  +the application to perform its own initialization of the interpreter
    98     96   created by \fBTcl_Main\fR, such as defining application-specific
    99     97   commands.  The procedure must have an interface that matches the
   100     98   type \fBTcl_AppInitProc\fR:
   101     99   .CS
   102    100   typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR);
   103    101   .CE
   104    102   

Changes to doc/TraceVar.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: TraceVar.3,v 1.16 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: TraceVar.3,v 1.17 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 \- monitor accesses to a variable
    15     15   .SH SYNOPSIS
................................................................................
   349    349   
   350    350   .SH "UNDEFINED VARIABLES"
   351    351   .PP
   352    352   It is legal to set a trace on an undefined variable.
   353    353   The variable will still appear to be undefined until the
   354    354   first time its value is set.
   355    355   If an undefined variable is traced and then unset, the unset will fail
   356         -with an error,
   357         -.QW "no such variable" ,
   358         -but the trace procedure will still be invoked.
          356  +with an error (``no such variable''), but the trace
          357  +procedure will still be invoked.
   359    358   
   360    359   .SH "TCL_TRACE_DESTROYED FLAG"
   361    360   .PP
   362    361   In an unset callback to \fIproc\fR, the \fBTCL_TRACE_DESTROYED\fR bit
   363    362   is set in \fIflags\fR if the trace is being removed as part
   364    363   of the deletion.
   365    364   Traces on a variable are always removed whenever the variable

Changes to doc/Translate.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1989-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: Translate.3,v 1.10 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: Translate.3,v 1.11 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures"
    12     12   .BS
    13     13   .SH NAME
    14     14   Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory
    15     15   .SH SYNOPSIS
................................................................................
    19     19   char *
    20     20   \fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR)
    21     21   .SH ARGUMENTS
    22     22   .AS Tcl_DString *bufferPtr in/out
    23     23   .AP Tcl_Interp *interp in
    24     24   Interpreter in which to report an error, if any.
    25     25   .AP "const char" *name in
    26         -File name, which may start with a
    27         -.QW ~ .
           26  +File name, which may start with a ``~''.
    28     27   .AP Tcl_DString *bufferPtr in/out
    29     28   If needed, this dynamic string is used to store the new file name.
    30     29   At the time of the call it should be uninitialized or free.  The
    31     30   caller must eventually call \fBTcl_DStringFree\fR to free up
    32     31   anything stored here.
    33     32   .BE
    34     33   

Changes to doc/WrongNumArgs.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.9 2007/10/24 14:29:38 dkf Exp $
            7  +'\" RCS: @(#) $Id: WrongNumArgs.3,v 1.10 2007/10/26 20:11:52 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures"
    11     11   .BS
    12     12   .SH NAME
    13     13   Tcl_WrongNumArgs \- generate standard error message for wrong number of arguments
    14     14   .SH SYNOPSIS
................................................................................
    37     37   \fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by
    38     38   command procedures when they discover that they have received the
    39     39   wrong number of arguments.  \fBTcl_WrongNumArgs\fR generates a
    40     40   standard error message and stores it in the result object of
    41     41   \fIinterp\fR.  The message includes the \fIobjc\fR initial
    42     42   elements of \fIobjv\fR plus \fImessage\fR.  For example, if
    43     43   \fIobjv\fR consists of the values \fBfoo\fR and \fBbar\fR,
    44         -\fIobjc\fR is 1, and \fImessage\fR is
    45         -.QW "\fBfileName count\fR"
           44  +\fIobjc\fR is 1, and \fImessage\fR is ``\fBfileName count\fR''
    46     45   then \fIinterp\fR's result object will be set to the following
    47     46   string:
    48     47   .CS
    49     48   wrong # args: should be "foo fileName count"
    50     49   .CE
    51     50   If \fIobjc\fR is 2, the result will be set to the following string:
    52     51   .CS

Changes to doc/after.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1990-1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: after.n,v 1.8 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: after.n,v 1.9 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH after n 7.5 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   after \- Execute a command after a time delay
................................................................................
   132    132   proc doOneStep {} {
   133    133      if {[::my_calc::one_step]} {
   134    134         \fBafter idle\fR [list \fBafter\fR 0 doOneStep]
   135    135      }
   136    136   }
   137    137   doOneStep
   138    138   .CE
          139  +
   139    140   .SH "SEE ALSO"
   140    141   concat(n), interp(n), update(n), vwait(n)
          142  +
   141    143   .SH KEYWORDS
   142    144   cancel, delay, idle callback, sleep, time

Changes to doc/append.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: append.n,v 1.7 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: append.n,v 1.8 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH append n "" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   append \- Append to variable
................................................................................
    23     23   of variable \fIvarName\fR.  If \fIvarName\fR doesn't exist,
    24     24   it is given a value equal to the concatenation of all the
    25     25   \fIvalue\fR arguments.
    26     26   The result of this command is the new value stored in variable
    27     27   \fIvarName\fR.
    28     28   This command provides an efficient way to build up long
    29     29   variables incrementally.
    30         -For example,
    31         -.QW "\fBappend a $b\fR"
    32         -is much more efficient than
    33         -.QW "\fBset a $a$b\fR" ,
    34         -especially when \fB$a\fR is long.
           30  +For example, ``\fBappend a $b\fR'' is much more efficient than
           31  +``\fBset a $a$b\fR'' if \fB$a\fR is long.
    35     32   .SH EXAMPLE
    36     33   Building a string of comma-separated numbers piecemeal using a loop.
    37     34   .CS
    38     35   set var 0
    39     36   for {set i 1} {$i<=10} {incr i} {
    40     37      \fBappend\fR var "," $i
    41     38   }
    42     39   puts $var
    43     40   # Prints 0,1,2,3,4,5,6,7,8,9,10
    44     41   .CE
           42  +
    45     43   .SH "SEE ALSO"
    46     44   concat(n), lappend(n)
           45  +
    47     46   .SH KEYWORDS
    48     47   append, variable

Changes to doc/apply.n.

    37     37   the \fBvariable\fR command or the \fBupvar\fR command.
    38     38   .PP
    39     39   The invocation of \fBapply\fR adds a call frame to Tcl's evaluation stack
    40     40   (the stack of frames accessed via \fBuplevel\fR). The execution of \fIbody\fR
    41     41   proceeds in this call frame, in the namespace given by \fInamespace\fR or
    42     42   in the global namespace if none was specified. If given, \fInamespace\fR is
    43     43   interpreted relative to the global namespace even if its name does not start
    44         -with
    45         -.QW :: . 
           44  +with '::'. 
    46     45   .PP
    47     46   The semantics of \fBapply\fR can also be described by:
    48     47   .PP
    49     48   .CS
    50     49   proc apply {fun args} {
    51     50      set len [llength $fun]
    52     51      if {($len < 2) || ($len > 3)} {
................................................................................
    62     61      return -options $opt $res
    63     62   }
    64     63   .CE
    65     64   .SH EXAMPLES
    66     65   This shows how to make a simple general command that applies a transformation
    67     66   to each element of a list.
    68     67   .CS
    69         -.ta 2i
    70     68   proc map {lambda list} {
    71     69      set result {}
    72     70      foreach $item $list {
    73     71         lappend result [\fBapply\fR $lambda $item]
    74     72      }
    75     73      return $result
    76     74   }
    77     75   map {x {return [string length $x]:$x}} {a bb ccc dddd}
    78         -	 \fB\(->\fI 1:a 2:bb 3:ccc 4:dddd\fR
           76  +      \fI=> 1:a 2:bb 3:ccc 4:dddd\fR
    79     77   map {x {expr {$x**2 + 3*$x - 2}}} {-4 -3 -2 -1 0 1 2 3 4}
    80         -	 \fB\(->\fI 2 -2 -4 -4 -2 2 8 16 26\fR
           78  +      \fI=> 2 -2 -4 -4 -2 2 8 16 26\fR
    81     79   .CE
    82     80   .PP
    83     81   The \fBapply\fR command is also useful for defining callbacks for use in the
    84     82   \fBtrace\fR command:
    85     83   .CS
    86         -.ta 2i
    87     84   set vbl "123abc"
    88     85   trace add variable vbl write {\fBapply\fR {v1 v2 op} {
    89     86      upvar 1 $v1 v
    90         -   puts "updated variable to \e"$v\e""
           87  +   puts "updated variable to \\"$v\\""
    91     88   }}
    92     89   set vbl 123
    93         -	 \fB\(->\fI updated variable to "123"\fR
    94     90   set vbl abc
    95         -	 \fB\(->\fI updated variable to "abc"\fR
    96     91   .CE
    97     92   .SH "SEE ALSO"
    98     93   proc(n), uplevel(n)
    99     94   .SH KEYWORDS
   100     95   argument, procedure, anonymous function

Changes to doc/array.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993-1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: array.n,v 1.17 2007/10/25 09:25:27 dkf Exp $
            8  +'\" RCS: @(#) $Id: array.n,v 1.18 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH array n 8.3 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   array \- Manipulate array variables
................................................................................
   144    144      blue  4
   145    145      white 9
   146    146   }
   147    147   
   148    148   foreach {color count} [\fBarray get\fR colorcount] {
   149    149      puts "Color: $color Count: $count"
   150    150   }
   151         -  \(-> Color: blue Count: 4
          151  + => Color: blue Count: 4
   152    152       Color: white Count: 9
   153    153       Color: green Count: 5
   154    154       Color: red Count: 1
   155    155   
   156    156   foreach color [\fBarray names\fR colorcount] {
   157    157      puts "Color: $color Count: $colorcount($color)"
   158    158   }
   159         -  \(-> Color: blue Count: 4
          159  + => Color: blue Count: 4
   160    160       Color: white Count: 9
   161    161       Color: green Count: 5
   162    162       Color: red Count: 1
   163    163   
   164    164   foreach color [lsort [\fBarray names\fR colorcount]] {
   165    165      puts "Color: $color Count: $colorcount($color)"
   166    166   }
   167         -  \(-> Color: blue Count: 4
          167  + => Color: blue Count: 4
   168    168       Color: green Count: 5
   169    169       Color: red Count: 1
   170    170       Color: white Count: 9
   171    171   
   172    172   \fBarray statistics\fR colorcount
   173         -  \(-> 4 entries in table, 4 buckets
          173  + => 4 entries in table, 4 buckets
   174    174       number of buckets with 0 entries: 1
   175    175       number of buckets with 1 entries: 2
   176    176       number of buckets with 2 entries: 1
   177    177       number of buckets with 3 entries: 0
   178    178       number of buckets with 4 entries: 0
   179    179       number of buckets with 5 entries: 0
   180    180       number of buckets with 6 entries: 0
   181    181       number of buckets with 7 entries: 0
   182    182       number of buckets with 8 entries: 0
   183    183       number of buckets with 9 entries: 0
   184    184       number of buckets with 10 or more entries: 0
   185    185       average search distance for entry: 1.2
   186    186   .CE
          187  +
   187    188   .SH "SEE ALSO"
   188    189   list(n), string(n), variable(n), trace(n), foreach(n)
          190  +
   189    191   .SH KEYWORDS
   190    192   array, element names, search

Changes to doc/bgerror.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1990-1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: bgerror.n,v 1.10 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: bgerror.n,v 1.11 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH bgerror n 7.5 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   bgerror \- Command invoked to process background errors
................................................................................
    82     82   proc bgerror {message} {
    83     83       set timestamp [clock format [clock seconds]]
    84     84       set fl [open mylog.txt {WRONLY CREAT APPEND}]
    85     85       puts $fl "$timestamp: bgerror in $::argv '$message'"
    86     86       close $fl
    87     87   }
    88     88   .CE
           89  +
    89     90   .SH "SEE ALSO"
    90     91   after(n), interp(n), tclvars(n)
           92  +
    91     93   .SH KEYWORDS
    92     94   background error, reporting

Changes to doc/binary.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1997 by Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: binary.n,v 1.31 2007/10/25 14:07:32 dkf Exp $
            7  +'\" RCS: @(#) $Id: binary.n,v 1.32 2007/10/26 20:11:52 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH binary n 8.0 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   binary \- Insert and extract fields from binary strings
................................................................................
   125    125   \fBbinary format\fR B5B* 11100 111000011010
   126    126   .CE
   127    127   will return a string equivalent to \fB\\xe0\\xe1\\xa0\fR.
   128    128   .RE
   129    129   .IP \fBh\fR 5
   130    130   Stores a string of \fIcount\fR hexadecimal digits in low-to-high
   131    131   within each byte in the output string.  \fIArg\fR must contain a
   132         -sequence of characters in the set
   133         -.QW 0123456789abcdefABCDEF .
   134         -The resulting bytes are emitted in first to last order with the hex digits
          132  +sequence of characters in the set ``0123456789abcdefABCDEF''.  The
          133  +resulting bytes are emitted in first to last order with the hex digits
   135    134   being formatted in low-to-high order within each byte.  If \fIarg\fR
   136    135   has fewer than \fIcount\fR digits, then zeros will be used for the
   137    136   remaining digits.  If \fIarg\fR has more than the specified number of
   138    137   digits, the extra digits will be ignored.  If \fIcount\fR is
   139    138   \fB*\fR, then all of the digits in \fIarg\fR will be formatted.  If
   140    139   \fIcount\fR is omitted, then one digit will be formatted.  If the
   141    140   number of digits formatted does not end at a byte boundary, the
................................................................................
   392    391   \fIcount\fR is a non-negative decimal integer or \fB*\fR, which
   393    392   normally indicates that all of the remaining items in the data are to
   394    393   be used.  If there are not enough bytes left after the current cursor
   395    394   position to satisfy the current field specifier, then the
   396    395   corresponding variable is left untouched and \fBbinary scan\fR returns
   397    396   immediately with the number of variables that were set.  If there are
   398    397   not enough arguments for all of the fields in the format string that
   399         -consume arguments, then an error is generated. The flag character
   400         -.QW u
          398  +consume arguments, then an error is generated. The flag character 'u'
   401    399   may be given to cause some types to be read as unsigned values. The flag
   402    400   is accepted for all field types but is ignored for non-integer fields.
   403    401   .PP
   404    402   A similar example as with \fBbinary format\fR should explain the
   405    403   relation between field specifiers and arguments in case of the binary
   406    404   scan subcommand:
   407    405   .CS
................................................................................
   432    430   long data size values.  In doing this, values that have their high
   433    431   bit set (0x80 for chars, 0x8000 for shorts, 0x80000000 for ints),
   434    432   will be sign extended.  Thus the following will occur:
   435    433   .CS
   436    434   set signShort [\fBbinary format\fR s1 0x8000]
   437    435   \fBbinary scan\fR $signShort s1 val; \fI# val == 0xFFFF8000\fR
   438    436   .CE
   439         -If you require unsigned values you can include the
   440         -.QW u
   441         -flag character following the field type. For example, to read an
   442         -unsigned short value:
          437  +If you require unsigned values you can include the 'u' flag character following
          438  +the field type. For example, to read an unsigned short value:
   443    439   .CS
   444    440   set signShort [\fBbinary format\fR s1 0x8000]
   445    441   \fBbinary scan\fR $signShort su1 val; \fI# val == 0x00008000\fR
   446    442   .CE
   447    443   .PP
   448    444   Each type-count pair moves an imaginary cursor through the binary data,
   449    445   reading bytes from the current position.  The cursor is initially
................................................................................
   472    468   .CS
   473    469   \fBbinary scan\fR "abc efghi  \\000" A* var1
   474    470   .CE
   475    471   will return \fB1\fR with \fBabc efghi\fR stored in \fIvar1\fR.
   476    472   .RE
   477    473   .IP \fBb\fR 5
   478    474   The data is turned into a string of \fIcount\fR binary digits in
   479         -low-to-high order represented as a sequence of
   480         -.QW 1
   481         -and
   482         -.QW 0
          475  +low-to-high order represented as a sequence of ``1'' and ``0''
   483    476   characters.  The data bytes are scanned in first to last order with
   484    477   the bits being taken in low-to-high order within each byte.  Any extra
   485    478   bits in the last byte are ignored.  If \fIcount\fR is \fB*\fR, then
   486    479   all of the remaining bits in \fIstring\fR will be scanned.  If
   487    480   \fIcount\fR is omitted, then one bit will be scanned.  For example,
   488    481   .RS
   489    482   .CS
................................................................................
   501    494   .CE
   502    495   will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and
   503    496   \fB1000011100000101\fR stored in \fIvar2\fR.
   504    497   .RE
   505    498   .IP \fBH\fR 5
   506    499   The data is turned into a string of \fIcount\fR hexadecimal digits in
   507    500   high-to-low order represented as a sequence of characters in the set
   508         -.QW 0123456789abcdef .
   509         -The data bytes are scanned in first to last
          501  +``0123456789abcdef''. The data bytes are scanned in first to last
   510    502   order with the hex digits being taken in high-to-low order within each
   511    503   byte. Any extra bits in the last byte are ignored. If \fIcount\fR is
   512    504   \fB*\fR, then all of the remaining hex digits in \fIstring\fR will be
   513    505   scanned. If \fIcount\fR is omitted, then one hex digit will be
   514    506   scanned. For example,
   515    507   .RS
   516    508   .CS
................................................................................
   787    779       if {![\fBbinary scan\fR [read $channel 4] I length]} {
   788    780           error "missing length"
   789    781       }
   790    782       set data [read $channel $length]
   791    783       return [encoding convertfrom utf-8 $data]
   792    784   }
   793    785   .CE
          786  +
   794    787   .SH "SEE ALSO"
   795    788   format(n), scan(n), tclvars(n)
          789  +
   796    790   .SH KEYWORDS
   797    791   binary, format, scan

Changes to doc/break.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993-1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: break.n,v 1.8 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: break.n,v 1.9 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH break n "" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   break \- Abort looping command
................................................................................
    35     35   for {set x 0} {$x<10} {incr x} {
    36     36      if {$x > 5} {
    37     37         \fBbreak\fR
    38     38      }
    39     39      puts "x is $x"
    40     40   }
    41     41   .CE
           42  +
    42     43   .SH "SEE ALSO"
    43     44   catch(n), continue(n), for(n), foreach(n), return(n), while(n)
           45  +
    44     46   .SH KEYWORDS
    45     47   abort, break, loop

Changes to doc/catch.n.

     2      2   '\" Copyright (c) 1993-1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Contributions from Don Porter, NIST, 2003.  (not subject to US copyright)
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: catch.n,v 1.14 2007/10/24 14:29:38 dkf Exp $
            9  +'\" RCS: @(#) $Id: catch.n,v 1.15 2007/10/26 20:11:52 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH catch n "8.5" Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   catch \- Evaluate script and trap exceptional returns
................................................................................
    86     86       puts stderr "Could not open $someFile for writing\\n$fid"
    87     87       exit 1
    88     88   }
    89     89   .CE
    90     90   .PP
    91     91   There are more complex examples of \fBcatch\fR usage in the
    92     92   documentation for the \fBreturn\fR command.
           93  +
    93     94   .SH "SEE ALSO" 
    94     95   break(n), continue(n), dict(n), error(n), return(n), tclvars(n)
           96  +
    95     97   .SH KEYWORDS
    96     98   catch, error

Changes to doc/cd.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: cd.n,v 1.7 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: cd.n,v 1.8 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH cd n "" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   cd \- Change working directory
................................................................................
    33     33   .CE
    34     34   .PP
    35     35   Change to the directory \fBlib\fR that is a sibling directory of the
    36     36   current one:
    37     37   .CS
    38     38   \fBcd\fR ../lib
    39     39   .CE
           40  +
    40     41   .SH "SEE ALSO"
    41     42   filename(n), glob(n), pwd(n)
           43  +
    42     44   .SH KEYWORDS
    43     45   working directory

Changes to doc/chan.n.

     1      1   '\" 
     2      2   '\" Copyright (c) 2005-2006 Donal K. Fellows
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\"
     7         -'\" RCS: @(#) $Id: chan.n,v 1.12 2007/10/25 14:07:32 dkf Exp $
            7  +'\" RCS: @(#) $Id: chan.n,v 1.13 2007/10/26 20:11:52 dgp Exp $
     8      8   .so man.macros
     9      9   .TH chan n 8.5 Tcl "Tcl Built-In Commands"
    10     10   .BS
    11     11   '\" Note:  do not modify the .SH NAME line immediately below!
    12     12   .SH NAME
    13     13   chan \- Read, write and manipulate channels
    14     14   .SH SYNOPSIS
................................................................................
   289    289   \fInot\fR made.  If \fIinputChan\fR is closed, then all data already
   290    290   queued for \fIoutputChan\fR is written out.
   291    291   .PP
   292    292   Note that \fIinputChan\fR can become readable during a background
   293    293   copy.  You should turn off any \fBchan event\fR or \fBfileevent\fR
   294    294   handlers during a background copy so those handlers do not interfere
   295    295   with the copy.  Any I/O attempted by a \fBchan event\fR or
   296         -\fBfileevent\fR handler will get a
   297         -.QW "channel busy"
   298         -error.
          296  +\fBfileevent\fR handler will get a "channel busy" error.
   299    297   .PP
   300    298   \fBChan copy\fR translates end-of-line sequences in \fIinputChan\fR
   301    299   and \fIoutputChan\fR according to the \fB\-translation\fR option for
   302    300   these channels (see \fBchan configure\fR above).  The translations
   303    301   mean that the number of bytes read from \fIinputChan\fR can be
   304    302   different than the number of bytes written to \fIoutputChan\fR.  Only
   305    303   the number of bytes written to \fIoutputChan\fR is reported, either as
................................................................................
   331    329   returned as the result of the \fBchan create\fR command, and the
   332    330   channel is open. Use either \fBclose\fR or \fBchan close\fR to remove
   333    331   the channel.
   334    332   .RS
   335    333   .PP
   336    334   The argument \fImode\fR specifies if the new channel is opened for
   337    335   reading, writing, or both. It has to be a list containing any of the
   338         -strings
   339         -.QW "\fBread\fR"
   340         -or
   341         -.QW "\fBwrite\fR" .
   342         -The list must have at least one
          336  +strings "\fBread\fR" or "\fBwrite\fR". The list must have at least one
   343    337   element, as a channel you can neither write to nor read from makes no
   344    338   sense. The handler command for the new channel must support the chosen
   345    339   mode, or an error is thrown.
   346    340   .PP
   347    341   The command prefix is executed in the global namespace, at the top of
   348    342   call stack, following the appending of arguments as described in the
   349    343   \fBreflectedchan\fR manual page. Command resolution happens at the
................................................................................
   413    407   writable.  File event handlers are most commonly used to allow data to
   414    408   be received from another process on an event-driven basis, so that the
   415    409   receiver can continue to interact with the user or with other channels
   416    410   while waiting for the data to arrive.  If an application invokes
   417    411   \fBchan gets\fR or \fBchan read\fR on a blocking channel when there is
   418    412   no input data available, the process will block; until the input data
   419    413   arrives, it will not be able to service other events, so it will
   420         -appear to the user to
   421         -.QW "freeze up" .
   422         -With \fBchan event\fR, the
          414  +appear to the user to ``freeze up''.  With \fBchan event\fR, the
   423    415   process can tell when data is present and only invoke \fBchan gets\fR
   424    416   or \fBchan read\fR when they won't block.
   425    417   .PP
   426    418   A channel is considered to be readable if there is unread data
   427    419   available on the underlying device.  A channel is also considered to
   428    420   be readable if there is unread data in an input buffer, except in the
   429    421   special case where the most recent attempt to read from the channel
................................................................................
   500    492   .
   501    493   Produces a list of all channel names. If \fIpattern\fR is specified,
   502    494   only those channel names that match it (according to the rules of
   503    495   \fBstring match\fR) will be returned.
   504    496   .TP
   505    497   \fBchan pending \fImode channelId\fR
   506    498   .
   507         -Depending on whether \fImode\fR is
   508         -.QW "input"
   509         -or
   510         -.QW "output" ,
   511         -returns the number of 
          499  +Depending on whether \fImode\fR is "input" or "output", returns the number of 
   512    500   bytes of input or output (respectively) currently buffered 
   513    501   internally for \fIchannelId\fR (especially useful in a readable event 
   514    502   callback to impose application-specific limits on input line lengths to avoid
   515    503   a potential denial-of-service attack where a hostile user crafts
   516    504   an extremely long line that exceeds the available memory to buffer it).
   517    505   Returns -1 if the channel was not opened for the mode in question.
   518    506   .TP
   519    507   \fBchan postevent \fIchannelId eventSpec\fR
   520    508   .
   521    509   This subcommand is used by command handlers specified with \fBchan
   522    510   create\fR. It notifies the channel represented by the handle
   523    511   \fIchannelId\fR that the event(s) listed in the \fIeventSpec\fR have
   524    512   occurred. The argument has to be a list containing any of the strings
   525         -.QW "\fBread\fR"
   526         -and
   527         -.QW "\fBwrite\fR" .
   528         -The list must contain at least one
          513  +"\fBread\fR" and "\fBwrite\fR". The list must contain at least one
   529    514   element as it does not make sense to invoke the command if there are
   530    515   no events to post.
   531    516   .RS
   532    517   .PP
   533    518   Note that this subcommand can only be used with channel handles that
   534    519   were created/opened by \fBchan create\fR. All other channels will
   535    520   cause this subcommand to report an error.

Changes to doc/clock.n.

     6      6   .TH "clock" n 8.5 Tcl "Tcl Built-In Commands"
     7      7   .BS
     8      8   .SH NAME
     9      9   clock \- Obtain and manipulate dates and times
    10     10   .SH "SYNOPSIS"
    11     11   package require \fBTcl 8.5\fR
    12     12   .sp
    13         -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
           13  +\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR?
    14     14   .sp
    15         -\fBclock clicks\fR ?\fI\-option\fR?
           15  +\fBclock clicks\fR ?\fI-option\fR?
    16     16   .sp
    17         -\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
           17  +\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...?
    18     18   .sp
    19     19   \fBclock microseconds\fR 
    20     20   .sp
    21     21   \fBclock milliseconds\fR 
    22     22   .sp
    23         -\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
           23  +\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...?
    24     24   .sp
    25     25   \fBclock seconds\fR 
    26     26   .sp
    27     27   .BE
    28     28   .SH "DESCRIPTION"
    29     29   .PP
    30     30   The \fBclock\fR command performs several operations that obtain and
    31     31   manipulate values that represent times.  The command supports several
    32     32   subcommands that determine what action is carried out by the command.
    33     33   .TP
    34         -\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI\-option value\fR?
           34  +\fBclock add\fR \fItimeVal\fR ?\fIcount unit...\fR? ?\fI-option value\fR?
    35     35   Adds a (possibly negative) offset to a time that is expressed as an
    36     36   integer number of seconds.  See \fBCLOCK ARITHMETIC\fR for a full description.
    37     37   .TP
    38         -\fBclock clicks\fR ?\fI\-option\fR?
    39         -If no \fI\-option\fR argument is supplied, returns a high-resolution
           38  +\fBclock clicks\fR ?\fI-option\fR?
           39  +If no \fI-option\fR argument is supplied, returns a high-resolution
    40     40   time value as a system-dependent integer value.  The unit of the value
    41     41   is system-dependent but should be the highest resolution clock available
    42     42   on the system such as a CPU cycle counter.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
    43     43   .sp
    44         -If the \fI\-option\fR argument is \fI\-milliseconds\fR, then the command
           44  +If the \fI-option\fR argument is \fI-milliseconds\fR, then the command
    45     45   is synonymous with \fBclock milliseconds\fR (see below).  This
    46     46   usage is obsolete, and \fBclock milliseconds\fR is to be
    47     47   considered the preferred way of obtaining a count of milliseconds.
    48     48   .sp
    49         -If the \fI\-option\fR argument is \fI\-microseconds\fR, then the command
           49  +If the \fI-option\fR argument is \fI-microseconds\fR, then the command
    50     50   is synonymous with \fBclock microseconds\fR (see below).  This
    51     51   usage is obsolete, and \fBclock microseconds\fR is to be
    52     52   considered the preferred way of obtaining a count of microseconds.
    53     53   .TP
    54         -\fBclock format\fR \fItimeVal\fR ?\fI\-option value\fR...?
           54  +\fBclock format\fR \fItimeVal\fR ?\fI-option value\fR...?
    55     55   Formats a time that is expressed as an integer number of seconds into a format
    56     56   intended for consumption by users or external programs.
    57     57   See \fBFORMATTING TIMES\fR for a full description.
    58     58   .TP
    59     59   \fBclock microseconds\fR 
    60     60   Returns the current time as an integer number of microseconds.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
    61     61   .TP
    62     62   \fBclock milliseconds\fR 
    63     63   Returns the current time as an integer number of milliseconds.  See \fBHIGH RESOLUTION TIMERS\fR for a full description.
    64     64   .TP
    65         -\fBclock scan\fR \fIinputString\fR ?\fI\-option value\fR...?
           65  +\fBclock scan\fR \fIinputString\fR ?\fI-option value\fR...?
    66     66   Scans a time that is expressed as a character string and produces an
    67     67   integer number of seconds.
    68     68   See \fBSCANNING TIMES\fR for a full description.
    69     69   .TP
    70     70   \fBclock seconds\fR 
    71     71   Returns the current time as an integer number of seconds.
    72     72   .SS "PARAMETERS"
................................................................................
    89     89   One of the words, \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
    90     90   \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
    91     91   any unique prefix of such a word. Used in conjunction with \fIcount\fR
    92     92   to identify an interval of time, for example, \fI3 seconds\fR or
    93     93   \fI1 year\fR.
    94     94   .SS "OPTIONS"
    95     95   .TP
    96         -\fB\-base\fR time
           96  +\fB-base\fR time
    97     97   Specifies that any relative times present in a \fBclock scan\fR command
    98     98   are to be given relative to \fItime\fR.  \fItime\fR must be expressed as
    99     99   a count of nominal seconds from the epoch time of 1 January 1970, 00:00 UTC.
   100    100   .TP
   101         -\fB\-format\fR format
          101  +\fB-format\fR format
   102    102   Specifies the desired output format for \fBclock format\fR or the
   103    103   expected input format for \fBclock scan\fR.  The \fIformat\fR string consists
   104         -of any number of characters other than the per-cent sign
   105         -.PQ \fI%\fR
          104  +of any number of characters other than the per-cent sign ('\fI%\fR')
   106    105   interspersed with any number of \fIformat groups\fR, which are two-character
   107    106   sequences beginning with the per-cent sign.  The permissible format groups,
   108    107   and their interpretation, are described under \fBFORMAT GROUPS\fR.
   109    108   .RS
   110    109   .PP
   111    110   On \fBclock format\fR, the default format is
   112    111   .CS
   113    112   %a %b %d %H:%M:%S %z %Y
   114    113   .CE
   115    114   .PP
   116         -On \fBclock scan\fR, the lack of a \fI\-format\fR option indicates that a
   117         -.QW "free format scan"
   118         -is requested; see \fBFREE FORM SCAN\fR for a description of what happens.
          115  +On \fBclock scan\fR, the lack of a \fI-format\fR option indicates that
          116  +a "free format scan" is requested; see \fBFREE FORM SCAN\fR for a
          117  +description of what happens.
   119    118   .RE
   120    119   .TP
   121         -\fB\-gmt\fR boolean
          120  +\fB-gmt\fR boolean
   122    121   If \fIboolean\fR is true, specifies that a time specified to \fBclock add\fR,
   123    122   \fBclock format\fR or \fBclock scan\fR should be processed in
   124    123   UTC.  If \fIboolean\fR is false, the processing defaults to the local time
   125    124   zone.  This usage is obsolete; the correct current usage is to
   126         -specify the UTC time zone with
   127         -.QW "\fB\-timezone\fR \fI:UTC\fR"
   128         -or any of the equivalent ways to specify it.
          125  +specify the UTC time zone with '\fB-timezone\fR \fI:UTC\fR' or any of
          126  +the equivalent ways to specify it.
   129    127   .TP
   130         -\fB\-locale\fR localeName
          128  +\fB-locale\fR localeName
   131    129   Specifies that locale-dependent scanning and formatting (and date arithmetic
   132    130   for dates preceding the adoption of the Gregorian calendar) is to be done in
   133    131   the locale identified by \fIlocaleName\fR.  The locale name may be any of
   134    132   the locales acceptable to the \fBmsgcat\fR package, or it may be the special
   135    133   name \fIsystem\fR, which represents the current locale of the process, or
   136    134   the null string, which represents Tcl's default locale.
   137    135   .sp
   138    136   The effect of locale on scanning and formatting is discussed in the
   139    137   descriptions of the individual format groups under \fBFORMAT GROUPS\fR.
   140    138   The effect of locale on clock arithmetic is discussed under
   141    139   \fBCLOCK ARITHMETIC\fR.
   142    140   .TP
   143         -\fB\-timezone\fR zoneName
          141  +\fB-timezone\fR zoneName
   144    142   Specifies that clock arithmetic, formatting, and scanning are to be done
   145    143   according to the rules for the time zone specified by \fIzoneName\fR.
   146    144   The permissible values, and their interpretation, are discussed under
   147    145   \fBTIME ZONES\fR.
   148         -On subcommands that expect a \fB\-timezone\fR argument, the default
          146  +On subcommands that expect a \fB-timezone\fR argument, the default
   149    147   is to use the \fIcurrent time zone\fR.  The current time zone is
   150    148   determined, in order of preference, by:
   151    149   .RS
   152    150   .IP [1]
   153    151   the environment variable \fBTCL_TZ\fR.
   154    152   .IP [2]
   155    153   the environment variable \fBTZ\fR.
................................................................................
   161    159   Greenwich.  On 32-bit systems, this approach is likely to have bugs,
   162    160   particularly for times that lie outside the window (approximately the
   163    161   years 1902 to 2037) that can be represented in a 32-bit integer.
   164    162   .SH "CLOCK ARITHMETIC"
   165    163   The \fBclock add\fR command performs clock arithmetic on a value
   166    164   (expressed as nominal seconds from the epoch time of 1 January 1970, 00:00 UTC)
   167    165   given as its first argument.  The remaining arguments (other than the
   168         -possible \fB\-timezone\fR, \fB\-locale\fR and \fB\-gmt\fR options)
          166  +possible \fB-timezone\fR, \fB-locale\fR and \fB-gmt\fR options)
   169    167   are integers and keywords in alternation, where the keywords are chosen
   170    168   from \fBseconds\fR, \fBminutes\fR, \fBhours\fR,
   171    169   \fBdays\fR, \fBweeks\fR, \fBmonths\fR, or \fByears\fR, or
   172    170   any unique prefix of such a word.
   173    171   .PP
   174    172   Addition of seconds, minutes and hours is fairly straightforward;
   175    173   the given time increment (times sixty for minutes, or 3600 for hours)
................................................................................
   282    280   .SH "FORMATTING TIMES"
   283    281   The \fBclock format\fR command produces times for display to a user
   284    282   or writing to an external medium.  The command accepts times that are
   285    283   expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC,
   286    284   as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR,
   287    285   \fBfile atime\fR or \fBfile mtime\fR.
   288    286   .PP
   289         -If a \fB\-format\fR option is present, the following argument is
          287  +If a \fB-format\fR option is present, the following argument is
   290    288   a string that specifies how the date and time are to be formatted.
   291    289   The string consists
   292         -of any number of characters other than the per-cent sign
   293         -.PQ \fI%\fR
          290  +of any number of characters other than the per-cent sign ('\fI%\fR')
          291  +interspersed with any number of \fIformat groups\fR, which are two-character
          292  +sequences beginning with the per-cent sign.  The permissible format groups,
          293  +and their interpretation, are described under \fBFORMAT GROUPS\fR.
          294  +.PP
          295  +If a \fB-timezone\fR option is present, the following
          296  +argument is a string that specifies the time zone in which the date and time
          297  +are to be formatted.  As an alternative to \fB-timezone\fR \fI:UTC\fR,
          298  +the obsolete usage \fB-gmt\fR \fItrue\fR may be used.  See
          299  +\fBTIME ZONES\fR for the permissible variants for the time zone.
          300  +.PP
          301  +If a \fB-locale\fR option is present, the following argument is
          302  +a string that specifies the locale in which the time is to be formatted,
          303  +in the same format that is used for the \fBmsgcat\fR package.  Note
          304  +that the default, if \fB-locale\fR is not specified, is the root locale
          305  +\fB{}\fR rather than the current locale.  The current locale may
          306  +be obtained by using \fB-locale\fR \fBcurrent\fR.
          307  +In addition, some platforms support a \fBsystem\fR locale that
          308  +reflects the user's current choices.  For instance, on Windows, the
          309  +format that the user has selected from dates and times in the Control
          310  +Panel can be obtained by using the \fBsystem\fR locale.  On
          311  +platforms that do not define a user selection of date and time formats
          312  +separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is
          313  +synonymous with \fB-locale\fR \fBcurrent\fR.
          314  +.SH "SCANNING TIMES"
          315  +The \fBclock scan\fR command accepts times that are formatted as
          316  +strings and converts them to counts of seconds from the epoch time
          317  +of 1 January 1970, 00:00 UTC.  It normally takes a \fB-format\fR
          318  +option that is followed by a string describing
          319  +the expected format of the input.  (See
          320  +\fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR
          321  +without such an argument.)  The string consists of any number of
          322  +characters other than the per-cent sign ('\fI%\fR'),
   294    323   interspersed with any number of \fIformat groups\fR, which are two-character
   295    324   sequences beginning with the per-cent sign.  The permissible format groups,
   296    325   and their interpretation, are described under \fBFORMAT GROUPS\fR.
   297    326   .PP
   298         -If a \fB\-timezone\fR option is present, the following
          327  +If a \fB-timezone\fR option is present, the following
   299    328   argument is a string that specifies the time zone in which the date and time
   300         -are to be formatted.  As an alternative to
   301         -.QW "\fB\-timezone\fR \fI:UTC\fR" ,
   302         -the obsolete usage
   303         -.QW "\fB\-gmt\fR \fItrue\fR"
   304         -may be used. See \fBTIME ZONES\fR for the permissible variants for the time
   305         -zone.
          329  +are to be interpreted.  As an alternative to \fB-timezone\fR \fI:UTC\fR,
          330  +the obsolete usage \fB-gmt\fR \fItrue\fR may be used.  See
          331  +\fBTIME ZONES\fR for the permissible variants for the time zone.
   306    332   .PP
   307         -If a \fB\-locale\fR option is present, the following argument is
   308         -a string that specifies the locale in which the time is to be formatted,
          333  +If a \fB-locale\fR option is present, the following argument is
          334  +a string that specifies the locale in which the time is to be interpreted,
   309    335   in the same format that is used for the \fBmsgcat\fR package.  Note
   310         -that the default, if \fB\-locale\fR is not specified, is the root locale
          336  +that the default, if \fB-locale\fR is not specified, is the root locale
   311    337   \fB{}\fR rather than the current locale.  The current locale may
   312         -be obtained by using
   313         -.QW "\fB\-locale\fR \fBcurrent\fR" .
          338  +be obtained by using \fB-locale\fR \fBcurrent\fR.
   314    339   In addition, some platforms support a \fBsystem\fR locale that
   315    340   reflects the user's current choices.  For instance, on Windows, the
   316    341   format that the user has selected from dates and times in the Control
   317    342   Panel can be obtained by using the \fBsystem\fR locale.  On
   318    343   platforms that do not define a user selection of date and time formats
   319         -separate from \fBLC_TIME\fR,
   320         -.QW "\fB\-locale\fR \fBsystem\fR"
   321         -is synonymous with
   322         -.QW "\fB\-locale\fR \fBcurrent\fR" .
   323         -.SH "SCANNING TIMES"
   324         -The \fBclock scan\fR command accepts times that are formatted as
   325         -strings and converts them to counts of seconds from the epoch time
   326         -of 1 January 1970, 00:00 UTC.  It normally takes a \fB\-format\fR
   327         -option that is followed by a string describing
   328         -the expected format of the input.  (See
   329         -\fBFREE FORM SCAN\fR for the effect of \fBclock scan\fR
   330         -without such an argument.)  The string consists of any number of
   331         -characters other than the per-cent sign
   332         -.PQ \fI%\fR "" ,
   333         -interspersed with any number of \fIformat groups\fR, which are two-character
   334         -sequences beginning with the per-cent sign.  The permissible format groups,
   335         -and their interpretation, are described under \fBFORMAT GROUPS\fR.
          344  +separate from \fBLC_TIME\fR, \fB-locale\fR \fBsystem\fR is
          345  +synonymous with \fB-locale\fR \fBcurrent\fR.
   336    346   .PP
   337         -If a \fB\-timezone\fR option is present, the following
   338         -argument is a string that specifies the time zone in which the date and time
   339         -are to be interpreted.  As an alternative to
   340         -.QW "\fB\-timezone\fR \fI:UTC\fR" ,
   341         -the obsolete usage
   342         -.QW "\fB\-gmt\fR \fItrue\fR"
   343         -may be used. See \fBTIME ZONES\fR for the permissible variants for the time
   344         -zone.
   345         -.PP
   346         -If a \fB\-locale\fR option is present, the following argument is
   347         -a string that specifies the locale in which the time is to be interpreted,
   348         -in the same format that is used for the \fBmsgcat\fR package.  Note
   349         -that the default, if \fB\-locale\fR is not specified, is the root locale
   350         -.MT
   351         -rather than the current locale. The current locale may be obtained by using
   352         -.QW "\fB\-locale\fR \fBcurrent\fR" .
   353         -In addition, some platforms support a \fBsystem\fR locale that
   354         -reflects the user's current choices.  For instance, on Windows, the
   355         -format that the user has selected from dates and times in the Control
   356         -Panel can be obtained by using the \fBsystem\fR locale.  On
   357         -platforms that do not define a user selection of date and time formats
   358         -separate from \fBLC_TIME\fR,
   359         -.QW "\fB\-locale\fR \fBsystem\fR"
   360         -is synonymous with
   361         -.QW "\fB\-locale\fR \fBcurrent\fR" .
   362         -.PP
   363         -If a \fB\-base\fR option is present, the following argument is
          347  +If a \fB-base\fR option is present, the following argument is
   364    348   a time (expressed in seconds from the epoch time) that is used as
   365    349   a \fIbase time\fR for interpreting relative times.  If no
   366         -\fB\-base\fR option is present, the base time is the current time.
          350  +\fB-base\fR option is present, the base time is the current time.
   367    351   .PP
   368    352   Scanning of times in fixed format works by determining three things:
   369    353   the date, the time of day, and the time zone.  These three are then
   370    354   combined into a point in time, which is returned as the number of seconds
   371    355   from the epoch.
   372    356   .PP
   373    357   Before scanning begins, the format string is preprocessed
................................................................................
   434    418   the minute of the hour, that group combines with the hour.  If the string
   435    419   further contains a group specifying the second of the minute, that group
   436    420   combines with the hour and minute.
   437    421   .IP [3]
   438    422   If the string contains neither a \fB%s\fR format group nor
   439    423   a group specifying the hour of the day, then midnight (\fB00:00\fR, the start
   440    424   of the given date) is used.
   441         -The time zone is determined by either the \fB\-timezone\fR or \fB\-gmt\fR
          425  +The time zone is determined by either the \fB-timezone\fR or \fB-gmt\fR
   442    426   options, or by using the current time zone.
   443    427   .PP
   444    428   If a format string lacks a \fB%z\fR or \fB%Z\fR format group,
   445    429   it is possible for the time to be ambiguous because it appears twice
   446    430   in the same day, once without and once with Daylight Saving Time.
   447    431   If this situation occurs, the first occurrence of the time is chosen.
   448    432   (For this reason, it is wise to have the input string contain the
................................................................................
   599    583   \fB%N\fR
   600    584   On output, produces the number of the month (1-12) with one or two digits.
   601    585   digits.  On input, accepts one or two digits, possibly with leading whitespace,
   602    586   and interprets them as the number of the month.
   603    587   .TP
   604    588   \fB%Od\fR, \fB%Oe\fR, \fB%OH\fR, \fB%OI\fR, \fB%Ok\fR, \fB%Ol\fR, \fB%Om\fR, \fB%OM\fR, \fB%OS\fR, \fB%Ou\fR, \fB%Ow\fR, \fB%Oy\fR
   605    589   All of these format groups are synonymous with their counterparts
   606         -without the
   607         -.QW \fBO\fR ,
   608         -except that the string is produced and parsed in the locale-dependent
   609         -alternative numerals.
          590  +without the '\fBO\fR', except that the string is produced and parsed in the
          591  +locale-dependent alternative numerals.
   610    592   .TP
   611    593   \fB%p\fR
   612         -.
   613    594   On output, produces an indicator for the part of the day, \fBAM\fR
   614    595   or \fBPM\fR, appropriate to the given locale.  If the script of the
   615    596   given locale supports multiple letterforms, lowercase is preferred.
   616    597   On input, matches the representation \fBAM\fR or \fBPM\fR in
   617    598   the given locale, in either case.
   618    599   .TP
   619    600   \fB%P\fR
................................................................................
   724    705   time zone. This option should, in general, be used on input only when
   725    706   parsing RFC822 dates. Other uses are fraught with ambiguity; for
   726    707   instance, the string \fBBST\fR may represent British Summer Time or
   727    708   Brazilian Standard Time. It is recommended that date/time strings for
   728    709   use by computers use numeric time zones instead.
   729    710   .TP
   730    711   \fB%%\fR
   731         -On output, produces a literal
   732         -.QW \fB%\fR
   733         -character. On input, matches a literal
   734         -.QW \fB%\fR
   735         -character.
          712  +On output, produces a literal '\fB%\fR' character. On input, matches
          713  +a literal '\fB%\fR' character.
   736    714   .TP
   737    715   \fB%+\fR
   738         -Synonymous with
   739         -.QW "\fB%a %b %e %H:%M:%S %Z %Y\fR" .
          716  +Synonymous with '\fB%a %b %e %H:%M:%S %Z %Y\fR'.
   740    717   .SH "TIME ZONES"
   741    718   When the \fBclock\fR command is processing a local time, it has several
   742    719   possible sources for the time zone to use.  In order of preference, they
   743    720   are:
   744    721   .IP [1]
   745    722   A time zone specified inside a string being parsed and matched by a \fB%z\fR
   746    723   or \fB%Z\fR format group.
   747    724   .IP [2]
   748         -A time zone specified with the \fB\-timezone\fR option to the \fBclock\fR
   749         -command (or, equivalently, by
   750         -.QW "\fB\-gmt\fR \fB1\fR" ).
          725  +A time zone specified with the \fB-timezone\fR option to the \fBclock\fR
          726  +command (or, equivalently, by \fB-gmt\fR \fB1\fR).
   751    727   .IP [3]
   752    728   A time zone specified in an environment variable \fBTCL_TZ\fR.
   753    729   .IP [4]
   754    730   A time zone specified in an environment variable \fBTZ\fR.
   755    731   .IP [5]
   756    732   The local time zone from the Control Panel on Windows systems.
   757    733   .IP [6]
................................................................................
   779    755   .PP
   780    756   If the time zone begins with a colon, it is one of a
   781    757   standardized list of names like \fB:America/New_York\fR
   782    758   that give the rules for various locales.  A complete list
   783    759   of the location names is too lengthy to be listed here.
   784    760   On most Tcl installations, the definitions of the locations
   785    761   are to be found in named files in the directory
   786         -.QW "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR" .
   787         -On some Unix systems, these
          762  + "\fI/no_backup/tools/lib/tcl8.5/clock/tzdata\fR".  On some Unix systems, these
   788    763   files are omitted, and the definitions are instead
   789         -obtained from system files in
   790         -.QW "\fI/usr/share/zoneinfo\fR" ,
   791         -.QW "\fI/usr/share/lib/zoneinfo\fR"
   792         -or
   793         -.QW "\fI/usr/local/etc/zoneinfo\fR" .
          764  +obtained from system files in "\fI/usr/share/zoneinfo\fR",
          765  + "\fI/usr/share/lib/zoneinfo\fR" or "\fI/usr/local/etc/zoneinfo\fR".
   794    766   As a special case, the name \fB:localtime\fR refers to
   795    767   the local time zone as defined by the C library.
   796    768   .PP
   797    769   A time zone string consisting of a plus or minus sign followed by
   798    770   four or six decimal digits is interpreted as an offset in
   799    771   hours, minutes, and seconds (if six digits are present) from
   800    772   UTC.  The plus sign denotes a sign east of Greenwich;
................................................................................
   808    780   Any other time zone string is processed by prefixing a colon and attempting
   809    781   to use it as a location name, as above.
   810    782   .SH "LOCALIZATION"
   811    783   Developers wishing to localize the date and time formatting and parsing
   812    784   are referred to \fIhttp://tip.tcl.tk/173\fR for a
   813    785   specification.
   814    786   .SH "FREE FORM SCAN"
   815         -If the \fBclock scan\fR command is invoked without a \fB\-format\fR
          787  +If the \fBclock scan\fR command is invoked without a \fB-format\fR
   816    788   option, then it requests a \fIfree-form scan.\fR  \fI
   817    789   This form of scan is deprecated.\fR  The reason for the deprecation
   818         -is that there are too many ambiguities. (Does the string
   819         -.QW 2000
          790  +is that there are too many ambiguities. (Does the string '2000'
   820    791   represent a year, a time of day, or a quantity?)  No set of rules
   821    792   for interpreting free-form dates and times has been found to
   822    793   give unsurprising results in all cases.
   823    794   .PP
   824         -If free-form scan is used, only the \fB\-base\fR and \fB\-gmt\fR
   825         -options are accepted.  The \fB\-timezone\fR and \fB\-locale\fR
   826         -options will result in an error if \fB\-format\fR is not supplied.
          795  +If free-form scan is used, only the \fB-base\fR and \fB-gmt\fR
          796  +options are accepted.  The \fB-timezone\fR and \fB-locale\fR
          797  +options will result in an error if \fB-format\fR is not supplied.
   827    798   .PP
   828    799   For the benefit of users who need to understand legacy code that
   829    800   uses free-form scan, the documentation for how free-form scan
   830    801   interprets a string is included here:
   831    802   .PP
   832    803   If only a time is
   833    804   specified, the current date is assumed.  If the \fIinputString\fR
   834    805   does not contain a
   835         -time zone mnemonic, the local time zone is assumed, unless the \fB\-gmt\fR
          806  +time zone mnemonic, the local time zone is assumed, unless the \fB-gmt\fR
   836    807   argument is true, in which case the clock value is calculated assuming
   837    808   that the specified time is relative to Greenwich Mean Time.
   838         -\fB\-gmt\fR, if specified, affects only the computed time value; it does not
   839         -impact the interpretation of \fB\-base\fR.
          809  +\fB-gmt\fR, if specified, affects only the computed time value; it does not
          810  +impact the interpretation of \fB-base\fR.
   840    811   .PP
   841         -If the \fB\-base\fR flag is specified, the next argument should contain
          812  +If the \fB-base\fR flag is specified, the next argument should contain
   842    813   an integer clock value.  Only the date in this value is used, not the
   843    814   time.  This is useful for determining the time on a specific day or
   844    815   doing other date-relative conversions.
   845    816   .PP
   846    817   The \fIinputString\fR argument consists of zero or more specifications of the
   847    818   following form:
   848    819   .TP
................................................................................
   849    820   \fItime\fR
   850    821   A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR
   851    822   or \fBhhmm ?meridian? ?zone?\fR
   852    823   If no meridian is specified, \fBhh\fR is interpreted on
   853    824   a 24-hour clock.
   854    825   .TP
   855    826   \fIdate\fR
   856         -A specific month and day with optional year. The acceptable formats are
   857         -.QW "\fBmm/dd\fR?\fB/yy\fR?" ,
   858         -.QW "\fBmonthname dd\fR?\fB, yy\fR?" ,
   859         -.QW "\fBday, dd monthname \fR?\fByy\fR?" ,
   860         -.QW "\fBdd monthname yy\fR" ,
   861         -.QW "?\fBCC\fR?\fByymmdd\fR" ,
   862         -and
   863         -.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" .
          827  +A specific month and day with optional year.  The
          828  +acceptable formats are "\fBmm/dd\fR?\fB/yy\fR?",
          829  + "\fBmonthname dd\fR?\fB, yy\fR?",
          830  + "\fBday, dd monthname \fR?\fByy\fR?",
          831  + "\fBdd monthname yy\fR",
          832  + "?\fBCC\fR?\fByymmdd\fR", and
          833  + "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR".
   864    834   The default year is the current year.  If the year is less
   865    835   than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
   866    836   as 1969-1999.  Not all platforms can represent the years 38-70, so
   867    837   an error may result if these years are used.
   868    838   .TP
   869    839   \fIISO 8601 point-in-time\fR
   870    840   An ISO 8601 point-in-time specification, such as \fBCCyymmddThhmmss\fR,
   871         -where \fBT\fR is the literal
   872         -.QW T ,
   873         -.QW "\fBCCyymmdd hhmmss\fR" ,
   874         -or
   875         -.QW \fBCCyymmddThh:mm:ss\fR .
   876         -Note that only these three formats are accepted.
          841  +where \fBT\fR is the literal T, "\fBCCyymmdd hhmmss\fR", or
          842  +\fBCCyymmddThh:mm:ss\fR. Note that only these three formats are accepted.
   877    843   The command does \fInot\fR accept the full range of point-in-time
   878    844   specifications specified in ISO8601.  Other formats can be recognized by
   879         -giving an explicit \fI\-format\fR option to the \fBclock scan\fR command.
          845  +giving an explicit \fI-format\fR option to the \fBclock scan\fR command.
   880    846   .TP
   881    847   \fIrelative time\fR
   882    848   A specification relative to the current time.  The format is \fBnumber
   883    849   unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR, 
   884    850   \fBmonth\fR, \fBweek\fR, \fBday\fR,
   885    851   \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR).  The
   886    852   unit can be specified as a singular or plural, as in \fB3 weeks\fR.

Changes to doc/close.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: close.n,v 1.11 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: close.n,v 1.12 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH close n 7.5 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   close \- Close an open channel
................................................................................
    67     67       catch {
    68     68           uplevel 1 $script
    69     69       } result options
    70     70       \fBclose\fR $chan
    71     71       return -options $options $result
    72     72   }
    73     73   .CE
           74  +
    74     75   .SH "SEE ALSO"
    75     76   file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3)
           77  +
    76     78   .SH KEYWORDS
    77     79   blocking, channel, close, nonblocking

Changes to doc/concat.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: concat.n,v 1.8 2007/10/25 14:07:32 dkf Exp $
            8  +'\" RCS: @(#) $Id: concat.n,v 1.9 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH concat n 8.3 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   concat \- Join lists together
................................................................................
    26     26   It permits any number of arguments;
    27     27   if no \fIarg\fRs are supplied, the result is an empty string.
    28     28   .SH EXAMPLES
    29     29   Although \fBconcat\fR will concatenate lists (so the command:
    30     30   .CS
    31     31   \fBconcat\fR a b {c d e} {f {g h}}
    32     32   .CE
    33         -will return
    34         -.QW "\fBa b c d e f {g h}\fR"
    35         -as its result), it will also
           33  +will return "\fBa b c d e f {g h}\fR" as its result), it will also
    36     34   concatenate things that are not lists, and hence the command:
    37     35   .CS
    38     36   \fBconcat\fR " a b {c   " d "  e} f"
    39     37   .CE
    40         -will return
    41         -.QW "\fBa b {c d e} f\fR"
    42         -as its result.
           38  +will return "\fBa b {c d e} f\fR" as its result.
    43     39   .PP
    44     40   Note that the concatenation does not remove spaces from the middle of
    45     41   its arguments, so the command:
    46     42   .CS
    47     43   \fBconcat\fR "a   b   c" { d e f }
    48     44   .CE
    49         -will return
    50         -.QW "\fBa   b   c d e f\fR"
    51         -(i.e. with three spaces between the
    52         -.QW \fBa\fR ,
    53         -the
    54         -.QW \fBb\fR
    55         -and the
    56         -.QW \fBc\fR ).
           45  +will return "\fBa   b   c d e f\fR" (i.e. with three spaces between
           46  +the \fBa\fR, the \fBb\fR and the \fBc\fR).
           47  +
    57     48   .SH "SEE ALSO"
    58     49   append(n), eval(n)
           50  +
    59     51   .SH KEYWORDS
    60     52   concatenate, join, lists

Changes to doc/continue.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993-1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: continue.n,v 1.8 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: continue.n,v 1.9 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH continue n "" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   continue \- Skip to the next iteration of a loop
................................................................................
    35     35   for {set x 0} {$x<10} {incr x} {
    36     36      if {$x == 5} {
    37     37         \fBcontinue\fR
    38     38      }
    39     39      puts "x is $x"
    40     40   }
    41     41   .CE
           42  +
    42     43   .SH "SEE ALSO"
    43     44   break(n), for(n), foreach(n), return(n), while(n)
           45  +
    44     46   .SH KEYWORDS
    45     47   continue, iteration, loop

Changes to doc/dde.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1997 Sun Microsystems, Inc.
     3      3   '\" Copyright (c) 2001 ActiveState Corporation.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: dde.n,v 1.19 2007/10/25 14:07:32 dkf Exp $
            8  +'\" RCS: @(#) $Id: dde.n,v 1.20 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH dde n 1.3 dde "Tcl Bundled Packages"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   dde \- Execute a Dynamic Data Exchange command
................................................................................
    44     44   .PP
    45     45   .SH "DDE COMMANDS"
    46     46   .PP
    47     47   The following commands are a subset of the full Dynamic Data Exchange
    48     48   set of commands.
    49     49   .TP
    50     50   \fBdde servername \fR?\fB-force\fR? ?\fB-handler \fIproc\fR? ?\fB--\fR? ?\fItopic\fR?
    51         -.
    52     51   \fBdde servername\fR registers the interpreter as a DDE server with
    53     52   the service name \fBTclEval\fR and the topic name specified by \fItopic\fR.
    54     53   If no \fItopic\fR is given, \fBdde servername\fR returns the name
    55     54   of the current topic or the empty string if it is not registered as a
    56     55   service. If the given \fItopic\fR name is already in use, then a
    57         -suffix of the form
    58         -.QW " #2"
    59         -or
    60         -.QW " #3"
    61         -is appended to the name to make it
           56  +suffix of the form ' #2' or ' #3' is appended to the name to make it
    62     57   unique. The command's result will be the name actually used. The
    63         -\fB\-force\fR option is used to force registration of precisely the
           58  +\fB-force\fR option is used to force registration of precisely the
    64     59   given \fItopic\fR name.
    65     60   .IP
    66     61   The \fB-handler\fR option specifies a Tcl procedure that will be called to
    67     62   process calls to the dde server. If the package has been loaded into a
    68     63   safe interpreter then a \fB-handler\fR procedure must be defined. The
    69     64   procedure is called with all the arguments provided by the remote
    70     65   call.
    71     66   .TP
    72     67   \fBdde execute\fR ?\fB\-async\fR? \fIservice topic data\fR
    73         -.
    74     68   \fBdde execute\fR takes the \fIdata\fR and sends it to the server indicated
    75     69   by \fIservice\fR with the topic indicated by \fItopic\fR. Typically,
    76     70   \fIservice\fR is the name of an application, and \fItopic\fR is a file to
    77     71   work on.  The \fIdata\fR field is given to the remote application.
    78     72   Typically, the application treats the \fIdata\fR field as a script, and the
    79     73   script is run in the application.  The \fB\-async\fR option requests
    80     74   asynchronous invocation.  The command returns an error message if the
    81     75   script did not run, unless the \fB\-async\fR flag was used, in which case
    82     76   the command returns immediately with no error.
    83     77   .TP
    84     78   \fBdde poke \fIservice topic item data\fR
    85         -.
    86     79   \fBdde poke\fR passes the \fIdata\fR to the server indicated by
    87     80   \fIservice\fR using the \fItopic\fR and \fIitem\fR specified.  Typically,
    88     81   \fIservice\fR is the name of an application.  \fItopic\fR is application
    89     82   specific but can be a command to the server or the name of a file to work
    90     83   on.  The \fIitem\fR is also application specific and is often not used, but
    91     84   it must always be non-null.  The \fIdata\fR field is given to the remote
    92     85   application.
    93     86   .TP
    94     87   \fBdde request\fR ?\fB\-binary\fR? \fIservice topic item\fR
    95         -.
    96     88   \fBdde request\fR is typically used to get the value of something; the
    97     89   value of a cell in Microsoft Excel or the text of a selection in
    98     90   Microsoft Word. \fIservice\fR is typically the name of an application,
    99     91   \fItopic\fR is typically the name of the file, and \fIitem\fR is
   100     92   application-specific. The command returns the value of \fIitem\fR as
   101     93   defined in the application.  Normally this is interpreted to be a
   102     94   string with terminating null.  If \fB\-binary\fR is specified, the
   103     95   result is returned as a byte array.
   104     96   .TP
   105     97   \fBdde services \fIservice topic\fR
   106         -.
   107     98   \fBdde services\fR returns a list of service-topic pairs that
   108     99   currently exist on the machine. If \fIservice\fR and \fItopic\fR are
   109    100   both empty strings ({}), then all service-topic pairs currently
   110    101   available on the system are returned. If \fIservice\fR is empty and
   111    102   \fItopic\fR is not, then all services with the specified topic are
   112    103   returned. If \fIservice\fR is non-empty and \fItopic\fR is, all topics
   113    104   for a given service are returned. If both are non-empty, if that
   114    105   service-topic pair currently exists, it is returned; otherwise, an
   115    106   empty string is returned.
   116    107   .TP
   117    108   \fBdde eval\fR ?\fB\-async\fR? \fItopic cmd \fR?\fIarg arg ...\fR?
   118         -.
   119    109   \fBdde eval\fR evaluates a command and its arguments using the interpreter
   120    110   specified by \fItopic\fR. The DDE service must be the \fBTclEval\fR
   121    111   service.  The \fB\-async\fR option requests asynchronous invocation.  The
   122    112   command returns an error message if the script did not run, unless the
   123    113   \fB\-async\fR flag was used, in which case the command returns immediately
   124    114   with no error.  This command can be used to replace send on Windows.
   125    115   .SH "DDE AND TCL"
................................................................................
   157    147   .SH EXAMPLE
   158    148   This asks Internet Explorer (which must already be running) to go to a
   159    149   particularly important website:
   160    150   .CS
   161    151   package require dde
   162    152   \fBdde execute\fR iexplore WWW_OpenURL http://www.tcl.tk/
   163    153   .CE
          154  +
   164    155   .SH "SEE ALSO"
   165    156   tk(n), winfo(n), send(n)
          157  +
   166    158   .SH KEYWORDS
   167    159   application, dde, name, remote execution

Changes to doc/dict.n.

     1      1   '\"
     2      2   '\" Copyright (c) 2003 Donal K. Fellows
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\"
     7         -'\" RCS: @(#) $Id: dict.n,v 1.13 2007/10/24 14:29:38 dkf Exp $
            7  +'\" RCS: @(#) $Id: dict.n,v 1.14 2007/10/26 20:11:52 dgp Exp $
     8      8   '\"
     9      9   .so man.macros
    10     10   .TH dict n 8.5 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   dict \- Manipulate dictionaries
................................................................................
   253    253      }
   254    254   }
   255    255   # Another way to iterate and pick out names...
   256    256   foreach id [\fBdict keys\fR $employeeInfo] {
   257    257      puts "Hello, [\fBdict get\fR $employeeInfo $id forenames]!"
   258    258   }
   259    259   .CE
   260         -.PP
          260  +
   261    261   A localizable version of \fBstring toupper\fR:
   262    262   .CS
   263    263   # Set up the basic C locale
   264    264   set capital [\fBdict create\fR C [\fBdict create\fR]]
   265    265   foreach c [split {abcdefghijklmnopqrstuvwxyz} ""] {
   266    266      \fBdict set\fR capital C $c [string toupper $c]
   267    267   }
................................................................................
   273    273   
   274    274   # ... and so on for other supported languages ...
   275    275   
   276    276   # Now get the mapping for the current locale and use it.
   277    277   set upperCaseMap [\fBdict get\fR $capital $env(LANG)]
   278    278   set upperCase [string map $upperCaseMap $string]
   279    279   .CE
          280  +
   280    281   .SH "SEE ALSO"
   281    282   append(n), array(n), foreach(n), incr(n), list(n), lappend(n), set(n)
          283  +
   282    284   .SH KEYWORDS
   283    285   dictionary, create, update, lookup, iterate, filter

Changes to doc/encoding.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1998 by Scriptics Corporation.
     3      3   '\" 
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: encoding.n,v 1.11 2007/10/26 12:25:06 dkf Exp $
            7  +'\" RCS: @(#) $Id: encoding.n,v 1.12 2007/10/26 20:11:52 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH encoding n "8.1" Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   .SH NAME
    13     13   encoding \- Manipulate encodings
    14     14   .SH SYNOPSIS
................................................................................
    78     78   that maps to the 00 page in Unicode.  The resulting Tcl strings will
    79     79   not contain the expected Japanese characters.  Instead, they will
    80     80   contain a sequence of Latin-1 characters that correspond to the bytes
    81     81   of the original string.  The \fBencoding\fR command can be used to
    82     82   convert this string to the expected Japanese Unicode characters.  For
    83     83   example,
    84     84   .CS
    85         -set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
           85  +set s [\fBencoding convertfrom\fR euc-jp "\\xA4\\xCF"]
    86     86   .CE
    87         -would return the Unicode string
    88         -.QW "\eu306F" ,
    89         -which is the Hiragana letter HA.
           87  +would return the Unicode string "\\u306F", which is the Hiragana
           88  +letter HA.
           89  +
    90     90   .SH "SEE ALSO"
    91         -fconfigure(n), Tcl_GetEncoding(3)
           91  +Tcl_GetEncoding(3)
           92  +
    92     93   .SH KEYWORDS
    93     94   encoding

Changes to doc/eof.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: eof.n,v 1.7 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: eof.n,v 1.8 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH eof n 7.5 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   eof \- Check for end of file condition on channel
................................................................................
    51     51       if {[\fBeof\fR $f]} {
    52     52           close $f
    53     53           break
    54     54       }
    55     55       puts "Read record: $record"
    56     56   }
    57     57   .CE
           58  +
    58     59   .SH "SEE ALSO"
    59     60   file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3)
           61  +
    60     62   .SH KEYWORDS
    61     63   channel, end of file

Changes to doc/exec.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2006 Donal K. Fellows.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: exec.n,v 1.18 2007/10/25 14:07:32 dkf Exp $
            9  +'\" RCS: @(#) $Id: exec.n,v 1.19 2007/10/26 20:11:52 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH exec n 8.5 Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   exec \- Invoke subprocesses
................................................................................
    45     45   Marks the end of switches.  The argument following this one will
    46     46   be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
    47     47   .PP
    48     48   If an \fIarg\fR (or pair of \fIarg\fRs) has one of the forms
    49     49   described below then it is used by \fBexec\fR to control the
    50     50   flow of input and output among the subprocess(es).
    51     51   Such arguments will not be passed to the subprocess(es).  In forms
    52         -such as
    53         -.QW "< \fIfileName\fR" ,
    54         -\fIfileName\fR may either be in a separate argument from
    55         -.QW <
    56         -or in the same argument with no intervening space (i.e.
    57         -.QW <\fIfileName\fR ).
           52  +such as ``< \fIfileName\fR'' \fIfileName\fR may either be in a
           53  +separate argument from ``<'' or in the same argument with no
           54  +intervening space (i.e. ``<\fIfileName\fR'').
    58     55   .TP 15
    59     56   |
    60     57   Separates distinct commands in the pipeline.  The standard output
    61     58   of the preceding command will be piped into the standard input
    62     59   of the next command.
    63     60   .TP 15
    64     61   |&
................................................................................
   133    130   all commands are redirected to \fIfileId\fR's file.
   134    131   The file must have been opened for writing.
   135    132   .PP
   136    133   If standard output has not been redirected then the \fBexec\fR
   137    134   command returns the standard output from the last command
   138    135   in the pipeline,
   139    136   .VS 8.5
   140         -unless
   141         -.QW 2>@1
   142         -was specified, in which case standard error is included as well.
          137  +unless ``2>@1'' was specified, in which case
          138  +standard error is included as well.
   143    139   .VE 8.5
   144    140   If any of the commands in the pipeline exit abnormally or
   145    141   are killed or suspended, then \fBexec\fR will return an error
   146    142   and the error message will include the pipeline's output followed by
   147    143   error messages describing the abnormal terminations; the
   148    144   \fB-errorcode\fR return option will contain additional information
   149    145   about the last abnormal termination encountered.
................................................................................
   161    157   is a newline then that character is normally deleted
   162    158   from the result or error message.
   163    159   This is consistent with other Tcl return values, which don't
   164    160   normally end with newlines.
   165    161   However, if \fB\-keepnewline\fR is specified then the trailing
   166    162   newline is retained.
   167    163   .PP
   168         -If standard input isn't redirected with
   169         -.QW < ,
   170         -.QW <<
   171         -or
   172         -.QW <@
   173         -then the standard input for the first command in the
          164  +If standard input isn't redirected with ``<'' or ``<<''
          165  +or ``<@'' then the standard input for the first command in the
   174    166   pipeline is taken from the application's current standard input.
   175    167   .PP
   176         -If the last \fIarg\fR is
   177         -.QW &
   178         -then the pipeline will be executed in background.
          168  +If the last \fIarg\fR is ``&'' then the pipeline will be
          169  +executed in background.
   179    170   In this case the \fBexec\fR command will return a list whose
   180    171   elements are the process identifiers for all of the subprocesses
   181    172   in the pipeline.
   182    173   The standard output from the last command in the pipeline will
   183    174   go to the application's standard output if it hasn't been
   184    175   redirected, and error output from all of
   185    176   the commands in the pipeline will go to the application's
................................................................................
   187    178   .PP
   188    179   The first word in each command is taken as the command name;
   189    180   tilde-substitution is performed on it, and if the result contains
   190    181   no slashes then the directories
   191    182   in the PATH environment variable are searched for
   192    183   an executable by the given name.
   193    184   If the name contains a slash then it must refer to an executable
   194         -reachable from the current directory. No
   195         -.QW glob
   196         -expansion or other shell-like substitutions
          185  +reachable from the current directory.
          186  +No ``glob'' expansion or other shell-like substitutions
   197    187   are performed on the arguments to commands.
   198    188   .SH "PORTABILITY ISSUES"
   199    189   .TP
   200    190   \fBWindows\fR (all versions)
   201    191   .
   202         -Reading from or writing to a socket, using the
   203         -.QW \[email protected]\0\fIfileId\fR
          192  +Reading from or writing to a socket, using the ``\[email protected]\0\fIfileId\fR''
   204    193   notation, does not work.  When reading from a socket, a 16-bit DOS
   205    194   application will hang and a 32-bit application will return immediately with
   206    195   end-of-file.  When either type of application writes to a socket, the
   207    196   information is instead sent to the console, if one is present, or is
   208    197   discarded.
   209    198   .RS
   210    199   .PP
................................................................................
   221    210   backslashes only in paths.  Any arguments to an application that specify a
   222    211   path name with forward slashes will not automatically be converted to use
   223    212   the backslash character.  If an argument contains forward slashes as the
   224    213   path separator, it may or may not be recognized as a path name, depending on
   225    214   the program.  
   226    215   .PP
   227    216   Additionally, when calling a 16-bit DOS or Windows 3.X application, all path
   228         -names must use the short, cryptic, path format (e.g., using
   229         -.QW applba~1.def
   230         -instead of
   231         -.QW applbakery.default ),
   232         -which can be obtained with the
          217  +names must use the short, cryptic, path format (e.g., using ``applba~1.def''
          218  +instead of ``applbakery.default''), which can be obtained with the
   233    219   \fBfile attributes $fileName -shortname\fR command.
   234    220   .PP
   235    221   Two or more forward or backward slashes in a row in a path refer to a
   236    222   network path.  For example, a simple concatenation of the root directory
   237    223   \fBc:/\fR with a subdirectory \fB/windows/system\fR will yield
   238    224   \fBc://windows/system\fR (two slashes together), which refers to the mount
   239    225   point called \fBsystem\fR on the machine called \fBwindows\fR (and the
................................................................................
   284    270   The Windows NT 16-bit system directory.
   285    271   .IP \(bu
   286    272   The Windows NT home directory.
   287    273   .IP \(bu
   288    274   The directories listed in the path.
   289    275   .PP
   290    276   In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
   291         -the caller must prepend the desired command with
   292         -.QW "\fBcmd.exe /c\0\fR"
          277  +the caller must prepend the desired command with ``\fBcmd.exe /c\0\fR''
   293    278   because built-in commands are not implemented using executables.
   294    279   .RE
   295    280   .TP
   296    281   \fBWindows 9x\fR
   297    282   .
   298    283   When attempting to execute an application, \fBexec\fR first searches for
   299    284   the name as it was specified.  Then, in order, \fB.com\fR, \fB.exe\fR, and
................................................................................
   310    295   The Windows 9x system directory.
   311    296   .IP \(bu
   312    297   The Windows 9x home directory.
   313    298   .IP \(bu
   314    299   The directories listed in the path.
   315    300   .PP
   316    301   In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
   317         -the caller must prepend the desired command with
   318         -.QW "\fBcommand.com /c\0\fR"
          302  +the caller must prepend the desired command with ``\fBcommand.com /c\0\fR''
   319    303   because built-in commands are not implemented using executables.
   320    304   .PP
   321    305   Once a 16-bit DOS application has read standard input from a console and 
   322    306   then quit, all subsequently run 16-bit DOS applications will see the 
   323    307   standard input as already closed.  32-bit applications do not have this
   324    308   problem and will run correctly, even after a 16-bit DOS application thinks 
   325    309   that standard input is closed.  There is no known workaround for this bug
   326    310   at this time.
   327    311   .PP
   328    312   Redirection between the \fBNUL:\fR device and a 16-bit application does not
   329    313   always work.  When redirecting from \fBNUL:\fR, some applications may hang,
   330         -others will get an infinite stream of
   331         -.QW 0x01
   332         -bytes, and some will actually
          314  +others will get an infinite stream of ``0x01'' bytes, and some will actually
   333    315   correctly get an immediate end-of-file; the behavior seems to depend upon 
   334    316   something compiled into the application itself.  When redirecting greater than
   335    317   4K or so to \fBNUL:\fR, some applications will hang.  The above problems do not
   336    318   happen with 32-bit applications.  
   337    319   .PP
   338    320   All DOS 16-bit applications are run synchronously.  All standard input from
   339    321   a pipe to a 16-bit DOS application is collected into a temporary file; the
................................................................................
   424    406   same name and be in the path. It can then happen that typing a command
   425    407   at the DOS prompt finds \fIa different program\fR than the same
   426    408   command run via \fBexec\fR. This is because of the (documented)
   427    409   differences in behaviour between \fBexec\fR and DOS batch files.
   428    410   .PP
   429    411   When in doubt, use the command \fBauto_execok\fR: it will return the
   430    412   complete path to the program as seen by the \fBexec\fR command.  This
   431         -applies especially when you want to run
   432         -.QW "internal"
   433         -commands like \fIdir\fR from a Tcl script (if you just want to list
   434         -filenames, use the \fBglob\fR command.)  To do that, use this:
          413  +applies especially when you want to run "internal" commands like
          414  +\fIdir\fR from a Tcl script (if you just want to list filenames, use
          415  +the \fBglob\fR command.)  To do that, use this:
   435    416   .CS
   436    417   \fBexec\fR {*}[auto_execok dir] *.tcl
   437    418   .CE
   438    419   .SH "SEE ALSO"
   439    420   error(n), open(n)
   440    421   .SH KEYWORDS
   441    422   execute, pipeline, redirection, subprocess

Changes to doc/expr.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-2000 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2005 by Kevin B. Kenny <[email protected]>. All rights reserved
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: expr.n,v 1.26 2007/10/25 09:35:14 dkf Exp $
            9  +'\" RCS: @(#) $Id: expr.n,v 1.27 2007/10/26 20:11:52 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH expr n 8.5 Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   expr \- Evaluate an expression
................................................................................
   103    103   .PP
   104    104   For some examples of simple expressions, suppose the variable
   105    105   \fBa\fR has the value 3 and
   106    106   the variable \fBb\fR has the value 6.
   107    107   Then the command on the left side of each of the lines below
   108    108   will produce the value on the right side of the line:
   109    109   .CS
   110         -.ta 3.5i
   111         -\fBexpr\fR 3.1 + $a	\fB\(-> \fI6.1\fR
   112         -\fBexpr\fR 2 + "$a.$b"	\fB\(-> \fI5.6\fR
   113         -\fBexpr\fR 4*[llength "6 2"]	\fB\(-> \fI8\fR
   114         -\fBexpr\fR {{word one} < "word $a"}	\fB\(-> \fI0\fR
          110  +.ta 6c
          111  +\fBexpr\fR 3.1 + $a	\fI6.1\fR
          112  +\fBexpr\fR 2 + "$a.$b"	\fI5.6\fR
          113  +\fBexpr\fR 4*[llength "6 2"]	\fI8\fR
          114  +\fBexpr\fR {{word one} < "word $a"}	\fI0\fR
   115    115   .CE
   116    116   .SS OPERATORS
   117    117   .PP
   118    118   The valid operators are listed below, grouped in decreasing order
   119    119   of precedence:
   120    120   .TP 20
   121    121   \fB\-\0\0+\0\0~\0\0!\fR
................................................................................
   199    199   All of the binary operators group left-to-right within the same
   200    200   precedence level.  For example, the command
   201    201   .CS
   202    202   \fBexpr\fR {4*2 < 7}
   203    203   .CE
   204    204   returns 0.
   205    205   .PP
   206         -The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have
   207         -.QW "lazy evaluation" ,
   208         -just as in C, which means that operands are not evaluated if they are
          206  +The \fB&&\fR, \fB||\fR, and \fB?:\fR operators have ``lazy
          207  +evaluation'', just as in C, 
          208  +which means that operands are not evaluated if they are
   209    209   not needed to determine the outcome.  For example, in the command
   210    210   .CS
   211    211   \fBexpr {$v ? [a] : [b]}\fR
   212    212   .CE
   213    213   only one of \fB[a]\fR or \fB[b]\fR will actually be evaluated,
   214    214   depending on the value of \fB$v\fR.  Note, however, that this is
   215    215   only true if the entire expression is enclosed in braces;  otherwise
................................................................................
   269    269   \fBexpr\fR {5 / 4}
   270    270   .CE
   271    271   returns 1, while
   272    272   .CS
   273    273   \fBexpr\fR {5 / 4.0}
   274    274   \fBexpr\fR {5 / ( [string length "abcd"] + 0.0 )}
   275    275   .CE
   276         -both return 1.25. Floating-point values are always returned with a
   277         -.QW \fB.\fR
          276  +both return 1.25.
          277  +Floating-point values are always returned with a ``\fB.\fR''
   278    278   or an \fBe\fR so that they will not look like integer values.  For
   279    279   example,
   280    280   .CS
   281    281   \fBexpr\fR {20.0/5.0}
   282    282   .CE
   283    283   returns \fB4.0\fR, not \fB4\fR.
   284    284   .SS "STRING OPERATIONS"
................................................................................
   334    334   the bytecode compiler must emit
   335    335   additional instructions to handle this situation.
   336    336   The most expensive code is required for
   337    337   unbraced expressions that contain command substitutions.
   338    338   These expressions must be implemented by generating new code
   339    339   each time the expression is executed.
   340    340   .SH EXAMPLES
   341         -Define a procedure that computes an
   342         -.QW "interesting"
   343         -mathematical function:
          341  +Define a procedure that computes an "interesting" mathematical
          342  +function:
   344    343   .CS
   345    344   proc tcl::mathfunc::calc {x y} {
   346    345       \fBexpr\fR { ($x**2 - $y**2) / exp($x**2 + $y**2) }
   347    346   }
   348    347   .CE
   349    348   .PP
   350    349   Convert polar coordinates into cartesian coordinates:
................................................................................
   376    375   }]
   377    376   .CE
   378    377   .PP
   379    378   Generate a random integer in the range 0..99 inclusive:
   380    379   .CS
   381    380   set randNum [\fBexpr\fR { int(100 * rand()) }]
   382    381   .CE
          382  +
   383    383   .SH "SEE ALSO"
   384         -array(n), for(n), if(n), mathfunc(n), namespace(n), proc(n), string(n),
   385         -Tcl(n), while(n)
          384  +array(n), for(n), if(n), mathfunc(n), namespace(n), proc(n), string(n), Tcl(n), while(n)
          385  +
   386    386   .SH KEYWORDS
   387    387   arithmetic, boolean, compare, expression, fuzzy comparison
          388  +
   388    389   .SH COPYRIGHT
   389         -.nf
   390         -Copyright \(co 1993 The Regents of the University of California.
   391         -Copyright \(co 1994-2000 Sun Microsystems Incorporated.
   392         -Copyright \(co 2005 by Kevin B. Kenny. All rights reserved.
   393         -.fi
          390  +Copyright (c) 1993 The Regents of the University of California.
          391  +.br
          392  +Copyright (c) 1994-2000 Sun Microsystems Incorporated.
          393  +.br
          394  +Copyright (c) 2005 by Kevin B. Kenny <[email protected]>. All rights reserved.

Changes to doc/fcopy.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: fcopy.n,v 1.13 2007/10/25 14:07:32 dkf Exp $
            8  +'\" RCS: @(#) $Id: fcopy.n,v 1.14 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH fcopy n 8.0 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   fcopy \- Copy data from one channel to another
................................................................................
    55     55   and the command callback is \fInot\fR made.
    56     56   If \fIinchan\fR is closed,
    57     57   then all data already queued for \fIoutchan\fR is written out.
    58     58   .PP
    59     59   Note that \fIinchan\fR can become readable during a background copy.
    60     60   You should turn off any \fBfileevent\fR handlers during a background
    61     61   copy so those handlers do not interfere with the copy.
    62         -Any I/O attempted by a \fBfileevent\fR handler will get a
    63         -.QW "channel busy"
    64         -error.
           62  +Any I/O attempted by a \fBfileevent\fR handler will get a "channel busy" error.
    65     63   .PP
    66     64   \fBFcopy\fR translates end-of-line sequences in \fIinchan\fR and \fIoutchan\fR
    67     65   according to the \fB\-translation\fR option
    68     66   for these channels.
    69     67   See the manual entry for \fBfconfigure\fR for details on the
    70     68   \fB\-translation\fR option.
    71     69   The translations mean that the number of bytes read from \fIinchan\fR
................................................................................
    76     74   .PP
    77     75   \fBFcopy\fR obeys the encodings and character translations configured
    78     76   for the channels. This
    79     77   means that the incoming characters are converted internally first
    80     78   UTF-8 and then into the encoding of the channel \fBfcopy\fR writes
    81     79   to. See the manual entry for \fBfconfigure\fR for details on the
    82     80   \fB\-encoding\fR and \fB\-translation\fR options. No conversion is
    83         -done if both channels are set to encoding
    84         -.QW "binary"
    85         -and have matching translations. If only the output channel is set to encoding
    86         -.QW "binary"
    87         -the system will write the internal UTF-8 representation of the incoming
    88         -characters. If only the input channel is set to encoding
    89         -.QW "binary"
    90         -the system will assume that the incoming bytes are valid UTF-8 characters and
    91         -convert them according to the output encoding. The behaviour of the system for
    92         -bytes which are not valid UTF-8 characters is undefined in this case.
           81  +done if both channels are
           82  +set to encoding "binary" and have matching translations. If only the
           83  +output channel is set to
           84  +encoding "binary" the system will write the internal UTF-8
           85  +representation of the incoming characters. If only the input channel
           86  +is set to encoding "binary" the system will assume that the incoming
           87  +bytes are valid UTF-8 characters and convert them according to the
           88  +output encoding. The behaviour of the system for bytes which are not
           89  +valid UTF-8 characters is undefined in this case.
           90  +
    93     91   .SH EXAMPLES
    94     92   .PP
    95     93   The first example transfers the contents of one channel exactly to
    96     94   another. Note that when copying one file to another, it is better to
    97     95   use \fBfile copy\fR which also copies file metadata (e.g. the file
    98     96   access permissions) where possible.
    99     97   .CS
................................................................................
   142    140   set out [socket $server $port]
   143    141   set chunk 1024
   144    142   set total 0
   145    143   \fBfcopy\fR $in $out -size $chunk \\
   146    144           -command [list CopyMore $in $out $chunk]
   147    145   vwait done
   148    146   .CE
          147  +
   149    148   .SH "SEE ALSO"
   150    149   eof(n), fblocked(n), fconfigure(n), file(n)
          150  +
   151    151   .SH KEYWORDS
   152    152   blocking, channel, end of line, end of file, nonblocking, read, translation

Changes to doc/file.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: file.n,v 1.46 2007/10/25 14:07:32 dkf Exp $
            8  +'\" RCS: @(#) $Id: file.n,v 1.47 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH file n 8.3 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   file \- Manipulate file names and attributes
................................................................................
    43     43   .RS
    44     44   This subcommand returns or sets platform specific values associated
    45     45   with a file. The first form returns a list of the platform specific
    46     46   flags and their values. The second form returns the value for the
    47     47   specific option. The third form sets one or more of the values. The
    48     48   values are as follows:
    49     49   .PP
    50         -On Unix, \fB\-group\fR gets or sets the group name for the file. A group id
    51         -can be given to the command, but it returns a group name. \fB\-owner\fR gets
           50  +On Unix, \fB-group\fR gets or sets the group name for the file. A group id
           51  +can be given to the command, but it returns a group name. \fB-owner\fR gets
    52     52   or sets the user name of the owner of the file. The command returns the
    53     53   owner name, but the numerical id can be passed when setting the
    54         -owner. \fB\-permissions\fR sets or retrieves the octal code that chmod(1)
           54  +owner. \fB-permissions\fR sets or retrieves the octal code that chmod(1)
    55     55   uses.  This command does also has limited support for setting using the
    56     56   symbolic attributes for chmod(1), of the form [ugo]?[[+\-=][rwxst],[...]],
    57     57   where multiple symbolic attributes can be separated by commas (example:
    58     58   \fBu+s,go\-rw\fR add sticky bit for user, remove read and write
    59     59   permissions for group and other).  A simplified \fBls\fR style string,
    60     60   of the form rwxrwxrwx (must be 9 characters), is also supported
    61     61   (example: \fBrwxr\-xr\-t\fR is equivalent to 01755).
    62         -On versions of Unix supporting file flags, \fB\-readonly\fR gives the
           62  +On versions of Unix supporting file flags, \fB-readonly\fR gives the
    63     63   value or sets or clears the readonly attribute of the file,
    64     64   i.e. the user immutable flag \fBuchg\fR to chflags(1).
    65     65   .PP
    66         -On Windows, \fB\-archive\fR gives the value or sets or clears the
    67         -archive attribute of the file. \fB\-hidden\fR gives the value or sets
    68         -or clears the hidden attribute of the file. \fB\-longname\fR will
           66  +On Windows, \fB-archive\fR gives the value or sets or clears the
           67  +archive attribute of the file. \fB-hidden\fR gives the value or sets
           68  +or clears the hidden attribute of the file. \fB-longname\fR will
    69     69   expand each path element to its long version. This attribute cannot be
    70         -set. \fB\-readonly\fR gives the value or sets or clears the readonly
    71         -attribute of the file. \fB\-shortname\fR gives a string where every
           70  +set. \fB-readonly\fR gives the value or sets or clears the readonly
           71  +attribute of the file. \fB-shortname\fR gives a string where every
    72     72   path element is replaced with its short (8.3) version of the
    73         -name. This attribute cannot be set. \fB\-system\fR gives or sets or
           73  +name. This attribute cannot be set. \fB-system\fR gives or sets or
    74     74   clears the value of the system attribute of the file.
    75     75   .PP
    76         -On Mac OS X and Darwin, \fB\-creator\fR gives or sets the
    77         -Finder creator type of the file. \fB\-hidden\fR gives or sets or clears
    78         -the hidden attribute of the file. \fB\-readonly\fR gives or sets or
    79         -clears the readonly attribute of the file. \fB\-rsrclength\fR gives
           76  +On Mac OS X and Darwin, \fB-creator\fR gives or sets the
           77  +Finder creator type of the file. \fB-hidden\fR gives or sets or clears
           78  +the hidden attribute of the file. \fB-readonly\fR gives or sets or
           79  +clears the readonly attribute of the file. \fB-rsrclength\fR gives
    80     80   the length of the resource fork of the file, this attribute can only be
    81     81   set to the value 0, which results in the resource fork being stripped
    82     82   off the file.
    83     83   .RE
    84     84   .TP
    85     85   \fBfile channels ?\fIpattern\fR?
    86     86   .
................................................................................
   118    118   argument.  Non-empty directories will be removed only if the
   119    119   \fB\-force\fR option is specified.  When operating on symbolic links,
   120    120   the links themselves will be deleted, not the objects they point to.
   121    121   Trying to delete a non-existent file is not considered an error.
   122    122   Trying to delete a read-only file will cause the file to be deleted,
   123    123   even if the \fB\-force\fR flags is not specified.  If the \fB\-force\fR
   124    124   option is specified on a directory, Tcl will attempt both to change
   125         -permissions and move the current directory
   126         -.QW pwd
   127         -out of the given path
          125  +permissions and move the current directory 'pwd' out of the given path
   128    126   if that is necessary to allow the deletion to proceed.  Arguments are
   129    127   processed in the order specified, halting at the first error, if any.
   130    128   A \fB\-\|\-\fR marks the end of switches; the argument following the
   131    129   \fB\-\|\-\fR will be treated as a \fIpathname\fR even if it starts with
   132    130   a \fB\-\fR.
   133    131   .TP
   134    132   \fBfile dirname \fIname\fR
   135    133   Returns a name comprised of all of the path components in \fIname\fR
   136    134   excluding the last element.  If \fIname\fR is a relative file name and
   137         -only contains one path element, then returns
   138         -.QW \fB.\fR .
   139         -If \fIname\fR refers to a root directory, then the root directory is
   140         -returned.  For example,
          135  +only contains one path element, then returns ``\fB.\fR''.  If \fIname\fR
          136  +refers to a root directory, then the root directory is returned.  For
          137  +example,
   141    138   .RS
   142    139   .CS
   143    140   \fBfile dirname c:/\fR
   144    141   .CE
   145    142   returns \fBc:/\fR. 
   146    143   .PP
   147    144   Note that tilde substitution will only be
................................................................................
   194    191   returns \fB/foo/bar\fR.
   195    192   .PP
   196    193   Note that any of the names can contain separators, and that the result
   197    194   is always canonical for the current platform: \fB/\fR for Unix and
   198    195   Windows.
   199    196   .RE
   200    197   .TP
   201         -\fBfile link ?\fI\-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
          198  +\fBfile link ?\fI-linktype\fR? \fIlinkName\fR ?\fItarget\fR?
   202    199   .
   203    200   If only one argument is given, that argument is assumed to be
   204    201   \fIlinkName\fR, and this command returns the value of the link given by
   205    202   \fIlinkName\fR (i.e. the name of the file it points to).  If
   206    203   \fIlinkName\fR isn't a link or its value cannot be read (as, for example,
   207    204   seems to be the case with hard links, which look just like ordinary
   208    205   files), then an error is returned.
................................................................................
   215    212   type of the link is platform-specific (on Unix a symbolic link will be
   216    213   the default).  This is useful for the case where the user wishes to
   217    214   create a link in a cross-platform way, and doesn't care what type of
   218    215   link is created.
   219    216   .
   220    217   If the user wishes to make a link of a specific type only, (and signal an
   221    218   error if for some reason that is not possible), then the optional
   222         -\fI\-linktype\fR argument should be given.  Accepted values for
   223         -\fI\-linktype\fR are
   224         -.QW "\-symbolic"
   225         -and
   226         -.QW "\-hard" .
          219  +\fI-linktype\fR argument should be given.  Accepted values for
          220  +\fI-linktype\fR are "-symbolic" and "-hard".
   227    221   .
   228    222   On Unix, symbolic links can be made to relative paths, and those paths
   229    223   must be relative to the actual \fIlinkName\fR's location (not to the
   230    224   cwd), but on all other platforms where relative links are not supported,
   231    225   target paths will always be converted to absolute, normalized form
   232    226   before the link is created (and therefore relative paths are interpreted
   233         -as relative to the cwd).  Furthermore,
   234         -.QW "~user"
   235         -paths are always expanded
          227  +as relative to the cwd).  Furthermore, "~user" paths are always expanded
   236    228   to absolute form.  When creating links on filesystems that either do not
   237    229   support any links, or do not support the specific type requested, an
   238    230   error message will be returned.  In particular Windows 95, 98 and ME do
   239    231   not support any links at present, but most Unix platforms support both
   240    232   symbolic and hard links (the latter for files only) and Windows
   241    233   NT/2000/XP (on NTFS drives) support symbolic
   242    234   directory links and hard file links.
................................................................................
   276    268   .TP
   277    269   \fBfile normalize \fIname\fR
   278    270   .
   279    271   .RS
   280    272   Returns a unique normalized path representation for the file-system
   281    273   object (file, directory, link, etc), whose string value can be used as a
   282    274   unique identifier for it.  A normalized path is an absolute path which has
   283         -all
   284         -.QW ../ ,
   285         -.QW ./
   286         -removed.  Also it is one which is in the
   287         -.QW standard
          275  +all '../', './' removed.  Also it is one which is in the ``standard''
   288    276   format for the native platform.  On Unix, this means the segments
   289    277   leading up to the path must be free of symbolic links/aliases (but the
   290    278   very last path component may be a symbolic link), and on Windows it also
   291    279   means we want the long form with that form's case-dependence (which
   292    280   gives us a unique, case-dependent path).  The one exception concerning the
   293    281   last link in the path is necessary, because Tcl or the user may wish to
   294         -operate on the actual symbolic link itself (for example \fBfile
   295         -delete\fR, \fBfile rename\fR, \fBfile copy\fR are defined to operate
   296         -on symbolic links, not on the things that they point to).
          282  +operate on the actual symbolic link itself (for example 'file delete', 'file
          283  +rename', 'file copy' are defined to operate on symbolic links, not on the
          284  +things that they point to).
   297    285   .RE
   298    286   .TP
   299    287   \fBfile owned \fIname\fR 
   300    288   .
   301    289   Returns \fB1\fR if file \fIname\fR is owned by the current user, \fB0\fR
   302    290   otherwise.
   303    291   .TP
................................................................................
   342    330   switches; the argument following the \fB\-\|\-\fR will be treated as a
   343    331   \fIsource\fR even if it starts with a \fB\-\fR.
   344    332   .RE
   345    333   .TP
   346    334   \fBfile rootname \fIname\fR
   347    335   .
   348    336   Returns all of the characters in \fIname\fR up to but not including the
   349         -last
   350         -.QW .
   351         -character in the last component of name.  If the last
          337  +last ``.'' character in the last component of name.  If the last
   352    338   component of \fIname\fR doesn't contain a dot, then returns \fIname\fR.
   353    339   .TP
   354    340   \fBfile separator\fR ?\fIname\fR?
   355    341   .
   356    342   If no argument is given, returns the character which is used to separate 
   357    343   path segments for native files on this platform.  If a path is given,
   358    344   the filesystem responsible for that path is asked to return its
................................................................................
   398    384   \fBfile system \fIname\fR
   399    385   .
   400    386   Returns a list of one or two elements, the first of which is the name of
   401    387   the filesystem to use for the file, and the second, if given, an
   402    388   arbitrary string representing the filesystem-specific nature or type of
   403    389   the location within that filesystem.  If a filesystem only supports one
   404    390   type of file, the second element may not be supplied.  For example the
   405         -native files have a first element
   406         -.QW native ,
   407         -and a second element which
          391  +native files have a first element 'native', and a second element which
   408    392   when given is a platform-specific type name for the file's system
   409         -(e.g.
   410         -.QW NTFS ,
   411         -.QW FAT ,
   412         -on Windows).  A generic virtual file system might return the list
   413         -.QW "vfs ftp"
   414         -to represent a file on a remote ftp site mounted as a virtual
   415         -filesystem through an extension called
   416         -.QW vfs .
   417         -If the file does not belong to any filesystem, an error is generated.
          393  +(e.g. 'NTFS', 'FAT', on Windows).  A generic virtual file system might return
          394  +the list 'vfs ftp' to represent a file on a remote ftp site mounted as a
          395  +virtual filesystem through an extension called 'vfs'.  If the file does
          396  +not belong to any filesystem, an error is generated.
   418    397   .TP
   419    398   \fBfile tail \fIname\fR
   420    399   .
   421    400   Returns all of the characters in the last filesystem component of
   422    401   \fIname\fR.  Any trailing directory separator in \fIname\fR is ignored.
   423    402   If \fIname\fR contains no separators then returns \fIname\fR.  So, 
   424    403   \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all
................................................................................
   428    407   .
   429    408   Returns a string giving the type of file \fIname\fR, which will be one of
   430    409   \fBfile\fR, \fBdirectory\fR, \fBcharacterSpecial\fR, \fBblockSpecial\fR,
   431    410   \fBfifo\fR, \fBlink\fR, or \fBsocket\fR.
   432    411   .TP
   433    412   \fBfile volumes\fR
   434    413   . 
   435         -Returns the absolute paths to the volumes mounted on the system, as a proper
   436         -Tcl list. Without any virtual filesystems mounted as root volumes, on UNIX,
   437         -the command will always return
   438         -.QW "/" ,
   439         -since all filesystems are locally mounted. On Windows, it will return a list
   440         -of the available local drives (e.g.
   441         -.QW "a:/ c:/" ).
   442         -If any virtual filesystem has mounted additional volumes, they will be in the
   443         -returned list.
          414  +Returns the absolute paths to the volumes mounted on the system, as a
          415  +proper Tcl list.  Without any virtual filesystems mounted as root
          416  +volumes, on UNIX, the command will always return "/", since all
          417  +filesystems are locally mounted.
          418  +On Windows, it will return a list of the available local drives
          419  +(e.g. {a:/ c:/}).  If any virtual filesystem has mounted additional
          420  +volumes, they will be in the returned list.
   444    421   .TP
   445    422   \fBfile writable \fIname\fR
   446    423   .
   447    424   Returns \fB1\fR if file \fIname\fR is writable by the current user,
   448    425   \fB0\fR otherwise.
   449    426   .SH "PORTABILITY ISSUES"
   450    427   .TP
................................................................................
   483    460   Rename a file and leave a symbolic link pointing from the old location
   484    461   to the new place:
   485    462   .CS
   486    463   set oldName foobar.txt
   487    464   set newName foo/bar.txt
   488    465   # Make sure that where we're going to move to exists...
   489    466   if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {
   490         -    \fBfile mkdir\fR [\fBfile dirname\fR $newName]
          467  +   \fBfile mkdir\fR [\fBfile dirname\fR $newName]
   491    468   }
   492    469   \fBfile rename\fR $oldName $newName
   493    470   \fBfile link\fR -symbolic $oldName $newName
   494    471   .CE
   495    472   
   496    473   .SH "SEE ALSO"
   497    474   chan(n), close(n), eof(n), fblocked(n), filename(n), flush(n), gets(n),
   498    475   open(n), seek(n), tell(n)
   499    476   .SH KEYWORDS
   500    477   attributes, copy files, delete files, directory, file, move files, name, rename files, stat

Changes to doc/fileevent.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: fileevent.n,v 1.10 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: fileevent.n,v 1.11 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH fileevent n 7.5 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   fileevent \- Execute a script when a channel becomes readable or writable
................................................................................
    26     26   is evaluated whenever the channel becomes readable or writable.  File event
    27     27   handlers are most commonly used to allow data to be received from another
    28     28   process on an event-driven basis, so that the receiver can continue to
    29     29   interact with the user while waiting for the data to arrive.  If an
    30     30   application invokes \fBgets\fR or \fBread\fR on a blocking channel when
    31     31   there is no input data available, the process will block; until the input
    32     32   data arrives, it will not be able to service other events, so it will
    33         -appear to the user to
    34         -.QW "freeze up" .
    35         -With \fBfileevent\fR, the process can
           33  +appear to the user to ``freeze up''.  With \fBfileevent\fR, the process can
    36     34   tell when data is present and only invoke \fBgets\fR or \fBread\fR when
    37     35   they won't block.
    38     36   .PP
    39     37   The \fIchannelId\fR argument to \fBfileevent\fR refers to an open
    40     38   channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR,
    41     39   or \fBstderr\fR), the return value from an invocation of \fBopen\fR
    42     40   or \fBsocket\fR, or the result of a channel creation command provided
................................................................................
   108    106       if {![eof $chan]} {
   109    107           puts [gets $chan]
   110    108       }
   111    109   }
   112    110   
   113    111   \fBfileevent\fR $chan readable [list GetData $chan]
   114    112   .CE
          113  +
   115    114   .SH CREDITS
   116    115   .PP
   117    116   \fBfileevent\fR is based on the \fBaddinput\fR command created
   118    117   by Mark Diekhans.
          118  +
   119    119   .SH "SEE ALSO"
   120    120   fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3)
          121  +
   121    122   .SH KEYWORDS
   122    123   asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
   123    124   script, writable.

Changes to doc/filename.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: filename.n,v 1.16 2007/10/25 14:07:32 dkf Exp $
            7  +'\" RCS: @(#) $Id: filename.n,v 1.17 2007/10/26 20:11:52 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH filename n 7.5 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   filename \- File name conventions supported by Tcl commands
................................................................................
   138    138   Tcl attempts to interpret that part of the path or otherwise access the
   139    139   file.  The behaviour of these paths when not trying to interpret them is
   140    140   the same as on Unix.  File names that have a tilde without a user name
   141    141   will be correctly substituted using the \fB$HOME\fR environment
   142    142   variable, just like for Unix.
   143    143   .SH "PORTABILITY ISSUES"
   144    144   .PP
   145         -Not all file systems are case sensitive, so scripts should avoid code that
   146         -depends on the case of characters in a file name. In addition, the character
   147         -sets allowed on different devices may differ, so scripts should choose file
   148         -names that do not contain special characters like: \fB<>:?"/\e|\fR.
   149         -.\"" Reset emacs highlighting
   150         -The safest approach is to use names consisting of alphanumeric characters
   151         -only. Care should be taken with filenames which contain spaces (common on
   152         -Windows systems) and filenames where the backslash is the directory separator
   153         -(Windows native path names). Also Windows 3.1 only supports file names with a
   154         -root of no more than 8 characters and an extension of no more than 3
   155         -characters.
          145  +Not all file systems are case sensitive, so scripts should avoid code
          146  +that depends on the case of characters in a file name.  In addition,
          147  +the character sets allowed on different devices may differ, so scripts
          148  +should choose file names that do not contain special characters like:
          149  +\fB<>:?"/\e|\fR.  The safest approach is to use names consisting of
          150  +alphanumeric characters only.  Care should be taken with filenames
          151  +which contain spaces (common on Windows systems) and
          152  +filenames where the backslash is the directory separator (Windows
          153  +native path names).  Also Windows 3.1 only supports file
          154  +names with a root of no more than 8 characters and an extension of no
          155  +more than 3 characters.
   156    156   .PP
   157         -On Windows platforms there are file and path length restrictions. Complete
   158         -paths or filenames longer than about 260 characters will lead to errors in
   159         -most file operations.
          157  +On Windows platforms there are file and path length restrictions. 
          158  +Complete paths or filenames longer than about 260 characters will lead
          159  +to errors in most file operations.
   160    160   .PP
   161         -Another Windows peculiarity is that any number of trailing dots
   162         -.QW "."
   163         -in filenames are totally ignored, so, for example, attempts to create a file
   164         -or directory with a name
   165         -.QW "foo."
   166         -will result in the creation of a file or directory with name
   167         -.QW "foo" .
   168         -This fact is reflected in the results of
   169         -.QW \fBfile normalize\fR .
   170         -Furthermore, a file name consisting only of dots
   171         -.QW "........."
   172         -or dots with trailing characters
   173         -.QW ".....abc"
   174         -is illegal.
          161  +Another Windows peculiarity is that any number of trailing dots '.'  in
          162  +filenames are totally ignored, so, for example, attempts to create a
          163  +file or directory with a name "foo." will result in the creation of a
          164  +file/directory with name "foo".  This fact is reflected in the
          165  +results of 'file normalize'.  Furthermore, a file name consisting only
          166  +of dots '.........' or dots with trailing characters '.....abc' is
          167  +illegal.
   175    168   .SH KEYWORDS
   176    169   current directory, absolute file name, relative file name,
   177    170   volume-relative file name, portability
   178    171   .SH "SEE ALSO"
   179    172   file(n), glob(n)

Changes to doc/for.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: for.n,v 1.6 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: for.n,v 1.7 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH for n "" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15         -for \- `For' loop
           15  +for \- ``For'' loop
    16     16   .SH SYNOPSIS
    17     17   \fBfor \fIstart test next body\fR
    18     18   .BE
    19     19   
    20     20   .SH DESCRIPTION
    21     21   .PP
    22     22   \fBFor\fR is a looping command, similar in structure to the C

Changes to doc/format.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: format.n,v 1.16 2007/10/25 14:07:32 dkf Exp $
            8  +'\" RCS: @(#) $Id: format.n,v 1.17 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH format n 8.1 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   format \- Format a string in the style of sprintf
................................................................................
    46     46   a set of flags, a minimum field width, a precision, a size modifier,
    47     47   and a conversion character.
    48     48   Any of these fields may be omitted except for the conversion character.
    49     49   The fields that are present must appear in the order given above.
    50     50   The paragraphs below discuss each of these fields in turn.
    51     51   .PP
    52     52   If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in
    53         -.QW \fB%2$d\fR ,
    54         -then the value to convert is not taken from the next sequential argument.
           53  +``\fB%2$d\fR'', then the value to convert is not taken from the
           54  +next sequential argument.
    55     55   Instead, it is taken from the argument indicated by the number,
    56     56   where 1 corresponds to the first \fIarg\fR.
    57     57   If the conversion specifier requires multiple arguments because
    58     58   of \fB*\fR characters in the specifier then
    59     59   successive arguments are used, starting with the argument
    60     60   given by the number.
    61     61   This follows the XPG3 conventions for positional specifiers.
................................................................................
   152    152   Convert integer to signed decimal string (equivalent to \fBd\fR).
   153    153   .TP 10
   154    154   \fBo\fR
   155    155   Convert integer to unsigned octal string.
   156    156   .TP 10
   157    157   \fBx\fR or \fBX\fR
   158    158   Convert integer to unsigned hexadecimal string, using digits
   159         -.QW 0123456789abcdef
   160         -for \fBx\fR and
   161         -.QW 0123456789ABCDEF
   162         -for \fBX\fR).
          159  +``0123456789abcdef'' for \fBx\fR and ``0123456789ABCDEF'' for \fBX\fR).
   163    160   .TP 10
   164    161   \fBc\fR
   165    162   Convert integer to the Unicode character it represents.
   166    163   .TP 10
   167    164   \fBs\fR
   168    165   No conversion; just insert string.
   169    166   .TP 10
................................................................................
   171    168   Convert number to signed decimal string of 
   172    169   the form \fIxx.yyy\fR, where the number of \fIy\fR's is determined by 
   173    170   the precision (default: 6).
   174    171   If the precision is 0 then no decimal point is output.
   175    172   .TP 10
   176    173   \fBe\fR or \fBE\fR
   177    174   Convert number to scientific notation in the 
   178         -form
   179         -.QW "\fIx.yyy\fBe\(+-\fIzz\fR" ,
   180         -where the number of \fIy\fR's is determined by the precision (default: 6).
          175  +form \fIx.yyy\fBe\(+-\fIzz\fR, where the number of \fIy\fR's is determined 
          176  +by the precision (default: 6).
   181    177   If the precision is 0 then no decimal point is output.
   182    178   If the \fBE\fR form is used then \fBE\fR is 
   183    179   printed instead of \fBe\fR.
   184    180   .TP 10
   185    181   \fBg\fR or \fBG\fR
   186    182   If the exponent is less than \-4 or greater than or equal to the 
   187    183   precision, then convert number as for \fB%e\fR or 

Changes to doc/glob.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: glob.n,v 1.19 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: glob.n,v 1.20 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH glob n 8.3 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   glob \- Return names of files that match patterns
    16     16   .SH SYNOPSIS
    17     17   \fBglob \fR?\fIswitches\fR? \fIpattern \fR?\fIpattern ...\fR?
    18     18   .BE
    19     19   
    20     20   .SH DESCRIPTION
    21     21   .PP
    22         -This command performs file name
    23         -.QW globbing
    24         -in a fashion similar to
           22  +This command performs file name ``globbing'' in a fashion similar to
    25     23   the csh shell.  It returns a list of the files whose names match any
    26     24   of the \fIpattern\fR arguments.  No particular order is guaranteed
    27     25   in the list, so if a sorted list is required the caller should use 
    28     26   \fBlsort\fR.
    29     27   .LP
    30     28   If the initial arguments to \fBglob\fR start with \fB\-\fR then
    31     29   they are treated as switches.  The following switches are
................................................................................
    99     97   The following are equivalent:
   100     98   .RS
   101     99   .CS
   102    100   \fBglob \-type d *\fR
   103    101   \fBglob */\fR
   104    102   .CE
   105    103   .RE
   106         -except that the first case doesn't return the trailing
   107         -.QW /
   108         -and is more platform independent.
          104  +except that the first case doesn't return the trailing ``/'' and
          105  +is more platform independent.
   109    106   .RE
   110    107   .TP
   111    108   \fB\-\|\-\fR
   112    109   Marks the end of switches.  The argument following this one will
   113    110   be treated as a \fIpattern\fR even if it starts with a \fB\-\fR.
   114    111   .PP
   115    112   The \fIpattern\fR arguments may contain any of the following
................................................................................
   128    125   .TP 10
   129    126   \fB\e\fIx\fR
   130    127   Matches the character \fIx\fR.
   131    128   .TP 10
   132    129   \fB{\fIa\fB,\fIb\fB,\fI...\fR}
   133    130   Matches any of the strings \fIa\fR, \fIb\fR, etc.
   134    131   .LP
   135         -On Unix, as with csh, a
   136         -.QW .
   137         -at the beginning of a file's name or just after a
   138         -.QW /
   139         -must be matched explicitly or with a {} construct, unless the
   140         -.QW "-types hidden"
   141         -flag is given (since
   142         -.QW .
   143         -at the beginning 
          132  +On Unix, as with csh, a ``.'' at the beginning of a file's name or just
          133  +after a ``/'' must be matched explicitly or with a {} construct,
          134  +unless the ``-types hidden'' flag is given (since ``.'' at the beginning 
   144    135   of a file's name indicates that it is hidden).  On other platforms,
   145         -files beginning with a
   146         -.QW .
   147         -are handled no differently to any others,
   148         -except the special directories
   149         -.QW .
   150         -and
   151         -.QW ..
   152         -which must be matched explicitly (this is to avoid a recursive pattern like
   153         -.QW "glob -join * * * *"
   154         -from recursing up the directory hierarchy as well as down). In addition, all
   155         -.QW /
   156         -characters must be matched explicitly.
          136  +files beginning with a ``.'' are handled no differently to any others,
          137  +except the special directories ``.'' and ``..'' which must be matched
          138  +explicitly (this is to avoid a recursive pattern like ``glob -join * *
          139  +* *'' from recursing up the directory hierarchy as well as down).
          140  +In addition, all ``/'' characters must be matched explicitly.
   157    141   .LP
   158         -If the first character in a \fIpattern\fR is
   159         -.QW ~
   160         -then it refers to the home directory for the user whose name follows the
   161         -.QW ~ .
   162         -If the
   163         -.QW ~
   164         -is followed immediately by
   165         -.QW /
   166         -then the value of the HOME environment variable is used.
          142  +If the first character in a \fIpattern\fR is ``~'' then it refers
          143  +to the home directory for the user whose name follows the ``~''.
          144  +If the ``~'' is followed immediately by ``/'' then the value of
          145  +the HOME environment variable is used.
   167    146   .LP
   168    147   The \fBglob\fR command differs from csh globbing in two ways.
   169    148   First, it does not sort its result list (use the \fBlsort\fR
   170    149   command if you want the list sorted).
   171    150   Second, \fBglob\fR only returns the names of files that actually
   172    151   exist;  in csh no check for existence is made unless a pattern
   173    152   contains a ?, *, or [] construct.
   174    153   .LP
   175    154   When the \fBglob\fR command returns relative paths whose filenames
   176         -start with a tilde
   177         -.QW ~
   178         -(for example through \fBglob *\fR or 
          155  +start with a tilde ``~'' (for example through \fBglob *\fR or 
   179    156   \fBglob -tails\fR, the returned list will not quote the tilde with
   180         -.QW ./ .
   181         -This means care must be taken if those names are later to
          157  +``./''.  This means care must be taken if those names are later to
   182    158   be used with \fBfile join\fR, to avoid them being interpreted as
   183    159   absolute paths pointing to a given user's home directory.
   184    160   .SH "PORTABILITY ISSUES"
   185         -.TP
          161  +.PP
   186    162   \fBWindows\fR
   187    163   .
   188    164   For Windows UNC names, the servername and sharename components of the path
   189    165   may not contain ?, *, or [] constructs.  On Windows NT, if \fIpattern\fR is
   190         -of the form
   191         -.QW \fB~\fIusername\[email protected]\fIdomain\fR
   192         -it refers to the home
          166  +of the form ``\fB~\fIusername\[email protected]\fIdomain\fR'' it refers to the home
   193    167   directory of the user whose account information resides on the specified NT
   194    168   domain server.  Otherwise, user account information is obtained from
   195    169   the local computer.  On Windows 95 and 98, \fBglob\fR accepts patterns
   196         -like
   197         -.QW .../
   198         -and
   199         -.QW ..../
   200         -for successively higher up parent directories.
   201         -.RS
   202         -.PP
          170  +like ``.../'' and ``..../'' for successively higher up parent directories.
          171  +
          172  +.
   203    173   Since the backslash character has a special meaning to the glob 
   204    174   command, glob patterns containing Windows style path separators need 
   205    175   special care. The pattern \fIC:\e\efoo\e\e*\fR is interpreted as 
   206    176   \fIC:\efoo\e*\fR where \fI\ef\fR will match the single character \fIf\fR 
   207    177   and \fI\e*\fR will match the single character \fI*\fR and will not be 
   208    178   interpreted as a wildcard character. One solution to this problem is 
   209    179   to use the Unix style forward slash as a path separator. Windows style 
................................................................................
   222    192   .CE
   223    193   .PP
   224    194   Find all subdirectories of the current directory:
   225    195   .CS
   226    196   \fBglob\fR \-type d *
   227    197   .CE
   228    198   .PP
   229         -Find all files whose name contains an
   230         -.QW a ,
   231         -a
   232         -.QW b
   233         -or the sequence
   234         -.QW cde :
          199  +Find all files whose name contains an "a", a "b" or the sequence "cde":
   235    200   .CS
   236    201   \fBglob\fR \-type f *{a,b,cde}*
   237    202   .CE
   238    203   
   239    204   .SH "SEE ALSO"
   240    205   file(n)
   241    206   
   242    207   .SH KEYWORDS
   243    208   exist, file, glob, pattern

Changes to doc/history.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: history.n,v 1.5 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: history.n,v 1.6 2007/10/26 20:11:52 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH history n "" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   history \- Manipulate the history list
................................................................................
    17     17   \fBhistory \fR?\fIoption\fR? ?\fIarg arg ...\fR?
    18     18   .BE
    19     19   
    20     20   .SH DESCRIPTION
    21     21   .PP
    22     22   The \fBhistory\fR command performs one of several operations related to
    23     23   recently-executed commands recorded in a history list.  Each of
    24         -these recorded commands is referred to as an
    25         -.QW event .
    26         -When specifying an event to the \fBhistory\fR command, the following
           24  +these recorded commands is referred to as an ``event''.  When
           25  +specifying an event to the \fBhistory\fR command, the following
    27     26   forms may be used:
    28     27   .IP [1]
    29     28   A number:  if positive, it refers to the event with
    30     29   that number (all events are numbered starting at 1).  If the number
    31     30   is negative, it selects an event relative to the current event
    32     31   (\fB\-1\fR refers to the previous event, \fB\-2\fR to the one before that, and
    33     32   so on).  Event \fB0\fR refers to the current event.
................................................................................
    89     88   .SH "HISTORY REVISION"
    90     89   .PP
    91     90   Pre-8.0 Tcl had a complex history revision mechanism.
    92     91   The current mechanism is more limited, and the old
    93     92   history operations \fBsubstitute\fR and \fBwords\fR have been removed.
    94     93   (As a consolation, the \fBclear\fR operation was added.)
    95     94   .PP
    96         -The history option \fBredo\fR results in much simpler
    97         -.QW "history revision" .
           95  +The history option \fBredo\fR results in much simpler ``history revision''.
    98     96   When this option is invoked then the most recent event
    99     97   is modified to eliminate the history command and replace it with
   100     98   the result of the history command.
   101     99   If you want to redo an event without modifying history, then use
   102    100   the \fBevent\fR operation to retrieve some event,
   103    101   and the \fBadd\fR operation to add it to history and execute it.
   104    102   
   105    103   .SH KEYWORDS
   106    104   event, history, record

Changes to doc/http.n.

     2      2   '\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
     3      3   '\" Copyright (c) 1998-2000 by Ajuba Solutions.
     4      4   '\" Copyright (c) 2004 ActiveState Corporation.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: http.n,v 1.26 2007/10/24 14:29:38 dkf Exp $
            9  +'\" RCS: @(#) $Id: http.n,v 1.27 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH "http" n 2.5 http "Tcl Bundled Packages"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   http \- Client-side implementation of the HTTP/1.0 protocol
................................................................................
    85     85   flags and values that define the configuration:
    86     86   .RS
    87     87   .TP
    88     88   \fB\-accept\fR \fImimetypes\fR
    89     89   The Accept header of the request.  The default is */*, which means that
    90     90   all types of documents are accepted.  Otherwise you can supply a 
    91     91   comma-separated list of mime type patterns that you are
    92         -willing to receive.  For example,
    93         -.QW "image/gif, image/jpeg, text/*" .
           92  +willing to receive.  For example, "image/gif, image/jpeg, text/*".
    94     93   .TP
    95     94   \fB\-proxyhost\fR \fIhostname\fR
    96     95   The name of the proxy host, if any.  If this value is the
    97     96   empty string, the URL host is contacted directly.
    98     97   .TP
    99     98   \fB\-proxyport\fR \fInumber\fR
   100     99   The proxy port number.
................................................................................
   117    116   returned by specifying the empty string (\fB{}\fR), although
   118    117   \fIiso8859-1\fR is recommended to restore similar behavior but without the
   119    118   \fB::http::formatQuery\fR throwing an error processing non-latin-1
   120    119   characters.
   121    120   .TP
   122    121   \fB\-useragent\fR \fIstring\fR
   123    122   The value of the User-Agent header in the HTTP request.  The default
   124         -is
   125         -.QW "\fBTcl http client package 2.5\fR" .
          123  +is \fB"Tcl http client package 2.4."\fR
   126    124   .RE
   127    125   .TP
   128    126   \fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR? 
   129    127   The \fB::http::geturl\fR command is the main procedure in the package.
   130    128   The \fB\-query\fR option causes a POST operation and
   131    129   the \fB\-validate\fR option causes a HEAD operation;
   132    130   otherwise, a GET operation is performed.  The \fB::http::geturl\fR command
................................................................................
   338    336   set token [::http::geturl https://my.secure.site/]
   339    337   .CE
   340    338   .RE
   341    339   .TP
   342    340   \fB::http::unregister\fR \fIproto\fR
   343    341   This procedure unregisters a protocol handler that was previously
   344    342   registered via \fB::http::register\fR.
          343  +
   345    344   .SH "ERRORS"
   346    345   The \fB::http::geturl\fR procedure will raise errors in the following cases:
   347    346   invalid command line options,
   348    347   an invalid URL,
   349    348   a URL on a non-existent host,
   350    349   or a URL at a bad port on an existing host.
   351    350   These errors mean that it
................................................................................
   382    381   These are described below.
   383    382   .TP
   384    383   ok
   385    384   If the HTTP transaction completes entirely, then status will be \fBok\fR.
   386    385   However, you should still check the \fB::http::code\fR value to get
   387    386   the HTTP status.  The \fB::http::ncode\fR procedure provides just
   388    387   the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fR
   389         -procedure returns a value like
   390         -.QW "HTTP 404 File not found" .
          388  +procedure returns a value like "HTTP 404 File not found".
   391    389   .TP
   392    390   eof
   393    391   If the server closes the socket without replying, then no error
   394    392   is raised, but the status of the transaction will be \fBeof\fR.
   395    393   .TP
   396    394   error
   397    395   The error message will also be stored in the \fBerror\fR status
................................................................................
   402    400   responds and closes the socket.
   403    401   The error message is saved in the \fBposterror\fR status array
   404    402   element and then  \fB::http::geturl\fR attempts to complete the
   405    403   transaction.
   406    404   If it can read the server's response
   407    405   it will end up with an \fBok\fR status, otherwise it will have
   408    406   an \fBeof\fR status.
          407  +
   409    408   .SH "STATE ARRAY"
   410    409   The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to
   411    410   get to the state of the HTTP transaction in the form of a Tcl array.
   412    411   Use this construct to create an easy-to-use array variable:
   413    412   .CS
   414    413   upvar #0 $token state
   415    414   .CE
................................................................................
   531    530      return $token
   532    531   }
   533    532   proc httpCopyProgress {args} {
   534    533      puts -nonewline stderr .
   535    534      flush stderr
   536    535   }
   537    536   .CE
          537  +
   538    538   .SH "SEE ALSO"
   539    539   safe(n), socket(n), safesock(n)
          540  +
   540    541   .SH KEYWORDS
   541    542   security policy, socket

Changes to doc/if.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: if.n,v 1.6 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: if.n,v 1.7 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH if n "" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   if \- Execute scripts conditionally
................................................................................
    28     28   if it is true then \fIbody1\fR is executed by passing it to the
    29     29   Tcl interpreter.
    30     30   Otherwise \fIexpr2\fR is evaluated as an expression and if it is true
    31     31   then \fBbody2\fR is executed, and so on.
    32     32   If none of the expressions evaluates to true then \fIbodyN\fR is
    33     33   executed.
    34     34   The \fBthen\fR and \fBelse\fR arguments are optional
    35         -.QW noise words
    36         -to make the command easier to read.
           35  +``noise words'' to make the command easier to read.
    37     36   There may be any number of \fBelseif\fR clauses, including zero.
    38     37   \fIBodyN\fR may also be omitted as long as \fBelse\fR is omitted too.
    39     38   The return value from the command is the result of the body script
    40     39   that was executed, or an empty string
    41     40   if none of the expressions was non-zero and there was no \fIbodyN\fR.
    42     41   .SH EXAMPLES
    43     42   A simple conditional:

Changes to doc/info.n.

     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 1993-1997 Bell Labs Innovations for Lucent Technologies
     5      5   '\" Copyright (c) 1998-2000 Ajuba Solutions
     6      6   '\"
     7      7   '\" See the file "license.terms" for information on usage and redistribution
     8      8   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     9      9   '\" 
    10         -'\" RCS: @(#) $Id: info.n,v 1.20 2007/10/25 14:07:32 dkf Exp $
           10  +'\" RCS: @(#) $Id: info.n,v 1.21 2007/10/26 20:11:53 dgp Exp $
    11     11   '\" 
    12     12   .so man.macros
    13     13   .TH info n 8.4 Tcl "Tcl Built-In Commands"
    14     14   .BS
    15     15   '\" Note:  do not modify the .SH NAME line immediately below!
    16     16   .SH NAME
    17     17   info \- Return information about the state of the Tcl interpreter
................................................................................
    19     19   \fBinfo \fIoption \fR?\fIarg arg ...\fR?
    20     20   .BE
    21     21   
    22     22   .SH DESCRIPTION
    23     23   .PP
    24     24   This command provides information about various internals of the Tcl
    25     25   interpreter.
    26         -The legal \fIoption\fRs (which may be abbreviated) are:
           26  +The legal \fIoption\fR's (which may be abbreviated) are:
    27     27   .TP
    28     28   \fBinfo args \fIprocname\fR
    29     29   Returns a list containing the names of the arguments to procedure
    30     30   \fIprocname\fR, in order.  \fIProcname\fR must be the name of a
    31     31   Tcl command procedure.
    32     32   .TP
    33     33   \fBinfo body \fIprocname\fR
................................................................................
    94     94   If \fInumber\fR is positive (> 0) then it selects a particular stack
    95     95   level (1 refers to the top-most active command, i.e., \fBinfo frame\fR
    96     96   itself, 2 to the command it was called from, and so on); otherwise it
    97     97   gives a level relative to the current command (0 refers to the current
    98     98   command, i.e., \fBinfo frame\fR itself, -1 to its caller, and so on).
    99     99   .sp
   100    100   This is similar to how \fBinfo level\fR works, except that this
   101         -subcommand reports all frames, like \fBsource\fRd scripts,
   102         -\fBeval\fRs, \fBuplevel\fRs, etc.
          101  +subcommand reports all frames, like \fBsource\fR'd scripts,
          102  +\fBeval\fR's, \fBuplevel\fR's, etc.
   103    103   .sp
   104         -Note that for nested commands, like
   105         -.QW "foo [[bar [[x]]]]"
   106         -only
   107         -.QW "x"
   108         -will be seen by an \fBinfo frame\fR invoked within
   109         -.QW "x" .
   110         -This is the same as for \fBinfo level\fR and error stack traces.
          104  +Note that for nested commands, like "foo [[bar [[x]]]]" only "x" will
          105  +be seen by an \fBinfo frame\fR invoked within "x". This is the same as
          106  +for \fBinfo level\fR and error stack traces.
   111    107   .sp
   112    108   The result dictionary may contain the keys listed below, with the
   113    109   specified meanings for their values:
   114    110   .RS
   115    111   .TP
   116    112   \fItype\fR
   117    113   This entry is always present and describes the nature of the location
................................................................................
   313    309   using a sequence of namespace names separated by double colons (\fB::\fR),
   314    310   and may have pattern matching special characters
   315    311   at the end to specify a set of variables in that namespace.
   316    312   If \fIpattern\fR is a qualified name,
   317    313   the resulting list of variable names
   318    314   has each matching namespace variable qualified with the name
   319    315   of its namespace.
   320         -Note that a currently-visible variable may not yet
   321         -.QW "exist"
   322         -if it has not
          316  +Note that a currently-visible variable may not yet "exist" if it has not
   323    317   been set (e.g. a variable declared but not set by \fBvariable\fR).
   324    318   .SH EXAMPLE
   325    319   This command prints out a procedure suitable for saving in a Tcl
   326    320   script:
   327    321   .PP
   328    322   .CS
   329    323   proc printProc {procName} {

Changes to doc/interp.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
     3      3   '\" Copyright (c) 2004 Donal K. Fellows
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: interp.n,v 1.30 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: interp.n,v 1.31 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH interp n 7.6 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   interp \- Create and manipulate Tcl interpreters
................................................................................
   103    103   This command creates an alias between one slave and another (see the
   104    104   \fBalias\fR slave command below for creating aliases between a slave
   105    105   and its master).  In this command, either of the slave interpreters
   106    106   may be anywhere in the hierarchy of interpreters under the interpreter
   107    107   invoking the command.
   108    108   \fISrcPath\fR and \fIsrcCmd\fR identify the source of the alias.
   109    109   \fISrcPath\fR is a Tcl list whose elements select a particular
   110         -interpreter.  For example,
   111         -.QW "\fBa b\fR"
   112         -identifies an interpreter
          110  +interpreter.  For example, ``\fBa b\fR'' identifies an interpreter
   113    111   \fBb\fR, which is a slave of interpreter \fBa\fR, which is a slave
   114    112   of the invoking interpreter.  An empty list specifies the interpreter
   115    113   invoking the command.  \fIsrcCmd\fR gives the name of a new
   116    114   command, which will be created in the source interpreter.
   117    115   \fITargetPath\fR and \fItargetCmd\fR specify a target interpreter
   118    116   and command, and the \fIarg\fR arguments, if any, specify additional
   119    117   arguments to \fItargetCmd\fR which are prepended to any arguments specified
................................................................................
   566    564   When the source for an alias is invoked in the slave interpreter, the
   567    565   usual Tcl substitutions are performed when parsing that command.
   568    566   These substitutions are carried out in the source interpreter just
   569    567   as they would be for any other command invoked in that interpreter.
   570    568   The command procedure for the source command takes its arguments
   571    569   and merges them with the \fItargetCmd\fR and \fIarg\fRs for the
   572    570   alias to create a new array of arguments.  If the words
   573         -of \fIsrcCmd\fR were
   574         -.QW "\fIsrcCmd arg1 arg2 ... argN\fR" ,
          571  +of \fIsrcCmd\fR were ``\fIsrcCmd arg1 arg2 ... argN\fR'',
   575    572   the new set of words will be
   576         -.QW "\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR" ,
          573  +``\fItargetCmd arg arg ... arg arg1 arg2 ... argN\fR'',
   577    574   where \fItargetCmd\fR and \fIarg\fRs are the values supplied when the
   578    575   alias was created.  \fITargetCmd\fR is then used to locate a command
   579    576   procedure in the target interpreter, and that command procedure
   580    577   is invoked with the new set of arguments.  An error occurs if
   581    578   there is no command named \fItargetCmd\fR in the target interpreter.
   582    579   No additional substitutions are performed on the words:  the
   583    580   target command procedure is invoked directly, without

Changes to doc/join.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: join.n,v 1.6 2007/10/25 09:25:27 dkf Exp $
            8  +'\" RCS: @(#) $Id: join.n,v 1.7 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH join n "" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   join \- Create a string by joining together list elements
    16     16   .SH SYNOPSIS
    17     17   \fBjoin \fIlist \fR?\fIjoinString\fR?
    18     18   .BE
           19  +
    19     20   .SH DESCRIPTION
    20     21   .PP
    21     22   The \fIlist\fR argument must be a valid Tcl list.
    22     23   This command returns the string
    23     24   formed by joining all of the elements of \fIlist\fR together with
    24     25   \fIjoinString\fR separating each adjacent pair of elements.
    25     26   The \fIjoinString\fR argument defaults to a space character.
    26     27   .SH EXAMPLES
    27     28   Making a comma-separated list:
    28     29   .CS
    29         -.ta 2i
    30     30   set data {1 2 3 4 5}
    31     31   \fBjoin\fR $data ", "
    32         -	 \fB\(->\fI 1, 2, 3, 4, 5\fR
           32  +     \fB=> 1, 2, 3, 4, 5\fR
    33     33   .CE
    34     34   .PP
    35     35   Using \fBjoin\fR to flatten a list by a single level:
    36     36   .CS
    37         -.ta 2i
    38     37   set data {1 {2 3} 4 {5 {6 7} 8}}
    39     38   \fBjoin\fR $data
    40         -	 \fB\(->\fI 1 2 3 4 5 {6 7} 8\fR
           39  +     \fB=> 1 2 3 4 5 {6 7} 8\fR
    41     40   .CE
           41  +
    42     42   .SH "SEE ALSO"
    43     43   list(n), lappend(n), split(n)
           44  +
    44     45   .SH KEYWORDS
    45     46   element, join, list, separator

Changes to doc/lappend.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: lappend.n,v 1.12 2007/10/24 14:29:38 dkf Exp $
            9  +'\" RCS: @(#) $Id: lappend.n,v 1.13 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH lappend n "" Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   lappend \- Append list elements onto a variable
................................................................................
    24     24   and appends each of the \fIvalue\fR arguments to that list as a separate
    25     25   element, with spaces between elements.
    26     26   If \fIvarName\fR doesn't exist, it is created as a list with elements
    27     27   given by the \fIvalue\fR arguments.
    28     28   \fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs
    29     29   are appended as list elements rather than raw text.
    30     30   This command provides a relatively efficient way to build up
    31         -large lists.  For example,
    32         -.QW "\fBlappend a $b\fR"
    33         -is much more efficient than
    34         -.QW "\fBset a [concat $a [list $b]]\fR" ,
    35         -especially when \fB$a\fR is long.
           31  +large lists.  For example, ``\fBlappend a $b\fR'' is much
           32  +more efficient than ``\fBset a [concat $a [list $b]]\fR'' when
           33  +\fB$a\fR is long.
    36     34   .SH EXAMPLE
    37     35   Using \fBlappend\fR to build up a list of numbers.
    38     36   .CS
    39     37   % set var 1
    40     38   1
    41     39   % \fBlappend\fR var 2
    42     40   1 2

Changes to doc/lassign.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1992-1999 Karl Lehenbauer & Mark Diekhans
     3      3   '\" Copyright (c) 2004 Donal K. Fellows
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: lassign.n,v 1.2 2007/10/25 09:31:52 dkf Exp $
            8  +'\" RCS: @(#) $Id: lassign.n,v 1.3 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH lassign n 8.5 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   lassign \- Assign list elements to variables
    16     16   .SH SYNOPSIS
    17     17   \fBlassign \fIlist varName \fR?\fIvarName ...\fR?
    18     18   .BE
           19  +
    19     20   .SH DESCRIPTION
    20     21   .PP
    21     22   This command treats the value \fIlist\fR as a list and assigns
    22     23   successive elements from that list to the variables given by the
    23     24   \fIvarName\fR arguments in order.  If there are more variable names
    24     25   than list elements, the remaining variables are set to the empty
    25     26   string.  If there are more list elements than variables, a list of
    26     27   unassigned elements is returned.
    27     28   .SH EXAMPLES
    28     29   An illustration of how multiple assignment works, and what happens
    29     30   when there are either too few or too many elements.
    30     31   .CS
    31         -.ta 2.5i
    32         -lassign {a b c} x y z	\fB\(->\fI Empty return\fR
    33         -puts $x	\fB\(->\fI Prints "a"\fR
    34         -puts $y	\fB\(->\fI Prints "b"\fR
    35         -puts $z	\fB\(->\fI Prints "c"\fR
           32  +lassign {a b c} x y z       ;# Empty return
           33  +puts $x                     ;# Prints "a"
           34  +puts $y                     ;# Prints "b"
           35  +puts $z                     ;# Prints "c"
    36     36   
    37         -lassign {d e} x y z	\fB\(->\fI Empty return\fR
    38         -puts $x	\fB\(->\fI Prints "d"\fR
    39         -puts $y	\fB\(->\fI Prints "e"\fR
    40         -puts $z	\fB\(->\fI Prints ""\fR
           37  +lassign {d e} x y z         ;# Empty return
           38  +puts $x                     ;# Prints "d"
           39  +puts $y                     ;# Prints "e"
           40  +puts $z                     ;# Prints ""
    41     41   
    42         -lassign {f g h i} x y	\fB\(->\fI Returns "h i"\fR
    43         -puts $x	\fB\(->\fI Prints "f"\fR
    44         -puts $y	\fB\(->\fI Prints "g"\fR
           42  +lassign {f g h i} x y       ;# Returns "h i"
           43  +puts $x                     ;# Prints "f"
           44  +puts $y                     ;# Prints "g"
    45     45   .CE
    46         -.PP
    47     46   The \fBlassign\fR command has other uses.  It can be used to create
    48         -the analogue of the
    49         -.QW shift
    50         -command in many shell languages like this:
           47  +the analogue of the "shift" command in many shell languages like this:
    51     48   .CS
    52     49   set ::argv [lassign $::argv argumentToReadOff]
    53     50   .CE
    54     51   .SH "SEE ALSO"
    55     52   lindex(n), list(n), lset(n), set(n)
           53  +
    56     54   .SH KEYWORDS
    57     55   assign, element, list, multiple, set, variable

Changes to doc/library.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1991-1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: library.n,v 1.19 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: library.n,v 1.20 2007/10/26 20:11:53 dgp Exp $
     9      9   .so man.macros
    10     10   .TH library n "8.0" Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   .SH NAME
    13     13   auto_execok, auto_import, auto_load, auto_mkindex, auto_mkindex_old, auto_qualify, auto_reset, tcl_findLibrary, parray, tcl_endOfWord, tcl_startOfNextWord, tcl_startOfPreviousWord, tcl_wordBreakAfter, tcl_wordBreakBefore \- standard library of Tcl procedures
    14     14   .SH SYNOPSIS
    15     15   .nf
................................................................................
    50     50   \fBsource [file join [info library] init.tcl]\fR
    51     51   .CE
    52     52   If the library procedure \fBTcl_Init\fR is invoked from an application's
    53     53   \fBTcl_AppInit\fR procedure, this happens automatically.
    54     54   The code in \fBinit.tcl\fR will define the \fBunknown\fR procedure
    55     55   and arrange for the other procedures to be loaded on-demand using
    56     56   the auto-load mechanism defined below.
           57  +
    57     58   .SH "COMMAND PROCEDURES"
    58     59   .PP
    59     60   The following procedures are provided in the Tcl library:
    60     61   .TP
    61     62   \fBauto_execok \fIcmd\fR
    62     63   Determines whether there is an executable file or shell builtin
    63     64   by the name \fIcmd\fR.  If so, it returns a list of arguments to be
................................................................................
   132    133   \fBAuto_mkindex_old\fR parses the Tcl scripts in a relatively
   133    134   unsophisticated way:  if any line contains the word \fBproc\fR
   134    135   as its first characters then it is assumed to be a procedure
   135    136   definition and the next word of the line is taken as the
   136    137   procedure's name.
   137    138   Procedure definitions that don't appear in this way (e.g. they
   138    139   have spaces before the \fBproc\fR) will not be indexed.  If your 
   139         -script contains
   140         -.QW dangerous
   141         -code, such as global initialization
          140  +script contains "dangerous" code, such as global initialization
   142    141   code or procedure names with special characters like \fB$\fR,
   143    142   \fB*\fR, \fB[\fR or \fB]\fR, you are safer using auto_mkindex_old.
   144    143   .RE
   145    144   .TP
   146    145   \fBauto_reset\fR
   147    146   Destroys all the information cached by \fBauto_execok\fR and
   148    147   \fBauto_load\fR.  This information will be re-read from disk the next
................................................................................
   171    170   .TP
   172    171   \fBtcl_findLibrary \fIbasename version patch initScript enVarName varName\fR
   173    172   This is a standard search procedure for use by extensions during
   174    173   their initialization.  They call this procedure to look for their
   175    174   script library in several standard directories.
   176    175   The last component of the name of the library directory is 
   177    176   normally \fIbasenameversion\fR
   178         -(e.g., tk8.0), but it might be
   179         -.QW library
   180         -when in the build hierarchies.
          177  +(e.g., tk8.0), but it might be "library" when in the build hierarchies.
   181    178   The \fIinitScript\fR file will be sourced into the interpreter
   182    179   once it is found.  The directory in which this file is found is
   183    180   stored into the global variable \fIvarName\fR.
   184    181   If this variable is already defined (e.g., by C code during
   185    182   application initialization) then no searching is done.
   186    183   Otherwise the search looks in these directories:
   187    184   the directory named by the environment variable \fIenVarName\fR;
................................................................................
   229    226   .TP
   230    227   \fBtcl_wordBreakBefore \fIstr start\fR
   231    228   Returns the index of the first word boundary before the starting index
   232    229   \fIstart\fR in the string \fIstr\fR.  Returns \-1 if there are no more
   233    230   boundaries before the starting point in the given string.  The index
   234    231   returned refers to the second character of the pair that comprises a
   235    232   boundary.
          233  +
   236    234   .SH "VARIABLES"
   237    235   .PP
   238    236   The following global variables are defined or used by the procedures in
   239    237   the Tcl library:
   240    238   .TP
   241    239   \fBauto_execs\fR
   242    240   Used by \fBauto_execok\fR to record information about whether
................................................................................
   269    267   assigned to the \fBtcl_library\fR variable and therefore returned by
   270    268   the command \fBinfo library\fR).  If this variable isn't set then
   271    269   a default value is used.
   272    270   .TP
   273    271   \fBenv(TCLLIBPATH)\fR
   274    272   If set, then it must contain a valid Tcl list giving directories to
   275    273   search during auto-load operations.  Directories must be specified in 
   276         -Tcl format, using
   277         -.QW /
   278         -as the path separator, regardless of platform.
          274  +Tcl format, using "/" as the path separator, regardless of platform.
   279    275   This variable is only used when initializing the \fBauto_path\fR variable.
   280    276   .TP
   281    277   \fBtcl_nonwordchars\fR
   282    278   This variable contains a regular expression that is used by routines
   283    279   like \fBtcl_endOfWord\fR to identify whether a character is part of a
   284    280   word or not.  If the pattern matches a character, the character is
   285    281   considered to be a non-word character.  On Windows platforms, spaces,
................................................................................
   290    286   \fBtcl_wordchars\fR
   291    287   This variable contains a regular expression that is used by routines
   292    288   like \fBtcl_endOfWord\fR to identify whether a character is part of a
   293    289   word or not.  If the pattern matches a character, the character is
   294    290   considered to be a word character.  On Windows platforms, words are
   295    291   comprised of any character that is not a space, tab, or newline.  Under
   296    292   Unix, words are comprised of numbers, letters or underscores.
          293  +
   297    294   .SH "SEE ALSO"
   298    295   info(n), re_syntax(n)
          296  +
   299    297   .SH KEYWORDS
   300    298   auto-exec, auto-load, library, unknown, word, whitespace 

Changes to doc/lindex.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2001 by Kevin B. Kenny.  All rights reserved.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: lindex.n,v 1.13 2007/10/25 09:25:27 dkf Exp $
            9  +'\" RCS: @(#) $Id: lindex.n,v 1.14 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH lindex n 8.4 Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   lindex \- Retrieve an element from a list
................................................................................
    63     63   lindex $a {1 2 3}
    64     64   .CE
    65     65   is synonymous with
    66     66   .CS
    67     67   lindex [lindex [lindex $a 1] 2] 3
    68     68   .CE
    69     69   .SH EXAMPLES
    70         -.PP
    71         -Demonstrating how the index list system works.
    72     70   .CS
    73         -.ta 5i
    74         -\fBlindex\fR {a b c}	 \fB\(->\fI a b c\fR
    75         -\fBlindex\fR {a b c} {}	 \fB\(->\fI a b c\fR
    76         -\fBlindex\fR {a b c} 0	 \fB\(->\fI a\fR
    77         -\fBlindex\fR {a b c} 2	 \fB\(->\fI c\fR
    78         -\fBlindex\fR {a b c} end	 \fB\(->\fI c\fR
    79         -\fBlindex\fR {a b c} end-1	 \fB\(->\fI b\fR
    80         -\fBlindex\fR {{a b c} {d e f} {g h i}} 2 1	 \fB\(->\fI h\fR
    81         -\fBlindex\fR {{a b c} {d e f} {g h i}} {2 1}	 \fB\(->\fI h\fR
    82         -\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0	 \fB\(->\fI g\fR
    83         -\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0}	 \fB\(->\fI g\fR
           71  +\fBlindex\fR {a b c}  \fI=> a b c\fR
           72  +\fBlindex\fR {a b c} {} \fI=> a b c\fR
           73  +\fBlindex\fR {a b c} 0 \fI=> a\fR
           74  +\fBlindex\fR {a b c} 2 \fI=> c\fR
           75  +\fBlindex\fR {a b c} end \fI=> c\fR
           76  +\fBlindex\fR {a b c} end-1 \fI=> b\fR
           77  +\fBlindex\fR {{a b c} {d e f} {g h i}} 2 1 \fI=> h\fR
           78  +\fBlindex\fR {{a b c} {d e f} {g h i}} {2 1} \fI=> h\fR
           79  +\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} 1 1 0 \fI=> g\fR
           80  +\fBlindex\fR {{{a b} {c d}} {{e f} {g h}}} {1 1 0} \fI=> g\fR
    84     81   .CE
    85     82   .SH "SEE ALSO"
    86     83   list(n), lappend(n), linsert(n), llength(n), lsearch(n), 
    87     84   lset(n), lsort(n), lrange(n), lreplace(n),
    88     85   .VS 8.5
    89     86   string(n)
    90     87   .VE
           88  +
    91     89   .SH KEYWORDS
    92     90   element, index, list

Changes to doc/llength.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: llength.n,v 1.11 2007/10/24 14:29:38 dkf Exp $
            9  +'\" RCS: @(#) $Id: llength.n,v 1.12 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH llength n "" Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   llength \- Count the number of elements in a list
    17     17   .SH SYNOPSIS
    18     18   \fBllength \fIlist\fR
    19     19   .BE
           20  +
    20     21   .SH DESCRIPTION
    21     22   .PP
    22     23   Treats \fIlist\fR as a list and returns a decimal string giving
    23     24   the number of elements in it.
           25  +
    24     26   .SH EXAMPLES
    25     27   The result is the number of elements:
    26     28   .CS
    27     29   % \fBllength\fR {a b c d e}
    28     30   5
    29     31   % \fBllength\fR {a b c}
    30     32   3
................................................................................
    42     44   .CE
    43     45   .PP
    44     46   An empty list is not necessarily an empty string:
    45     47   .CS
    46     48   % set var { }; puts "[string length $var],[\fBllength\fR $var]"
    47     49   1,0
    48     50   .CE
           51  +
    49     52   .SH "SEE ALSO"
    50     53   list(n), lappend(n), lindex(n), linsert(n), lsearch(n), 
    51     54   lset(n), lsort(n), lrange(n), lreplace(n)
           55  +
    52     56   .SH KEYWORDS
    53     57   element, list, length

Changes to doc/load.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: load.n,v 1.18 2007/10/24 14:29:38 dkf Exp $
            7  +'\" RCS: @(#) $Id: load.n,v 1.19 2007/10/26 20:11:53 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH load n 7.5 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   load \- Load machine code and initialize new commands
................................................................................
   106    106   package by that name, and uses it if it is found.  If several
   107    107   different files have been \fBload\fRed with different versions of
   108    108   the package, Tcl picks the file that was loaded first.
   109    109   .SH "PORTABILITY ISSUES"
   110    110   .TP
   111    111   \fBWindows\fR\0\0\0\0\0
   112    112   .
   113         -When a load fails with a
   114         -.QW "library not found"
   115         -error, it is also possible that a dependent library was not found.  To
   116         -see the dependent libraries, type
   117         -.QW "dumpbin -imports <dllname>"
   118         -in a DOS console to see what the library must import.
   119         -When loading a DLL in the current directory, Windows will ignore
   120         -.QW ./
   121         -as a path specifier and use a search heuristic to find the DLL instead.
          113  +When a load fails with "library not found" error, it is also possible
          114  +that a dependent library was not found.  To see the dependent libraries,
          115  +type ``dumpbin -imports <dllname>'' in a DOS console to see what the
          116  +library must import.
          117  +When loading a DLL in the current directory, Windows will ignore ``./'' as
          118  +a path specifier and use a search heuristic to find the DLL instead.
   122    119   To avoid this, load the DLL with:
   123    120   .CS
   124    121   \fBload\fR [file join [pwd] mylib.DLL]
   125    122   .CE
   126    123   .SH BUGS
   127    124   .PP
   128    125   If the same file is \fBload\fRed by different \fIfileName\fRs, it will

Changes to doc/lrange.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: lrange.n,v 1.13 2007/10/24 14:29:38 dkf Exp $
            9  +'\" RCS: @(#) $Id: lrange.n,v 1.14 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH lrange n 7.4 Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   lrange \- Return one or more adjacent elements from a list
................................................................................
    30     30   end of the list.
    31     31   .VE
    32     32   If \fIfirst\fR is less than zero, it is treated as if it were zero.
    33     33   If \fIlast\fR is greater than or equal to the number of elements
    34     34   in the list, then it is treated as if it were \fBend\fR.
    35     35   If \fIfirst\fR is greater than \fIlast\fR then an empty string
    36     36   is returned.
    37         -Note:
    38         -.QW "\fBlrange \fIlist first first\fR"
    39         -does not always produce the same result as
    40         -.QW "\fBlindex \fIlist first\fR"
    41         -(although it often does
           37  +Note: ``\fBlrange \fIlist first first\fR'' does not always produce the
           38  +same result as ``\fBlindex \fIlist first\fR'' (although it often does
    42     39   for simple fields that aren't enclosed in braces); it does, however,
    43         -produce exactly the same results as
    44         -.QW "\fBlist [lindex \fIlist first\fB]\fR" .
           40  +produce exactly the same results as ``\fBlist [lindex \fIlist first\fB]\fR''
    45     41   .SH EXAMPLES
    46     42   Selecting the first two elements:
    47     43   .CS
    48     44   % \fBlrange\fR {a b c d e} 0 1
    49     45   a b
    50     46   .CE
    51     47   .PP

Changes to doc/lrepeat.n.

     1      1   '\"
     2      2   '\" Copyright (c) 2003 by Simon Geard.  All rights reserved.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: lrepeat.n,v 1.3 2007/10/25 09:25:27 dkf Exp $
            7  +'\" RCS: @(#) $Id: lrepeat.n,v 1.4 2007/10/26 20:11:53 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH lrepeat n 8.5 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   lrepeat \- Build a list by repeating elements
    15     15   .SH SYNOPSIS
    16     16   \fBlrepeat \fInumber element1 \fR?\fIelement2 element3 ...\fR?
    17     17   .BE
    18     18   .SH DESCRIPTION
    19     19   .PP
    20         -The \fBlrepeat\fR command creates a list of size \fInumber\fR \(mu \fInumber
    21         -of elements\fR by repeating \fInumber\fR times the sequence of elements
    22         -\fIelement1 element2 ...\fR. The \fInumber\fR must be a positive integer, and
    23         -each \fIelementN\fR can be any Tcl value.
    24         -.PP
    25         -Note that
    26         -.QW "\fBlrepeat 1 arg ...\fR"
    27         -is identical to
    28         -.QW "\fBlist arg ...\fR" ,
    29         -though the \fIarg\fR is required with \fBlrepeat\fR.
           20  +The \fBlrepeat\fR command creates a list of size \fInumber * number of
           21  +elements\fR by repeating \fInumber\fR times the sequence of elements
           22  +\fIelement1 element2 ...\fR.  \fInumber\fR must be a positive integer,
           23  +\fIelementn\fR can be any Tcl value.  Note that \fBlrepeat 1 arg ...\fR
           24  +is identical to \fBlist arg ...\fR, though the \fIarg\fR is required
           25  +with \fBlrepeat\fR.
    30     26   .SH EXAMPLES
    31     27   .CS
    32         -.ta 3i
    33         -lrepeat 3 a	\fB\(->\fI a a a\fR
    34         -lrepeat 3 [lrepeat 3 0]	\fB\(->\fI {0 0 0} {0 0 0} {0 0 0}\fR
    35         -lrepeat 3 a b c	\fB\(->\fI a b c a b c a b c\fR
    36         -lrepeat 3 [lrepeat 2 a] b c	\fB\(->\fI {a a} b c {a a} b c {a a} b c\fR
           28  +lrepeat 3 a  => a a a
           29  +lrepeat 3 [lrepeat 3 0] => {0 0 0} {0 0 0} {0 0 0}
           30  +lrepeat 3 a b c => a b c a b c a b c
           31  +lrepeat 3 [lrepeat 2 a] b c => {a a} b c {a a} b c {a a} b c
    37     32   .CE
    38     33   .SH "SEE ALSO"
    39     34   list(n), lappend(n), linsert(n), llength(n), lset(n)
    40     35   
    41     36   .SH KEYWORDS
    42     37   element, index, list

Changes to doc/lreplace.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: lreplace.n,v 1.14 2007/10/24 14:29:38 dkf Exp $
            9  +'\" RCS: @(#) $Id: lreplace.n,v 1.15 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   lreplace \- Replace elements in a list with new elements
    17     17   .SH SYNOPSIS
    18     18   \fBlreplace \fIlist first last \fR?\fIelement element ...\fR?
    19     19   .BE
           20  +
    20     21   .SH DESCRIPTION
    21     22   .PP
    22     23   \fBlreplace\fR returns a new list formed by replacing one or more elements of
    23     24   \fIlist\fR with the \fIelement\fR arguments.
    24     25   .VS 8.5
    25     26   \fIfirst\fR and \fIlast\fR are index values specifying the first and
    26     27   last elements of the range to replace.  
................................................................................
    28     29   the same as index values for the command \fBstring index\fR,
    29     30   supporting simple index arithmetic and indices relative to the
    30     31   end of the list.
    31     32   0 refers to the first element of the
    32     33   list, and \fBend\fR refers to the last element of the list.
    33     34   If \fIlist\fR is empty, then \fIfirst\fR and \fIlast\fR are ignored.
    34     35   .VE
    35         -.PP
           36  +
    36     37   If \fIfirst\fR is less than zero, it is considered to refer to the
    37     38   first element of the list.  For non-empty lists, the element indicated
    38     39   by \fIfirst\fR must exist.
    39         -.PP
           40  +
    40     41   If \fIlast\fR is less than zero but greater than \fIfirst\fR, then any
    41     42   specified elements will be prepended to the list.  If \fIlast\fR is
    42     43   less than \fIfirst\fR then no elements are deleted; the new elements
    43     44   are simply inserted before \fIfirst\fR.
    44         -.PP
           45  +
    45     46   The \fIelement\fR arguments specify zero or more new arguments to
    46     47   be added to the list in place of those that were deleted.
    47     48   Each \fIelement\fR argument will become a separate element of
    48     49   the list.  If no \fIelement\fR arguments are specified, then the elements
    49     50   between \fIfirst\fR and \fIlast\fR are simply deleted.  If \fIlist\fR
    50     51   is empty, any \fIelement\fR arguments are added to the end of the list.
    51     52   .SH EXAMPLES
................................................................................
    64     65   Deleting the last element from a list in a variable:
    65     66   .CS
    66     67   % set var {a b c d e}
    67     68   a b c d e
    68     69   % set var [\fBlreplace\fR $var end end]
    69     70   a b c d
    70     71   .CE
           72  +
    71     73   .SH "SEE ALSO"
    72     74   list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
    73     75   lset(n), lrange(n), lsort(n),
    74     76   .VS 8.5
    75     77   string(n)
    76     78   .VE
           79  +
           80  +
    77     81   .SH KEYWORDS
    78     82   element, list, replace

Changes to doc/lreverse.n.

     1         -.\" -*- nroff -*-
     2         -.\" Copyright (c) 2006 by Donal K. Fellows.  All rights reserved.
     3         -.\"
     4         -.\" See the file "license.terms" for information on usage and redistribution
     5         -.\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6         -.\" 
     7         -.\" RCS: @(#) $Id: lreverse.n,v 1.3 2007/10/25 09:25:27 dkf Exp $
     8         -.\" 
            1  +'\" -*- nroff -*-
            2  +'\" Copyright (c) 2006 by Donal K. Fellows.  All rights reserved.
            3  +'\"
            4  +'\" See the file "license.terms" for information on usage and redistribution
            5  +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
            6  +'\" 
            7  +'\" RCS: @(#) $Id: lreverse.n,v 1.4 2007/10/26 20:11:53 dgp Exp $
            8  +'\" 
     9      9   .so man.macros
    10     10   .TH lreverse n 8.5 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12         -.\" Note:  do not modify the .SH NAME line immediately below!
           12  +'\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   lreverse \- Reverse the order of a list
    15     15   .SH SYNOPSIS
    16     16   \fBlreverse \fIlist\fR
    17     17   .BE
    18     18   .SH DESCRIPTION
    19     19   .PP
    20     20   The \fBlreverse\fR command returns a list that has the same elements as its
    21     21   input list, \fIlist\fR, except with the elements in the reverse order.
    22     22   .SH EXAMPLES
    23     23   .CS
    24         -.ta 3i
    25         -\fBlreverse\fR {a a b c}	\fB\(->\fI c b a a\fR
    26         -\fBlreverse\fR {a b {c d} e f}	\fB\(->\fI f e {c d} b a\fR
           24  +\fBlreverse\fR {a a b c}        => c b a a
           25  +\fBlreverse\fR {a b {c d} e f}  => f e {c d} b a
    27     26   .CE
    28     27   .SH "SEE ALSO"
    29     28   list(n), lsearch(n), lsort(n)
           29  +
    30     30   .SH KEYWORDS
    31     31   element, list, reverse

Changes to doc/lsearch.n.

     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
     5      5   '\" Copyright (c) 2003-2004 Donal K. Fellows.
     6      6   '\"
     7      7   '\" See the file "license.terms" for information on usage and redistribution
     8      8   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     9      9   '\" 
    10         -'\" RCS: @(#) $Id: lsearch.n,v 1.28 2007/10/25 09:25:27 dkf Exp $
           10  +'\" RCS: @(#) $Id: lsearch.n,v 1.29 2007/10/26 20:11:53 dgp Exp $
    11     11   '\" 
    12     12   .so man.macros
    13     13   .TH lsearch n 8.5 Tcl "Tcl Built-In Commands"
    14     14   .BS
    15     15   '\" Note:  do not modify the .SH NAME line immediately below!
    16     16   .SH NAME
    17     17   lsearch \- See if a list contains a particular element
    18     18   .SH SYNOPSIS
    19     19   \fBlsearch \fR?\fIoptions\fR? \fIlist pattern\fR
    20     20   .BE
           21  +
    21     22   .SH DESCRIPTION
    22     23   .PP
    23     24   This command searches the elements of \fIlist\fR to see if one
    24     25   of them matches \fIpattern\fR.  If so, the command returns the index
    25     26   of the first matching element
    26     27   (unless the options \fB\-all\fR or \fB\-inline\fR are specified.)
    27     28   If not, the command returns \fB\-1\fR.  The \fIoption\fR arguments
................................................................................
    29     30   \fIpattern\fR and must have one of the values below:
    30     31   .SS "MATCHING STYLE OPTIONS"
    31     32   If all matching style options are omitted, the default matching style
    32     33   is \fB\-glob\fR.  If more than one matching style is specified, the
    33     34   last matching style given takes precedence.
    34     35   .TP
    35     36   \fB\-exact\fR
    36         -.
    37     37   \fIPattern\fR is a literal string that is compared for exact equality
    38     38   against each list element.
    39     39   .TP
    40     40   \fB\-glob\fR
    41         -.
    42     41   \fIPattern\fR is a glob-style pattern which is matched against each list
    43     42   element using the same rules as the \fBstring match\fR command.
    44     43   .TP
    45     44   \fB\-regexp\fR
    46         -.
    47     45   \fIPattern\fR is treated as a regular expression and matched against
    48     46   each list element using the rules described in the \fBre_syntax\fR
    49     47   reference page.
    50     48   .TP
    51     49   \fB\-sorted\fR
    52         -.
    53     50   The list elements are in sorted order.  If this option is specified,
    54     51   \fBlsearch\fR will use a more efficient searching algorithm to search
    55     52   \fIlist\fR.  If no other options are specified, \fIlist\fR is assumed
    56     53   to be sorted in increasing order, and to contain ASCII strings.  This
    57     54   option is mutually exclusive with \fB\-glob\fR and \fB\-regexp\fR, and
    58     55   is treated exactly like \fB-exact\fR when either \fB\-all\fR or
    59     56   \fB\-not\fR are specified.
................................................................................
    64     61   .
    65     62   Changes the result to be the list of all matching indices (or all matching
    66     63   values if \fB\-inline\fR is specified as well.) If indices are returned, the
    67     64   indices will be in numeric order. If values are returned, the order of the
    68     65   values will be the order of those values within the input \fIlist\fR.
    69     66   .TP
    70     67   \fB\-inline\fR
    71         -.
    72     68   The matching value is returned instead of its index (or an empty
    73     69   string if no value matches.)  If \fB\-all\fR is also specified, then
    74     70   the result of the command is the list of all values that matched.
    75     71   .TP
    76     72   \fB\-not\fR
    77         -.
    78     73   This negates the sense of the match, returning the index of the first
    79     74   non-matching value in the list.
    80     75   .TP
    81     76   \fB\-start\fR\0\fIindex\fR
    82         -.
    83     77   The list is searched starting at position \fIindex\fR.
    84     78   .VS 8.5
    85     79   The interpretation of the \fIindex\fR value is the same as
    86     80   for the command \fBstring index\fR, supporting simple index
    87     81   arithmetic and indices relative to the end of the list.
    88     82   .VE 8.5
    89     83   .SS "CONTENTS DESCRIPTION OPTIONS"
    90     84   These options describe how to interpret the items in the list being
    91     85   searched.  They are only meaningful when used with the \fB\-exact\fR
    92     86   and \fB\-sorted\fR options.  If more than one is specified, the last
    93     87   one takes precedence.  The default is \fB\-ascii\fR.
    94     88   .TP
    95     89   \fB\-ascii\fR
    96         -.
    97     90   The list elements are to be examined as Unicode strings (the name is
    98     91   for backward-compatibility reasons.)
    99     92   .TP
   100     93   \fB\-dictionary\fR
   101         -.
   102     94   The list elements are to be compared using dictionary-style
   103     95   comparisons (see \fBlsort\fR for a fuller description). Note that this
   104     96   only makes a meaningful difference from the \fB\-ascii\fR option when
   105     97   the \fB\-sorted\fR option is given, because values are only
   106     98   dictionary-equal when exactly equal.
   107     99   .TP
   108    100   \fB\-integer\fR
   109         -.
   110    101   The list elements are to be compared as integers.
   111    102   .VS 8.5
   112    103   .TP
   113    104   \fB\-nocase\fR
   114         -.
   115    105   Causes comparisons to be handled in a case-insensitive manner.  Has no
   116    106   effect if combined with the \fB\-dictionary\fR, \fB\-integer\fR, or 
   117    107   \fB\-real\fR options.
   118    108   .VE 8.5
   119    109   .TP
   120    110   \fB\-real\fR
   121         -.
   122    111   The list elements are to be compared as floating-point values.
   123    112   .SS "SORTED LIST OPTIONS"
   124    113   These options (only meaningful with the \fB\-sorted\fR option) specify
   125    114   how the list is sorted.  If more than one is given, the last one takes
   126    115   precedence.  The default option is \fB\-increasing\fR.
   127    116   .TP
   128    117   \fB\-decreasing\fR
   129         -.
   130    118   The list elements are sorted in decreasing order.  This option is only
   131    119   meaningful when used with \fB\-sorted\fR.
   132    120   .TP
   133    121   \fB\-increasing\fR
   134         -.
   135    122   The list elements are sorted in increasing order.  This option is only
   136    123   meaningful when used with \fB\-sorted\fR.
   137    124   .SS "NESTED LIST OPTIONS"
   138    125   .VS 8.5
   139    126   These options are used to search lists of lists.  They may be used
   140    127   with any other options.
   141    128   .TP
   142    129   \fB\-index\fR\0\fIindexList\fR
   143         -.
   144    130   This option is designed for use when searching within nested lists.
   145    131   The \fIindexList\fR argument gives a path of indices (much as might be
   146    132   used with the \fBlindex\fR or \fBlset\fR commands) within each element
   147    133   to allow the location of the term being matched against.
   148    134   .TP
   149    135   \fB\-subindices\fR
   150         -.
   151    136   If this option is given, the index result from this command (or every
   152    137   index result when \fB\-all\fR is also specified) will be a complete
   153    138   path (suitable for use with \fBlindex\fR or \fBlset\fR) within the
   154    139   overall list to the term found.  This option has no effect unless the
   155    140   \fI\-index\fR is also specified, and is just a convenience short-cut.
   156    141   .VE 8.5
   157    142   .SH EXAMPLES
   158    143   Basic searching:
   159    144   .CS
   160         -.ta 2i
   161    145   \fBlsearch\fR {a b c d e} c
   162         -	\fB\(->\fI 2\fR
          146  +      => 2
   163    147   \fBlsearch\fR -all {a b c a b c} c
   164         -	\fB\(->\fI 2 5\fR
          148  +      => 2 5
   165    149   .CE
   166         -.PP
          150  +
   167    151   Using \fBlsearch\fR to filter lists:
   168    152   .CS
   169         -.ta 2i
   170    153   \fBlsearch\fR -inline {a20 b35 c47} b*
   171         -	\fB\(->\fI b35\fR
          154  +      => b35
   172    155   \fBlsearch\fR -inline -not {a20 b35 c47} b*
   173         -	\fB\(->\fI a20\fR
          156  +      => a20
   174    157   \fBlsearch\fR -all -inline -not {a20 b35 c47} b*
   175         -	\fB\(->\fI a20 c47\fR
          158  +      => a20 c47
   176    159   \fBlsearch\fR -all -not {a20 b35 c47} b*
   177         -	\fB\(->\fI 0 2\fR
          160  +      => 0 2
   178    161   .CE
   179         -This can even do a
   180         -.QW set-like
   181         -removal operation:
          162  +This can even do a "set-like" removal operation:
   182    163   .CS
   183         -.ta 2i
   184    164   \fBlsearch\fR -all -inline -not -exact {a b c a d e a f g a} a
   185         -	\fB\(->\fI b c d e f g\fR
          165  +      => b c d e f g
   186    166   .CE
   187         -.PP
          167  +
   188    168   Searching may start part-way through the list:
   189    169   .CS
   190         -.ta 2i
   191    170   \fBlsearch\fR -start 3 {a b c a b c} c
   192         -	\fB\(->\fI 5\fR
          171  +      => 5
   193    172   .CE
   194         -.PP
          173  +
   195    174   It is also possible to search inside elements:
   196    175   .CS
   197         -.ta 2i
   198    176   \fBlsearch\fR -index 1 -all -inline {{a abc} {b bcd} {c cde}} *bc*
   199         -	\fB\(->\fI {a abc} {b bcd}\fR
          177  +      => {a abc} {b bcd}
   200    178   .CE
          179  +
   201    180   .SH "SEE ALSO"
   202    181   foreach(n), list(n), lappend(n), lindex(n), linsert(n), llength(n), 
   203    182   lset(n), lsort(n), lrange(n), lreplace(n),
   204    183   .VS 8.5
   205    184   string(n)
   206    185   .VE
          186  +
          187  +
   207    188   .SH KEYWORDS
   208    189   list, match, pattern, regular expression, search, string
   209         -.\" Local Variables:
   210         -.\" mode: nroff
   211         -.\" End:
          190  +
          191  +'\" Local Variables:
          192  +'\" mode: nroff
          193  +'\" End:

Changes to doc/lset.n.

     1      1   '\"
     2      2   '\" Copyright (c) 2001 by Kevin B. Kenny.  All rights reserved.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: lset.n,v 1.11 2007/10/25 09:25:27 dkf Exp $
            7  +'\" RCS: @(#) $Id: lset.n,v 1.12 2007/10/26 20:11:53 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH lset n 8.4 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   lset \- Change an element in a list
................................................................................
    75     75   than or equal to zero.  The integer appearing in each \fIindex\fR
    76     76   argument must be strictly less than the length of the corresponding
    77     77   list.  In other words, the \fBlset\fR command cannot change the size
    78     78   of a list.  If an index is outside the permitted range, an error is reported.
    79     79   .SH EXAMPLES
    80     80   In each of these examples, the initial value of \fIx\fR is:
    81     81   .CS
    82         -.ta 2i
    83     82   set x [list [list a b c] [list d e f] [list g h i]]
    84         -	 \fB\(->\fR {a b c} {d e f} {g h i}
           83  +  => {a b c} {d e f} {g h i}
    85     84   .CE
    86     85   The indicated return value also becomes the new value of \fIx\fR
    87     86   (except in the last case, which is an error which leaves the value of
    88     87   \fIx\fR unchanged.)
    89     88   .CS
    90         -.ta 2i
    91         -lset x {j k l}	 \fB\(->\fR j k l
    92         -lset x {} {j k l}	 \fB\(->\fR j k l
    93         -lset x 0 j	 \fB\(->\fR j {d e f} {g h i}
    94         -lset x 2 j	 \fB\(->\fR {a b c} {d e f} j
    95         -lset x end j	 \fB\(->\fR {a b c} {d e f} j
    96         -lset x end-1 j	 \fB\(->\fR {a b c} j {g h i}
    97         -lset x 2 1 j	 \fB\(->\fR {a b c} {d e f} {g j i}
    98         -lset x {2 1} j	 \fB\(->\fR {a b c} {d e f} {g j i}
    99         -lset x {2 3} j	 \fB\(->\fR \fIlist index out of range\fR
           89  +lset x {j k l} => j k l
           90  +lset x {} {j k l} => j k l
           91  +lset x 0 j => j {d e f} {g h i}
           92  +lset x 2 j => {a b c} {d e f} j
           93  +lset x end j => {a b c} {d e f} j
           94  +lset x end-1 j => {a b c} j {g h i}
           95  +lset x 2 1 j => {a b c} {d e f} {g j i}
           96  +lset x {2 1} j => {a b c} {d e f} {g j i}
           97  +lset x {2 3} j => \fIlist index out of range\fR
   100     98   .CE
   101     99   In the following examples, the initial value of \fIx\fR is:
   102    100   .CS
   103         -.ta 2i
   104    101   set x [list [list [list a b] [list c d]] \e
   105    102               [list [list e f] [list g h]]]
   106         -	 \fB\(->\fR {{a b} {c d}} {{e f} {g h}}
          103  + => {{a b} {c d}} {{e f} {g h}}
   107    104   .CE
   108    105   The indicated return value also becomes the new value of \fIx\fR.
   109    106   .CS
   110         -.ta 2i
   111         -lset x 1 1 0 j	 \fB\(->\fR {{a b} {c d}} {{e f} {j h}}
   112         -lset x {1 1 0} j	 \fB\(->\fR {{a b} {c d}} {{e f} {j h}}
          107  +lset x 1 1 0 j => {{a b} {c d}} {{e f} {j h}}
          108  +lset x {1 1 0} j => {{a b} {c d}} {{e f} {j h}}
   113    109   .CE
   114    110   .SH "SEE ALSO"
   115    111   list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
   116    112   lsort(n), lrange(n), lreplace(n),
   117    113   .VS 8.5
   118    114   string(n)
   119    115   .VE
          116  +
          117  +
   120    118   .SH KEYWORDS
   121    119   element, index, list, replace, set

Changes to doc/lsort.n.

     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 1999 Scriptics Corporation
     5      5   '\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
     6      6   '\"
     7      7   '\" See the file "license.terms" for information on usage and redistribution
     8      8   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     9      9   '\" 
    10         -'\" RCS: @(#) $Id: lsort.n,v 1.23 2007/10/24 14:29:38 dkf Exp $
           10  +'\" RCS: @(#) $Id: lsort.n,v 1.24 2007/10/26 20:11:53 dgp Exp $
    11     11   '\" 
    12     12   .so man.macros
    13     13   .TH lsort n 8.5 Tcl "Tcl Built-In Commands"
    14     14   .BS
    15     15   '\" Note:  do not modify the .SH NAME line immediately below!
    16     16   .SH NAME
    17     17   lsort \- Sort the elements of a list
................................................................................
    55     55   \fIcommand\fR with the two elements appended as additional
    56     56   arguments.  The script should return an integer less than,
    57     57   equal to, or greater than zero if the first element is to
    58     58   be considered less than, equal to, or greater than the second,
    59     59   respectively.
    60     60   .TP 20
    61     61   \fB\-increasing\fR
    62         -Sort the list in increasing order (i.e.
    63         -.QW smallest
    64         -items first). This is the default.
           62  +Sort the list in increasing order (``smallest'' items first).
           63  +This is the default.
    65     64   .TP 20
    66     65   \fB\-decreasing\fR
    67         -Sort the list in decreasing order (i.e.
    68         -.QW largest
    69         -items first).
           66  +Sort the list in decreasing order (``largest'' items first).
    70     67   .TP 20
    71     68   \fB\-indices\fR
    72     69   .VS "8.5 (TIP#217)"
    73     70   Return a list of indices into \fIlist\fR in sorted order instead of
    74     71   the values themselves.
    75     72   .VE "8.5 (TIP#217)"
    76     73   .TP 20

Changes to doc/mathfunc.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-2000 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2005 by Kevin B. Kenny <[email protected]>. All rights reserved
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: mathfunc.n,v 1.14 2007/10/25 14:07:32 dkf Exp $
            9  +'\" RCS: @(#) $Id: mathfunc.n,v 1.15 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH mathfunc n 8.5 Tcl "Tcl Mathematical Functions"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   mathfunc \- Mathematical functions for Tcl expressions
................................................................................
    81     81   .br
    82     82   \fB::tcl::mathfunc::wide\fR \fIarg\fR
    83     83   .sp
    84     84   .BE
    85     85   .SH "DESCRIPTION"
    86     86   .PP
    87     87   The \fBexpr\fR command handles mathematical functions of the form
    88         -.QW \fBsin($x)\fR
    89         -or
    90         -.QW \fBatan2($y,$x)\fR
    91         -by converting them to calls of the form
    92         -.QW "\fB[tcl::mathfunc::sin [expr {$x}]]\fR"
    93         -or
    94         -.QW "\fB[tcl::mathfunc::atan2 [expr {$y}] [expr {$x}]]\fR" .
           88  +\fBsin($x)\fR or \fBatan2($y,$x)\fR by converting them to calls of the
           89  +form \fB[tcl::mathfunc::sin [expr {$x}]]\fR or
           90  +\fB[tcl::mathfunc::atan2 [expr {$y}] [expr {$x}]]\fR.
    95     91   A number of math functions are available by default within the
    96     92   namespace \fB::tcl::mathfunc\fR; these functions are also available
    97     93   for code apart from \fBexpr\fR, by invoking the given commands
    98     94   directly.
    99     95   .PP
   100     96   Tcl supports the following mathematical functions in expressions, all
   101     97   of which work solely with floating-point numbers unless otherwise noted:
................................................................................
   109    105   \fBmin\fR	\fBpow\fR	\fBrand\fR	\fBround\fR
   110    106   \fBsin\fR	\fBsinh\fR	\fBsqrt\fR	\fBsrand\fR
   111    107   \fBtan\fR	\fBtanh\fR	\fBwide\fR
   112    108   .DE
   113    109   .PP
   114    110   .TP
   115    111   \fBabs(\fIarg\fB)\fR
   116         -.
   117    112   Returns the absolute value of \fIarg\fR.  \fIArg\fR may be either
   118    113   integer or floating-point, and the result is returned in the same form.
   119    114   .TP
   120    115   \fBacos(\fIarg\fB)\fR
   121         -.
   122    116   Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR]
   123    117   radians. \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR].
   124    118   .TP
   125    119   \fBasin(\fIarg\fB)\fR
   126         -.
   127    120   Returns the arc sine of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR]
   128    121   radians.  \fIArg\fR should be in the range [\fI-1\fR,\fI1\fR].
   129    122   .TP
   130    123   \fBatan(\fIarg\fB)\fR
   131         -.
   132    124   Returns the arc tangent of \fIarg\fR, in the range [\fI-pi/2\fR,\fIpi/2\fR]
   133    125   radians.
   134    126   .TP
   135    127   \fBatan2(\fIy, x\fB)\fR
   136         -.
   137    128   Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI-pi\fR,\fIpi\fR]
   138    129   radians.  \fIx\fR and \fIy\fR cannot both be 0.  If \fIx\fR is greater
   139    130   than \fI0\fR, this is equivalent to \fBatan(\fIy/x\fB)\fR.
   140    131   .TP
   141    132   \fBbool(\fIarg\fB)\fR
   142         -.
   143    133   Accepts any numeric value, or any string acceptable to
   144    134   \fBstring is boolean\fR, and returns the corresponding 
   145    135   boolean value \fB0\fR or \fB1\fR.  Non-zero numbers are true.
   146    136   Other numbers are false.  Non-numeric strings produce boolean value in
   147         -agreement with
   148         -.QW "\fBstring is true\fR"
   149         -and
   150         -.QW "\fBstring is false\fR" .
          137  +agreement with \fBstring is true\fR and \fBstring is false\fR.
   151    138   .TP
   152    139   \fBceil(\fIarg\fB)\fR
   153         -.
   154    140   Returns the smallest integral floating-point value (i.e. with a zero
   155    141   fractional part) not less than \fIarg\fR.  The argument may be any
   156    142   numeric value.
   157    143   .TP
   158    144   \fBcos(\fIarg\fB)\fR
   159         -.
   160    145   Returns the cosine of \fIarg\fR, measured in radians.
   161    146   .TP
   162    147   \fBcosh(\fIarg\fB)\fR
   163         -.
   164    148   Returns the hyperbolic cosine of \fIarg\fR.  If the result would cause
   165    149   an overflow, an error is returned.
   166    150   .TP
   167    151   \fBdouble(\fIarg\fB)\fR
   168         -.
   169    152   The argument may be any numeric value,
   170    153   If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts
   171    154   \fIarg\fR to floating-point and returns the converted value.  May return
   172    155   \fBInf\fR or \fB-Inf\fR when the argument is a numeric value that exceeds
   173    156   the floating-point range.
   174    157   .TP
   175    158   \fBentier(\fIarg\fB)\fR
................................................................................
   177    160   The argument may be any numeric value.  The integer part of \fIarg\fR
   178    161   is determined and returned.  The integer range returned by this function
   179    162   is unlimited, unlike functions \fBint()\fR and \fBwide()\fR which
   180    163   truncate their range to fit in particular storage widths.
   181    164   .VE 8.5
   182    165   .TP
   183    166   \fBexp(\fIarg\fB)\fR
   184         -.
   185    167   Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR.
   186    168   If the result would cause an overflow, an error is returned.
   187    169   .TP
   188    170   \fBfloor(\fIarg\fB)\fR
   189         -.
   190    171   Returns the largest integral floating-point value (i.e. with a zero
   191    172   fractional part) not greater than \fIarg\fR.  The argument may be
   192    173   any numeric value.
   193    174   .TP
   194    175   \fBfmod(\fIx, y\fB)\fR
   195         -.
   196    176   Returns the floating-point remainder of the division of \fIx\fR by
   197    177   \fIy\fR.  If \fIy\fR is 0, an error is returned.
   198    178   .TP
   199    179   \fBhypot(\fIx, y\fB)\fR
   200         -.
   201    180   Computes the length of the hypotenuse of a right-angled triangle
   202         -.QW "\fBsqrt(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fB)\fR" .
          181  +\fBsqrt(\fIx\fR*\fIx\fR+\fIy\fR*\fIy\fB)\fR.
   203    182   .TP
   204    183   \fBint(\fIarg\fB)\fR
   205         -.
   206    184   The argument may be any numeric value.  The integer part of \fIarg\fR
   207    185   is determined, and then the low order bits of that integer value up
   208    186   to the machine word size are returned as an integer value.  For reference,
   209    187   the number of bytes in the machine word are stored in
   210    188   \fBtcl_platform(wordSize)\fR.
   211    189   .TP
   212    190   \fBisqrt(\fIarg\fB)\fR
   213         -.
   214    191   Computes the integer part of the square root of \fIarg\fR.  \fIArg\fR must be
   215    192   a positive value, either an integer or a floating point number.
   216    193   Unlike \fBsqrt\fR, which is limited to the precision of a floating point
   217    194   number, \fIisqrt\fR will return a result of arbitrary precision.
   218    195   .TP
   219    196   \fBlog(\fIarg\fB)\fR
   220         -.
   221    197   Returns the natural logarithm of \fIarg\fR.  \fIArg\fR must be a
   222    198   positive value.
   223    199   .TP
   224    200   \fBlog10(\fIarg\fB)\fR
   225         -.
   226    201   Returns the base 10 logarithm of \fIarg\fR.  \fIArg\fR must be a
   227    202   positive value.
   228    203   .TP
   229    204   \fBmax(\fIarg\fB, \fI...\fB)\fR
   230         -.
   231    205   Accepts one or more numeric arguments.  Returns the one argument
   232    206   with the greatest value.
   233    207   .TP
   234    208   \fBmin(\fIarg\fB, \fI...\fB)\fR
   235         -.
   236    209   Accepts one or more numeric arguments.  Returns the one argument
   237    210   with the least value.
   238    211   .TP
   239    212   \fBpow(\fIx, y\fB)\fR
   240         -.
   241    213   Computes the value of \fIx\fR raised to the power \fIy\fR.  If \fIx\fR
   242    214   is negative, \fIy\fR must be an integer value.
   243    215   .TP
   244    216   \fBrand()\fR
   245         -.
   246    217   Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR).  
   247    218   The generator algorithm is a simple linear congruential generator that
   248    219   is not cryptographically secure.  Each result from \fBrand\fR completely
   249    220   determines all future results from subsequent calls to \fBrand\fR, so
   250    221   \fBrand\fR should not be used to generate a sequence of secrets, such as
   251    222   one-time passwords.  The seed of the generator is initialized from the
   252    223   internal clock of the machine or may be set with the \fBsrand\fR function.
   253    224   .TP
   254    225   \fBround(\fIarg\fB)\fR
   255         -.
   256    226   If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts
   257    227   \fIarg\fR to integer by rounding and returns the converted value.
   258    228   .TP
   259    229   \fBsin(\fIarg\fB)\fR
   260         -.
   261    230   Returns the sine of \fIarg\fR, measured in radians.
   262    231   .TP
   263    232   \fBsinh(\fIarg\fB)\fR
   264         -.
   265    233   Returns the hyperbolic sine of \fIarg\fR.  If the result would cause
   266    234   an overflow, an error is returned.
   267    235   .TP
   268    236   \fBsqrt(\fIarg\fB)\fR
   269         -.
   270    237   The argument may be any non-negative numeric value.  Returns a floating-point
   271    238   value that is the square root of \fIarg\fR.  May return \fBInf\fR when the
   272    239   argument is a numeric value that exceeds the square of the maximum value of
   273    240   the floating-point range.
   274    241   .TP
   275    242   \fBsrand(\fIarg\fB)\fR
   276         -.
   277    243   The \fIarg\fR, which must be an integer, is used to reset the seed for
   278    244   the random number generator of \fBrand\fR.  Returns the first random
   279    245   number (see \fBrand()\fR) from that seed.  Each interpreter has its own seed.
   280    246   .TP
   281    247   \fBtan(\fIarg\fB)\fR
   282         -.
   283    248   Returns the tangent of \fIarg\fR, measured in radians.
   284    249   .TP
   285    250   \fBtanh(\fIarg\fB)\fR
   286         -.
   287    251   Returns the hyperbolic tangent of \fIarg\fR.
   288    252   .TP
   289    253   \fBwide(\fIarg\fB)\fR
   290         -.
   291    254   The argument may be any numeric value.  The integer part of \fIarg\fR
   292    255   is determined, and then the low order 64 bits of that integer value
   293    256   are returned as an integer value.  
   294    257   .PP
   295    258   In addition to these predefined functions, applications may
   296    259   define additional functions by using \fBproc\fR (or any other method,
   297    260   such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define
................................................................................
   298    261   new commands in the \fBtcl::mathfunc\fR namespace.  In addition, an
   299    262   obsolete interface named \fBTcl_CreateMathFunc\fR() is available to
   300    263   extensions that are written in C. The latter interface is not recommended
   301    264   for new implementations.
   302    265   .SH "SEE ALSO"
   303    266   expr(n), namespace(n)
   304    267   .SH "COPYRIGHT"
   305         -.nf
   306         -Copyright \(co 1993 The Regents of the University of California.
   307         -Copyright \(co 1994-2000 Sun Microsystems Incorporated.
   308         -Copyright \(co 2005, 2006 by Kevin B. Kenny <[email protected]>.
   309         -.fi
          268  +Copyright (c) 1993 The Regents of the University of California.
          269  +.br
          270  +Copyright (c) 1994-2000 Sun Microsystems Incorporated.
          271  +.br
          272  +Copyright (c) 2005, 2006 by Kevin B. Kenny <[email protected]>.

Changes to doc/mathop.n.

     1      1   .\" -*- nroff -*-
     2      2   .\" Copyright (c) 2006 Donal K. Fellows.
     3      3   .\"
     4      4   .\" See the file "license.terms" for information on usage and redistribution
     5      5   .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   .\"
     7         -.\" RCS: @(#) $Id: mathop.n,v 1.5 2007/10/25 14:07:32 dkf Exp $
            7  +.\" RCS: @(#) $Id: mathop.n,v 1.6 2007/10/26 20:11:53 dgp Exp $
     8      8   .\"
     9      9   .so man.macros
    10     10   .TH mathop n 8.5 Tcl "Tcl Mathematical Operator Commands"
    11     11   .BS
    12     12   .\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   mathop \- Mathematical operators as Tcl commands
................................................................................
   121    121   Returns the integral modulus of the first argument with respect to the second.
   122    122   Each \fInumber\fR must have an integral value.
   123    123   .TP
   124    124   \fB**\fR ?\fInumber\fR ...?
   125    125   .
   126    126   Returns the result of raising each value to the power of the result of
   127    127   recursively operating on the result of processing the following arguments, so
   128         -.QW "\fB** 2 3 4\fR"
   129         -is the same as
   130         -.QW "\fB** 2 [** 3 4]\fR" .
   131         -Each \fInumber\fR may be
          128  +\fB** 2 3 4\fR is the same as \fB** 2 [** 3 4]\fR. Each \fInumber\fR may be
   132    129   any numeric value, though the second number must not be fractional if the
   133    130   first is negative. If no arguments are given, the result will be one, and if
   134    131   only one argument is given, the result will be that argument.
   135    132   .TP
   136    133   \fB&\fR ?\fInumber\fR ...?
   137    134   .
   138    135   Returns the bit-wise AND of each of the arbitrarily many arguments. Each

Changes to doc/memory.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1992-1999 by Karl Lehenbauer and Mark Diekhans
     3      3   '\" Copyright (c) 2000 by Scriptics Corporation.
     4      4   '\" All rights reserved.
     5      5   '\" 
     6         -'\" RCS: @(#) $Id: memory.n,v 1.7 2007/10/25 14:07:32 dkf Exp $
            6  +'\" RCS: @(#) $Id: memory.n,v 1.8 2007/10/26 20:11:53 dgp Exp $
     7      7   '\" 
     8      8   .so man.macros
     9      9   .TH memory n 8.1 Tcl "Tcl Built-In Commands"
    10     10   .BS
    11     11   .SH NAME
    12     12   memory \- Control Tcl memory debugging capabilities
    13     13   .SH SYNOPSIS
    14     14   \fBmemory \fIoption \fR?\fIarg arg ...\fR?
    15     15   .BE
           16  +
    16     17   .SH DESCRIPTION
    17     18   .PP
    18     19   The \fBmemory\fR command gives the Tcl developer control of Tcl's memory
    19     20   debugging capabilities.  The memory command has several suboptions, which are
    20     21   described below.  It is only available when Tcl has been compiled with
    21     22   memory debugging enabled (when \fBTCL_MEM_DEBUG\fR is defined at
    22     23   compile time), and after \fBTcl_InitMemory\fR has been called.
    23     24   .TP
    24     25   \fBmemory active\fR \fIfile\fR
    25         -.
    26     26   Write a list of all currently allocated memory to the specified \fIfile\fR.
    27     27   .TP
    28     28   \fBmemory break_on_malloc\fR \fIcount\fR
    29         -.
    30     29   After the \fIcount\fR allocations have been performed, \fBckalloc\fR
    31     30   outputs a message to this effect and that it is now attempting to enter
    32     31   the C debugger.  Tcl will then issue a \fISIGINT\fR signal against itself.
    33     32   If you are running Tcl under a C debugger, it should then enter the debugger
    34     33   command mode.
    35     34   .TP
    36     35   \fBmemory info\fR
    37         -.
    38     36   Returns a report containing the total allocations and frees since 
    39     37   Tcl began, the current packets allocated (the current
    40     38   number of calls to \fBckalloc\fR not met by a corresponding call 
    41     39   to \fBckfree\fR), the current bytes allocated, and the maximum number
    42     40   of packets and bytes allocated.
    43     41   .TP
    44         -\fBmemory init \fR[\fBon\fR|\fBoff\fR]
    45         -.
           42  +\fB memory init [on|off]\fR
    46     43   Turn on or off the pre-initialization of all allocated memory
    47     44   with bogus bytes.  Useful for detecting the use of uninitialized values.
    48     45   .TP
    49     46   \fBmemory onexit\fR \fIfile\fR
    50         -.
    51     47   Causes a list of all allocated memory to be written to the specified \fIfile\fR
    52     48   during the finalization of Tcl's memory subsystem.  Useful for checking
    53     49   that memory is properly cleaned up during process exit.
    54     50   .TP
    55     51   \fBmemory tag\fR \fIstring\fR
    56         -.
    57     52   Each packet of memory allocated by \fBckalloc\fR can have associated
    58     53   with it a string-valued tag.  In the lists of allocated memory generated
    59     54   by \fBmemory active\fR and \fBmemory onexit\fR, the tag for each packet
    60     55   is printed along with other information about the packet.  The
    61     56   \fBmemory tag\fR command sets the tag value for subsequent calls
    62     57   to \fBckalloc\fR to be \fIstring\fR.  
    63     58   .TP
    64         -\fBmemory trace \fR[\fBon\fR|\fBoff\fR]
    65         -.
           59  +\fBmemory trace [on|off]\fR
           60  +.br
    66     61   Turns memory tracing on or off.  When memory tracing is on, every call
    67     62   to \fBckalloc\fR causes a line of trace information to be written to
    68     63   \fIstderr\fR, consisting of the word \fIckalloc\fR, followed by the
    69     64   address returned, the amount of memory allocated, and the C filename
    70     65   and line number of the code performing the allocation.  For example:
    71     66   .RS
    72     67   .CS
    73     68   ckalloc 40e478 98 tclProc.c 1406
    74     69   .CE
    75     70   Calls to \fBckfree\fR are traced in the same manner.
    76     71   .RE
    77     72   .TP
    78     73   \fBmemory trace_on_at_malloc\fR \fIcount\fR
    79         -.
    80         -Enable memory tracing after \fIcount\fR \fBckalloc\fRs have been performed.
    81         -For example, if you enter
    82         -.QW "\fBmemory trace_on_at_malloc 100\fR" ,
    83         -.
           74  +Enable memory tracing after \fIcount\fR \fBckalloc\fR's have been performed.
           75  +For example, if you enter \fBmemory trace_on_at_malloc 100\fR,
    84     76   after the 100th call to \fBckalloc\fR, memory trace information will begin
    85     77   being displayed for all allocations and frees.  Since there can be a lot
    86     78   of memory activity before a problem occurs, judicious use of this option
    87     79   can reduce the slowdown caused by tracing (and the amount of trace information
    88     80   produced), if you can identify a number of allocations that occur before
    89     81   the problem sets in.  The current number of memory allocations that have 
    90     82   occurred since Tcl started is printed on a guard zone failure.
    91     83   .TP
    92         -\fBmemory validate \fR[\fBon\fR|\fBoff\fR]
    93         -.
           84  +\fBmemory validate [on|off]\fR
    94     85   Turns memory validation on or off. When memory validation is enabled,
    95     86   on every call to \fBckalloc\fR or \fBckfree\fR, the guard zones are
    96     87   checked for every piece of memory currently in existence that was
    97     88   allocated by \fBckalloc\fR.  This has a large performance impact and
    98     89   should only be used when overwrite problems are strongly suspected.
    99     90   The advantage of enabling memory validation is that a guard zone
   100     91   overwrite can be detected on the first call to \fBckalloc\fR or
   101     92   \fBckfree\fR after the overwrite occurred, rather than when the
   102     93   specific memory with the overwritten guard zone(s) is freed, which may
   103     94   occur long after the overwrite occurred.
           95  +
   104     96   .SH "SEE ALSO"
   105         -ckalloc(3), ckfree(3), Tcl_ValidateAllMemory(3), Tcl_DumpActiveMemory(3),
   106         -TCL_MEM_DEBUG
           97  +ckalloc, ckfree, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory, TCL_MEM_DEBUG
           98  +
   107     99   .SH KEYWORDS
   108    100   memory, debug

Changes to doc/msgcat.n.

    29     29   .sp
    30     30   \fB::msgcat::mcset \fIlocale src-string \fR?\fItranslate-string\fR?
    31     31   .sp
    32     32   \fB::msgcat::mcmset \fIlocale src-trans-list\fR
    33     33   .sp
    34     34   \fB::msgcat::mcunknown \fIlocale src-string\fR
    35     35   .BE
           36  +
    36     37   .SH DESCRIPTION
    37     38   .PP
    38     39   The \fBmsgcat\fR package provides a set of functions
    39     40   that can be used to manage multi-lingual user interfaces.
    40         -Text strings are defined in a
    41         -.QW "message catalog"
    42         -which is independent from the application, and
           41  +Text strings are defined in a ``message catalog'' which
           42  +is independent from the application, and
    43     43   which can be edited or localized without modifying
    44     44   the application source code.  New languages
    45     45   or locales are provided by adding a new file to
    46     46   the message catalog.
    47     47   .PP
    48     48   Use of the message catalog is optional by any application
    49     49   or package, but is encouraged if the application or package
................................................................................
    90     90   the user, based on the user's language specification.
    91     91   The list is ordered from most specific to least
    92     92   preference.  The list is derived from the current
    93     93   locale set in msgcat by \fB::msgcat::mclocale\fR, and
    94     94   cannot be set independently.  For example, if the
    95     95   current locale is en_US_funky, then \fB::msgcat::mcpreferences\fR
    96     96   .VS 1.4
    97         -returns
    98         -.QW "\fBen_US_funky en_US en {}\fR" .
           97  +returns \fB{en_US_funky en_US en {}}\fR.
    99     98   .VE 1.4
   100     99   .TP
   101    100   \fB::msgcat::mcload \fIdirname\fR
   102    101   Searches the specified directory for files that match
   103    102   the language specifications returned by \fB::msgcat::mcpreferences\fR
   104         -(note that these are all lowercase), extended by the file extension
   105         -.QW .msg .
   106         -Each matching file is 
          103  +(note that these are all lowercase), extended by the file
          104  +extension ``.msg''.  Each matching file is 
   107    105   read in order, assuming a UTF-8 encoding.  The file contents are
   108    106   then evaluated as a Tcl script.  This means that Unicode characters
   109    107   may be present in the message file either directly in their UTF-8
   110    108   encoded form, or by use of the backslash-u quoting recognized by Tcl
   111    109   evaluation.  The number of message files which matched the specification
   112    110   and were loaded is returned.
   113    111   .TP
................................................................................
   118    116   for both.  The function returns \fItranslate-string\fR.
   119    117   .TP
   120    118   \fB::msgcat::mcmset \fIlocale src-trans-list\fR
   121    119   Sets the translation for multiple source strings in
   122    120   \fIsrc-trans-list\fR in the specified \fIlocale\fR and the current
   123    121   namespace.
   124    122   \fIsrc-trans-list\fR must have an even number of elements and is in
   125         -the form
   126         -.QW "\fIsrc-string translate-string\fR ?\fIsrc-string translate-string ...\fR?}" .
   127         -The \fB::msgcat::mcmset\fR command can be significantly
          123  +the form {\fIsrc-string translate-string\fR ?\fIsrc-string
          124  +translate-string ...\fR?} \fB::msgcat::mcmset\fR can be significantly
   128    125   faster than multiple invocations of \fB::msgcat::mcset\fR. The function
   129    126   returns the number of translations set.
   130    127   .TP
   131    128   \fB::msgcat::mcunknown \fIlocale src-string\fR
   132    129   This routine is called by \fB::msgcat::mc\fR in the case when
   133    130   a translation for \fIsrc-string\fR is not defined in the
   134    131   current locale.  The default action is to return
................................................................................
   140    137   to \fB::msgcat::mc\fR.  
   141    138   .SH "LOCALE SPECIFICATION"
   142    139   .PP
   143    140   The locale is specified to \fBmsgcat\fR by a locale string
   144    141   passed to \fB::msgcat::mclocale\fR.
   145    142   The locale string consists of
   146    143   a language code, an optional country code, and an optional
   147         -system-specific code, each separated by
   148         -.QW _ .
   149         -The country and language
          144  +system-specific code, each separated by ``_''.  The country and language
   150    145   codes are specified in standards ISO-639 and ISO-3166.
   151         -For example, the locale
   152         -.QW en
   153         -specifies English and
   154         -.QW en_US
   155         -specifies U.S. English.
          146  +For example, the locale ``en'' specifies English and ``en_US'' specifies
          147  +U.S. English.
   156    148   .PP
   157    149   When the msgcat package is first loaded, the locale is initialized
   158    150   according to the user's environment.  The variables \fBenv(LC_ALL)\fR,
   159    151   \fBenv(LC_MESSAGES)\fR, and \fBenv(LANG)\fR are examined in order.
   160    152   The first of them to have a non-empty value is used to determine the
   161    153   initial locale.  The value is parsed according to the XPG4 pattern
   162    154   .CS
................................................................................
   167    159   .CS
   168    160   language[_country][_modifier]
   169    161   .CE
   170    162   On Windows, if none of those environment variables is set, msgcat will
   171    163   attempt to extract locale information from the
   172    164   registry.  If all these attempts to discover an initial locale
   173    165   from the user's environment fail, msgcat defaults to an initial
   174         -locale of
   175         -.QW C .
          166  +locale of ``C''.
   176    167   .PP
   177         -When a locale is specified by the user, a
   178         -.QW "best match"
   179         -search is
          168  +When a locale is specified by the user, a ``best match'' search is
   180    169   performed during string translation.  For example, if a user specifies
   181    170   .VS 1.4
   182         -en_GB_Funky, the locales
   183         -.QW en_GB_Funky ,
   184         -.QW en_GB ,
   185         -.QW en
   186         -and
   187         -.MT
          171  +en_GB_Funky, the locales ``en_GB_Funky'', ``en_GB'', ``en'' and ``''
   188    172   (the empty string)
   189    173   .VE 1.4
   190    174   are searched in order until a matching translation
   191    175   string is found.  If no translation string is available, then
   192    176   \fB::msgcat::mcunknown\fR is called.
   193    177   .SH "NAMESPACES AND MESSAGE CATALOGS"
   194    178   .PP
................................................................................
   213    197   hello from ::
   214    198   hello from ::foo
   215    199   .CE
   216    200   .PP
   217    201   When searching for a translation of a message, the
   218    202   message catalog will search first the current namespace,
   219    203   then the parent of the current namespace, and so on until
   220         -the global namespace is reached.  This allows child namespaces to
   221         -.QW inherit
   222         -messages from their parent namespace.
          204  +the global namespace is reached.  This allows child namespaces
          205  +to "inherit" messages from their parent namespace.
   223    206   .PP
   224         -For example, executing (in the
   225         -.QW en
   226         -locale) the code 
          207  +For example, executing (in the ``en'' locale) the code 
   227    208   .CS
   228    209   \fB::msgcat::mcset\fR en m1 ":: message1"
   229    210   \fB::msgcat::mcset\fR en m2 ":: message2"
   230    211   \fB::msgcat::mcset\fR en m3 ":: message3"
   231    212   namespace eval ::foo {
   232    213      \fB::msgcat::mcset\fR en m2 "::foo message2"
   233    214      \fB::msgcat::mcset\fR en m3 "::foo message3"
................................................................................
   250    231   .PP
   251    232   Message files can be located in any directory, subject
   252    233   to the following conditions:
   253    234   .IP [1]
   254    235   All message files for a package are in the same directory.
   255    236   .IP [2]
   256    237   The message file name is a msgcat locale specifier (all lowercase)
   257         -followed by
   258         -.QW .msg .
   259         -For example:
   260         -.RS
          238  +followed by ``.msg''.  For example:
   261    239   .CS
   262    240   es.msg    -- spanish
   263    241   en_gb.msg -- United Kingdom English
   264    242   .CE
   265    243   .VS 1.4
   266         -\fIException:\fR The message file for the root locale
   267         -.MT
   268         -is called \fBROOT.msg\fR.  This exception is made so as not to
          244  +\fIException:\fR The message file for the root locale ``'' is
          245  +called \fBROOT.msg\fR.  This exception is made so as not to
   269    246   cause peculiar behavior, such as marking the message file as
   270         -.QW hidden
   271         -on Unix file systems.
          247  +``hidden'' on Unix file systems.
   272    248   .VE 1.4
   273         -.RE
   274    249   .IP [3]
   275    250   The file contains a series of calls to \fBmcset\fR and
   276    251   \fBmcmset\fR, setting the necessary translation strings
   277    252   for the language, likely enclosed in a \fBnamespace eval\fR
   278    253   so that all source strings are tied to the namespace of
   279    254   the package. For example, a short \fBes.msg\fR might contain:
   280         -.RS
   281    255   .CS
   282    256   namespace eval ::mypackage {
   283    257      \fB::msgcat::mcset\fR es "Free Beer!" "Cerveza Gracias!"
   284    258   }
   285    259   .CE
   286         -.RE
   287    260   .SH "RECOMMENDED MESSAGE SETUP FOR PACKAGES"
   288    261   .PP
   289    262   If a package is installed into a subdirectory of the
   290    263   \fBtcl_pkgPath\fR and loaded via \fBpackage require\fR, the
   291    264   following procedure is recommended.
   292    265   .IP [1]
   293    266   During package installation, create a subdirectory
   294    267   \fBmsgs\fR under your package directory.
   295    268   .IP [2]
   296    269   Copy your *.msg files into that directory.
   297    270   .IP [3]
   298         -Add the following command to your package initialization script:
   299         -.RS
          271  + Add the following command to your package
          272  +initialization script:
   300    273   .CS
   301    274   # load language files, stored in msgs subdirectory
   302    275   \fB::msgcat::mcload\fR [file join [file dirname [info script]] msgs]
   303    276   .CE
   304         -.RE
   305    277   .SH "POSITIONAL CODES FOR FORMAT AND SCAN COMMANDS"
   306    278   .PP
   307    279   It is possible that a message string used as an argument
   308    280   to \fBformat\fR might have positionally dependent parameters that
   309    281   might need to be repositioned.  For example, it might be
   310    282   syntactically desirable to rearrange the sentence structure
   311    283   while translating.
   312    284   .CS
   313    285   format "We produced %d units in location %s" $num $city
   314    286   format "In location %s we produced %d units" $city $num
   315    287   .CE
   316    288   .PP
   317         -This can be handled by using the positional parameters:
          289  +This can be handled by using the positional
          290  +parameters:
   318    291   .CS
   319    292   format "We produced %1\\$d units in location %2\\$s" $num $city
   320    293   format "In location %2\\$s we produced %1\\$d units" $num $city
   321    294   .CE
   322    295   .PP
   323    296   Similarly, positional parameters can be used with \fBscan\fR to
   324    297   extract values from internationalized strings.
   325         -.PP
   326         -\fINote:\fR for the specific case of formatting a string, you should
   327         -take advantage of the fact that the \fB::msgcat::mc\fR command already
   328         -passes its string through \fBformat\fR internally.
   329    298   .SH CREDITS
   330    299   .PP
   331    300   The message catalog code was developed by Mark Harrison.
          301  +
   332    302   .SH "SEE ALSO"
   333    303   format(n), scan(n), namespace(n), package(n)
          304  +
   334    305   .SH KEYWORDS
   335    306   internationalization, i18n, localization, l10n, message, text, translation

Changes to doc/namespace.n.

     3      3   '\" Copyright (c) 1997 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2000 Scriptics Corporation.
     5      5   '\" Copyright (c) 2004-2005 Donal K. Fellows.
     6      6   '\"
     7      7   '\" See the file "license.terms" for information on usage and redistribution
     8      8   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     9      9   '\" 
    10         -'\" RCS: @(#) $Id: namespace.n,v 1.22 2007/10/24 14:29:38 dkf Exp $
           10  +'\" RCS: @(#) $Id: namespace.n,v 1.23 2007/10/26 20:11:53 dgp Exp $
    11     11   '\" 
    12     12   .so man.macros
    13     13   .TH namespace n 8.5 Tcl "Tcl Built-In Commands"
    14     14   .BS
    15         -.\" Note:  do not modify the .SH NAME line immediately below!
           15  +'\" Note:  do not modify the .SH NAME line immediately below!
    16     16   .SH NAME
    17     17   namespace \- create and manipulate contexts for commands and variables
    18     18   .SH SYNOPSIS
    19     19   \fBnamespace \fR?\fIoption\fR? ?\fIarg ...\fR?
    20     20   .BE
    21     21   
    22     22   .SH DESCRIPTION
................................................................................
    51     51   The new script has two important properties.
    52     52   First, it can be evaluated in any namespace and will cause
    53     53   \fIscript\fR to be evaluated in the current namespace
    54     54   (the one where the \fBnamespace code\fR command was invoked).
    55     55   Second, additional arguments can be appended to the resulting script
    56     56   and they will be passed to \fIscript\fR as additional arguments.
    57     57   For example, suppose the command
    58         -.QW "\fBset script [namespace code {foo bar}]\fR"
           58  +\fBset script [namespace code {foo bar}]\fR
    59     59   is invoked in namespace \fB::a::b\fR.
    60         -Then
    61         -.QW \fBeval\0"$script\0x\0y"\fR
           60  +Then \fBeval "$script x y"\fR
    62     61   can be executed in any namespace (assuming the value of
    63     62   \fBscript\fR has been passed in properly)
    64     63   and will have the same effect as the command
    65     64   \fB::namespace eval ::a::b {foo bar x y}\fR.
    66     65   This command is needed because
    67     66   extensions like Tk normally execute callback scripts
    68     67   in the global namespace.
................................................................................
    69     68   A scoped command captures a command together with its namespace context
    70     69   in a way that allows it to be executed properly later.
    71     70   See the section \fBSCOPED SCRIPTS\fR for some examples
    72     71   of how this is used to create callback scripts.
    73     72   .TP
    74     73   \fBnamespace current\fR
    75     74   Returns the fully-qualified name for the current namespace.
    76         -The actual name of the global namespace is
    77         -.MT
           75  +The actual name of the global namespace is ``''
    78     76   (i.e., an empty string),
    79     77   but this command returns \fB::\fR for the global namespace
    80     78   as a convenience to programmers.
    81     79   .TP
    82     80   \fBnamespace delete \fR?\fInamespace namespace ...\fR?
    83     81   Each namespace \fInamespace\fR is deleted
    84     82   and all variables, procedures, and child namespaces
................................................................................
   216    214   \fBnamespace parent\fR ?\fInamespace\fR?
   217    215   Returns the fully-qualified name of the parent namespace
   218    216   for namespace \fInamespace\fR.
   219    217   If \fInamespace\fR is not specified,
   220    218   the fully-qualified name of the current namespace's parent is returned.
   221    219   .TP
   222    220   \fBnamespace path\fR ?\fInamespaceList\fR?
   223         -.\" Should really have the .TP inside the .VS, but that triggers a groff bug
          221  +'\" Should really have the .TP inside the .VS, but that triggers a groff bug
   224    222   .VS 8.5
   225    223   Returns the command resolution path of the current namespace. If
   226    224   \fInamespaceList\fR is specified as a list of named namespaces, the
   227    225   current namespace's command resolution path is set to those namespaces
   228    226   and returns the empty list. The default command resolution path is
   229    227   always empty. See the section \fBNAME RESOLUTION\fR below for an
   230    228   explanation of the rules regarding name resolution.
................................................................................
   357    355   Since namespaces may nest,
   358    356   qualified names are used to refer to
   359    357   commands, variables, and child namespaces contained inside namespaces.
   360    358   Qualified names are similar to the hierarchical path names for
   361    359   Unix files or Tk widgets,
   362    360   except that \fB::\fR is used as the separator
   363    361   instead of \fB/\fR or \fB.\fR.
   364         -The topmost or global namespace has the name
   365         -.MT
   366         -(i.e., an empty string), although \fB::\fR is a synonym.
          362  +The topmost or global namespace has the name ``'' (i.e., an empty string),
          363  +although \fB::\fR is a synonym.
   367    364   As an example, the name \fB::safe::interp::create\fR
   368    365   refers to the command \fBcreate\fR in the namespace \fBinterp\fR
   369    366   that is a child of namespace \fB::safe\fR,
   370    367   which in turn is a child of the global namespace, \fB::\fR.
   371    368   .PP
   372    369   If you want to access commands and variables from another namespace,
   373    370   you must use some extra syntax.
................................................................................
   830    827   foobar grill
   831    828   .CE
   832    829   .PP
   833    830   Look up where the command imported in the previous example came from:
   834    831   .CS
   835    832   puts "grill came from [\fBnamespace origin\fR grill]"
   836    833   .CE
          834  +
   837    835   .SH "SEE ALSO"
   838    836   interp(n), upvar(n), variable(n)
          837  +
   839    838   .SH KEYWORDS
   840    839   command, ensemble, exported, internal, variable

Changes to doc/open.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: open.n,v 1.29 2007/10/24 14:29:38 dkf Exp $
            8  +'\" RCS: @(#) $Id: open.n,v 1.30 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH open n 8.3 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13         -.\" Note:  do not modify the .SH NAME line immediately below!
           13  +'\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   open \- Open a file-based or command pipeline channel
    16     16   .SH SYNOPSIS
    17     17   .sp
    18     18   \fBopen \fIfileName\fR
    19     19   .br
    20     20   \fBopen \fIfileName access\fR
................................................................................
    62     62   create a new empty file.
    63     63   Set the initial access position  to the end of the file.
    64     64   .VS 8.5
    65     65   .PP
    66     66   All of the legal \fIaccess\fR values above may have the character
    67     67   \fBb\fR added as the second or third character in the value to
    68     68   indicate that the opened channel should be configured with the
    69         -\fB\-translation binary\fR option, making the channel suitable for 
           69  +\fB-translation binary\fR option, making the channel suitable for 
    70     70   reading or writing of binary data.
    71     71   .VE 8.5
    72     72   .PP
    73     73   In the second form, \fIaccess\fR consists of a list of any of the
    74     74   following flags, all of which have the standard POSIX meanings.
    75     75   One of the flags must be either \fBRDONLY\fR, \fBWRONLY\fR or \fBRDWR\fR.
    76     76   .TP 15
................................................................................
    84     84   Open the file for both reading and writing.
    85     85   .TP 15
    86     86   \fBAPPEND\fR
    87     87   Set the file pointer to the end of the file prior to each write.
    88     88   .VS 8.5
    89     89   .TP 15
    90     90   \fBBINARY\fR
    91         -Configure the opened channel with the \fB\-translation binary\fR option.
           91  +Configure the opened channel with the \fB-translation binary\fR option.
    92     92   .VE 8.5
    93     93   .TP 15
    94     94   \fBCREAT\fR
    95     95   Create the file if it doesn't already exist (without this flag it
    96     96   is an error for the file not to exist).
    97     97   .TP 15
    98     98   \fBEXCL\fR
................................................................................
   115    115   \fBTRUNC\fR
   116    116   If the file exists it is truncated to zero length.
   117    117   .PP
   118    118   If a new file is created as part of opening it, \fIpermissions\fR
   119    119   (an integer) is used to set the permissions for the new file in
   120    120   conjunction with the process's file mode creation mask.
   121    121   \fIPermissions\fR defaults to 0666.
          122  +
   122    123   .SH "COMMAND PIPELINES"
   123    124   .PP
   124         -If the first character of \fIfileName\fR is
   125         -.QW |
   126         -then the remaining characters of \fIfileName\fR are treated as a list of
   127         -arguments that describe a command pipeline to invoke, in the same style as the
          125  +If the first character of \fIfileName\fR is ``|'' then the
          126  +remaining characters of \fIfileName\fR are treated as a list of arguments
          127  +that describe a command pipeline to invoke, in the same style as the
   128    128   arguments for \fBexec\fR.
   129    129   In this case, the channel identifier returned by \fBopen\fR may be used
   130    130   to write to the command's input pipe or read from its output pipe,
   131    131   depending on the value of \fIaccess\fR.
   132    132   If write-only access is used (e.g. \fIaccess\fR is \fBw\fR), then
   133    133   standard output for the pipeline is directed to the current standard
   134    134   output unless overridden by the command.
................................................................................
   158    158   configuration options specific to serial ports (where supported):
   159    159   .TP
   160    160   \fB\-mode\fR \fIbaud\fB,\fIparity\fB,\fIdata\fB,\fIstop\fR
   161    161   This option is a set of 4 comma-separated values: the baud rate, parity,
   162    162   number of data bits, and number of stop bits for this serial port.  The
   163    163   \fIbaud\fR rate is a simple integer that specifies the connection speed.
   164    164   \fIParity\fR is one of the following letters: \fBn\fR, \fBo\fR, \fBe\fR,
   165         -\fBm\fR, \fBs\fR; respectively signifying the parity options of
   166         -.QW none ,
   167         -.QW odd ,
   168         -.QW even ,
   169         -.QW mark ,
   170         -or
   171         -.QW space .
   172         -\fIData\fR is the number of data bits and should be an integer from 5 to 8,
   173         -while \fIstop\fR is the number of stop bits and should be the integer 1 or 2.
          165  +\fBm\fR, \fBs\fR; respectively signifying the parity options of ``none'',
          166  +``odd'', ``even'', ``mark'', or ``space''.  \fIData\fR is the number of
          167  +data bits and should be an integer from 5 to 8, while \fIstop\fR is the
          168  +number of stop bits and should be the integer 1 or 2.
   174    169   .TP
   175    170   \fB\-handshake\fR \fItype\fR
   176    171   (Windows and Unix). This option is used to setup automatic handshake
   177    172   control. Note that not all handshake types maybe supported by your operating
   178    173   system. The \fItype\fR parameter is case-independent.
   179    174   .sp
   180    175   If \fItype\fR is \fBnone\fR then any handshake is switched off.
   181    176   \fBrtscts\fR activates hardware handshake. Hardware handshake signals
   182    177   are described below.
   183    178   For software handshake \fBxonxoff\fR the handshake characters can be redefined
   184         -with \fB\-xchar\fR.
          179  +with \fB-xchar\fR.
   185    180   An additional hardware handshake \fBdtrdsr\fR is available only under Windows.
   186    181   There is no default handshake configuration, the initial value depends
   187    182   on your operating system settings.
   188         -The \fB\-handshake\fR option cannot be queried.
          183  +The \fB-handshake\fR option cannot be queried.
   189    184   .TP
   190    185   \fB\-queue\fR
   191         -(Windows and Unix). The \fB\-queue\fR option can only be queried.
          186  +(Windows and Unix). The \fB-queue\fR option can only be queried.
   192    187   It returns a list of two integers representing the current number
   193    188   of bytes in the input and output queue respectively.
   194    189   .TP
   195    190   \fB\-timeout\fR \fImsec\fR
   196    191   (Windows and Unix). This option is used to set the timeout for blocking
   197    192   read operations. It specifies the maximum interval between the
   198    193   reception of two bytes in milliseconds.
   199    194   For Unix systems the granularity is 100 milliseconds.
   200         -The \fB\-timeout\fR option does not affect write operations or
          195  +The \fB-timeout\fR option does not affect write operations or
   201    196   nonblocking reads.
   202    197   This option cannot be queried.
   203    198   .TP
   204    199   \fB\-ttycontrol\fR \fI{signal boolean signal boolean ...}\fR
   205    200   (Windows and Unix). This option is used to setup the handshake
   206    201   output lines (see below) permanently or to send a BREAK over the serial line.
   207    202   The \fIsignal\fR names are case-independent.
   208    203   \fB{RTS 1 DTR 0}\fR sets the RTS output to high and the DTR output to low.
   209    204   The BREAK condition (see below) is enabled and disabled with \fB{BREAK 1}\fR and
   210    205   \fB{BREAK 0}\fR respectively.
   211    206   It's not a good idea to change the \fBRTS\fR (or \fBDTR\fR) signal
   212    207   with active hardware handshake \fBrtscts\fR (or \fBdtrdsr\fR).
   213    208   The result is unpredictable.
   214         -The \fB\-ttycontrol\fR option cannot be queried.
          209  +The \fB-ttycontrol\fR option cannot be queried.
   215    210   .TP
   216    211   \fB\-ttystatus\fR
   217         -(Windows and Unix). The \fB\-ttystatus\fR option can only be
          212  +(Windows and Unix). The \fB-ttystatus\fR option can only be
   218    213   queried.  It returns the current modem status and handshake input signals
   219    214   (see below).
   220    215   The result is a list of signal,value pairs with a fixed order,
   221    216   e.g. \fB{CTS 1 DSR 0 RING 1 DCD 0}\fR.
   222    217   The \fIsignal\fR names are returned upper case.
   223    218   .TP
   224    219   \fB\-xchar\fR \fI{xonChar xoffChar}\fR
................................................................................
   246    241   .TP
   247    242   \fB\-lasterror\fR
   248    243   (Windows only). This option is query only.
   249    244   In case of a serial communication error, \fBread\fR or \fBputs\fR
   250    245   returns a general Tcl file I/O error.
   251    246   \fBfconfigure -lasterror\fR can be called to get a list of error details.
   252    247   See below for an explanation of the various error codes.
          248  +
   253    249   .SH "SERIAL PORT SIGNALS"
   254    250   .PP
   255    251   RS-232 is the most commonly used standard electrical interface for serial
   256    252   communications. A negative voltage (-3V..-12V) define a mark (on=1) bit and
   257    253   a positive voltage (+3..+12V) define a space (off=0) bit (RS-232C).  The
   258    254   following signals are specified for incoming and outgoing data, status
   259    255   lines and handshaking. Here we are using the terms \fIworkstation\fR for
................................................................................
   276    272   \fBData Terminal Ready:\fR This signal tells the modem that the workstation
   277    273   is ready to establish a link. DTR is often enabled automatically whenever a
   278    274   serial port is opened.
   279    275   .IP \fBDSR(input)\fR
   280    276   \fBData Set Ready:\fR The complement to DTR. Tells the workstation that the
   281    277   modem is ready to establish a link.
   282    278   .IP \fBDCD(input)\fR
   283         -\fBData Carrier Detect:\fR This line becomes active when a modem detects a
   284         -.QW Carrier
   285         -signal.
          279  +\fBData Carrier Detect:\fR This line becomes active when a modem detects
          280  +a "Carrier" signal.
   286    281   .IP \fBRI(input)\fR
   287    282   \fBRing Indicator:\fR Goes active when the modem detects an incoming call.
   288    283   .IP \fBBREAK\fR
   289    284   A BREAK condition is not a hardware signal line, but a logical zero on the
   290    285   TXD or RXD lines for a long period of time, usually 250 to 500
   291    286   milliseconds.  Normally a receive or transmit data signal stays at the mark
   292    287   (on=1) voltage until the next character is transferred. A BREAK is sometimes
   293    288   used to reset the communications line or change the operating mode of
   294    289   communications hardware.
          290  +
   295    291   .SH "ERROR CODES (Windows only)"
   296    292   .PP
   297    293   A lot of different errors may occur during serial read operations or during
   298    294   event polling in background. The external device may have been switched
   299    295   off, the data lines may be noisy, system buffers may overrun or your mode
   300    296   settings may be wrong.  That's why a reliable software should always
   301    297   \fBcatch\fR serial read operations.  In cases of an error Tcl returns a
................................................................................
   326    322   \fBFRAME\fR
   327    323   A stop-bit error has been detected by your UART.
   328    324   Wrong mode settings with \fBfconfigure -mode\fR or a noisy data line (RXD)
   329    325   may cause this error.
   330    326   .TP 10
   331    327   \fBBREAK\fR
   332    328   A BREAK condition has been detected by your UART (see above).
          329  +
   333    330   .SH "PORTABILITY ISSUES"
   334    331   .TP
   335    332   \fBWindows \fR(all versions)
   336         -.
   337    333   Valid values for \fIfileName\fR to open a serial port are of the form
   338    334   \fBcom\fIX\fB:\fR, where \fIX\fR is a number, generally from 1 to 4.
   339    335   This notation only works for serial ports from 1 to 9, if the system
   340    336   happens to have more than four.  An attempt to open a serial port that
   341    337   does not exist or has a number greater than 9 will fail.  An alternate
   342    338   form of opening serial ports is to use the filename \fB\e\e.\ecomX\fR,
   343    339   where X is any number that corresponds to a serial port; please note
   344    340   that this method is considerably slower on Windows 95 and Windows 98.
   345    341   .TP
   346    342   \fBWindows NT\fR
   347         -.
   348    343   When running Tcl interactively, there may be some strange interactions
   349    344   between the real console, if one is present, and a command pipeline that uses
   350    345   standard input or output.  If a command pipeline is opened for reading, some
   351    346   of the lines entered at the console will be sent to the command pipeline and
   352    347   some will be sent to the Tcl evaluator.  If a command pipeline is opened for
   353    348   writing, keystrokes entered into the console are not visible until the
   354    349   pipe is closed.  This behavior occurs whether the command pipeline is
................................................................................
   355    350   executing 16-bit or 32-bit applications.  These problems only occur because
   356    351   both Tcl and the child application are competing for the console at
   357    352   the same time.  If the command pipeline is started from a script, so that Tcl
   358    353   is not accessing the console, or if the command pipeline does not use
   359    354   standard input or output, but is redirected from or to a file, then the
   360    355   above problems do not occur.  
   361    356   .TP
   362         -\fBWindows 95\fR
   363         -.
          357  +\fBWindows 95\fR 
   364    358   A command pipeline that executes a 16-bit DOS application cannot be opened
   365    359   for both reading and writing, since 16-bit DOS applications that receive
   366    360   standard input from a pipe and send standard output to a pipe run
   367    361   synchronously.  Command pipelines that do not execute 16-bit DOS
   368    362   applications run asynchronously and can be opened for both reading and
   369    363   writing.  
   370         -.RS
   371         -.PP
          364  +.sp
   372    365   When running Tcl interactively, there may be some strange interactions
   373    366   between the real console, if one is present, and a command pipeline that uses
   374    367   standard input or output.  If a command pipeline is opened for reading from
   375    368   a 32-bit application, some of the keystrokes entered at the console will be
   376    369   sent to the command pipeline and some will be sent to the Tcl evaluator.  If
   377    370   a command pipeline is opened for writing to a 32-bit application, no output
   378    371   is visible on the console until the pipe is closed.  These problems only
   379    372   occur because both Tcl and the child application are competing for the
   380    373   console at the same time.  If the command pipeline is started from a script,
   381    374   so that Tcl is not accessing the console, or if the command pipeline does
   382    375   not use standard input or output, but is redirected from or to a file, then
   383    376   the above problems do not occur.  
   384         -.PP
          377  +.sp
   385    378   Whether or not Tcl is running interactively, if a command pipeline is opened
   386    379   for reading from a 16-bit DOS application, the call to \fBopen\fR will not
   387    380   return until end-of-file has been received from the command pipeline's
   388    381   standard output.  If a command pipeline is opened for writing to a 16-bit DOS
   389    382   application, no data will be sent to the command pipeline's standard output
   390    383   until the pipe is actually closed.  This problem occurs because 16-bit DOS
   391    384   applications are run synchronously, as described above.  
   392         -.RE
   393    385   .TP
   394    386   \fBUnix\fR\0\0\0\0\0\0\0
   395         -.
   396    387   Valid values for \fIfileName\fR to open a serial port are generally of the
   397    388   form \fB/dev/tty\fIX\fR, where \fIX\fR is \fBa\fR or \fBb\fR, but the name
   398    389   of any pseudo-file that maps to a serial port may be used.
   399    390   Advanced configuration options are only supported for serial ports
   400    391   when Tcl is built to use the POSIX serial interface.
   401         -.RS
   402         -.PP
          392  +.sp
   403    393   When running Tcl interactively, there may be some strange interactions
   404    394   between the console, if one is present, and a command pipeline that uses
   405    395   standard input.  If a command pipeline is opened for reading, some
   406    396   of the lines entered at the console will be sent to the command pipeline and
   407    397   some will be sent to the Tcl evaluator.  This problem only occurs because
   408    398   both Tcl and the child application are competing for the console at the
   409    399   same time.  If the command pipeline is started from a script, so that Tcl is
   410    400   not accessing the console, or if the command pipeline does not use standard
   411    401   input, but is redirected from a file, then the above problem does not occur.  
   412         -.RE
   413    402   .LP
   414    403   See the PORTABILITY ISSUES section of the \fBexec\fR command for additional
   415    404   information not specific to command pipelines about executing
   416    405   applications on the various platforms
   417    406   .SH "EXAMPLE"
   418    407   Open a command pipeline and catch any errors:
   419    408   .CS
   420    409   set fl [\fBopen\fR "| ls this_file_does_not_exist"]
   421    410   set data [read $fl]
   422    411   if {[catch {close $fl} err]} {
   423    412       puts "ls command failed: $err"
   424    413   }
   425    414   .CE
          415  +
   426    416   .SH "SEE ALSO"
   427         -chan(n), close(n), exec(n), fconfigure(n), file(n), filename(n), gets(n),
   428         -pid(n), puts(n), read(n), fopen(3)
          417  +file(n), close(n), filename(n), fconfigure(n), gets(n), read(n),
          418  +puts(n), exec(n), pid(n), fopen(3)
          419  +
   429    420   .SH KEYWORDS
   430    421   access mode, append, create, file, non-blocking, open, permissions,
   431    422   pipeline, process, serial

Changes to doc/package.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1996 Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: package.n,v 1.19 2007/10/25 10:13:35 dkf Exp $
            7  +'\" RCS: @(#) $Id: package.n,v 1.20 2007/10/26 20:11:53 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH package n 7.5 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   package \- Facilities for package loading and version control
................................................................................
    25     25   \fBpackage unknown \fR?\fIcommand\fR?
    26     26   \fBpackage vcompare \fIversion1 version2\fR
    27     27   \fBpackage versions \fIpackage\fR
    28     28   \fBpackage vsatisfies \fIversion requirement...\fR
    29     29   \fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR?
    30     30   .fi
    31     31   .BE
           32  +
    32     33   .SH DESCRIPTION
    33     34   .PP
    34     35   This command keeps a simple database of the packages available for
    35     36   use by the current interpreter and how to load them into the
    36     37   interpreter.
    37     38   It supports multiple versions of each package and arranges
    38     39   for the correct version of a package to be loaded based on what
................................................................................
   105    106   .PP
   106    107   A suitable version of the package is any version which satisfies at
   107    108   least one of the requirements, per the rules of \fBpackage
   108    109   vsatisfies\fR. If multiple versions are suitable the implementation
   109    110   with the highest version is chosen. This last part is additionally
   110    111   influenced by the selection mode set with \fBpackage prefer\fR.
   111    112   .PP
   112         -In the
   113         -.QW "stable"
   114         -selection mode the command will select the highest
          113  +In the "stable" selection mode the command will select the highest
   115    114   stable version satisfying the requirements, if any. If no stable
   116    115   version satisfies the requirements, the highest unstable version
   117         -satisfying the requirements will be selected.  In the
   118         -.QW "latest"
          116  +satisfying the requirements will be selected.  In the "latest"
   119    117   selection mode the command will accept the highest version satisfying
   120    118   all the requirements, regardless of its stableness.
   121    119   .PP
   122    120   If a version of \fIpackage\fR has already been provided (by invoking
   123    121   the \fBpackage provide\fR command), then its version number must
   124    122   satisfy the \fIrequirement\fRs and the command returns immediately.
   125    123   Otherwise, the command searches the database of information provided by
................................................................................
   141    139   .TP
   142    140   \fBpackage require \-exact \fIpackage version\fR
   143    141   This form of the command is used when only the given \fIversion\fR
   144    142   of \fIpackage\fR is acceptable to the caller.  This command is
   145    143   equivalent to \fBpackage require \fIpackage version\fR-\fIversion\fR.
   146    144   .TP
   147    145   \fBpackage unknown \fR?\fIcommand\fR?
   148         -.
   149         -This command supplies a
   150         -.QW "last resort"
   151         -command to invoke during
          146  +This command supplies a ``last resort'' command to invoke during
   152    147   \fBpackage require\fR if no suitable version of a package can be found
   153    148   in the \fBpackage ifneeded\fR database.
   154    149   If the \fIcommand\fR argument is supplied, it contains the first part
   155    150   of a command;  when the command is invoked during a \fBpackage require\fR
   156    151   command, Tcl appends one or more additional arguments giving the desired
   157    152   package name and requirements.
   158    153   For example, if \fIcommand\fR is \fBfoo bar\fR and later the command
................................................................................
   179    174   \fBpackage vsatisfies \fIversion requirement...\fR
   180    175   Returns 1 if the \fIversion\fR satisfies at least one of the given
   181    176   requirements, and 0 otherwise. Each \fIrequirement\fR is allowed to
   182    177   have any of the forms:
   183    178   .RS
   184    179   .TP
   185    180   min
   186         -This form is called
   187         -.QW "min-bounded" .
          181  +This form is called "min-bounded".
   188    182   .TP
   189    183   min-
   190         -This form is called
   191         -.QW "min-unbound" .
          184  +This form is called "min-unbound".
   192    185   .TP
   193    186   min-max
   194         -This form is called
   195         -.QW "bounded" .
          187  +This form is called "bounded".
   196    188   .RE
   197    189   .RS
   198    190   .PP
   199         -where
   200         -.QW "min"
   201         -and
   202         -.QW "max"
   203         -are valid version numbers. The legacy syntax is
          191  +where "min" and "max" are valid version numbers. The legacy syntax is
   204    192   a special case of the extended syntax, keeping backward
   205    193   compatibility. Regarding satisfaction the rules are:
   206    194   .RE
   207    195   .RS
   208    196   .IP [1]
   209    197   The \fIversion\fR has to pass at least one of the listed
   210    198   \fIrequirement\fRs to be satisfactory.
   211    199   .IP [2]
   212         -A version satisfies a
   213         -.QW "bounded"
   214         -requirement when
          200  +A version satisfies a "bounded" requirement when
   215    201   .RS
   216    202   .IP [a]
   217    203   For \fImin\fR equal to the \fImax\fR if, and only if the \fIversion\fR
   218    204   is equal to the \fImin\fR.
   219    205   .IP [b]
   220    206   Otherwise if, and only if the \fIversion\fR is greater than or equal
   221    207   to the \fImin\fR, and less than the \fImax\fR, where both \fImin\fR
   222         -and \fImax\fR have been padded internally with
   223         -.QW a0 .
   224         -Note that while the comparison to \fImin\fR is inclusive, the comparison to
          208  +and \fImax\fR have been padded internally with 'a0'. Note that while
          209  +the comparison to \fImin\fR is inclusive, the comparison to
   225    210   \fImax\fR is exclusive.
   226    211   .RE
   227    212   .IP [3]
   228         -A
   229         -.QW "min-bounded"
   230         -requirement is a
   231         -.QW "bounded"
   232         -requirement in disguise,
          213  +A "min-bounded" requirement is a "bounded" requirement in disguise,
   233    214   with the \fImax\fR part implicitly specified as the next higher major
   234    215   version number of the \fImin\fR part. A version satisfies it per the
   235    216   rules above.
   236    217   .IP [4]
   237         -A \fIversion\fR satisfies a
   238         -.QW "min-unbound"
   239         -requirement if, and only if
          218  +A \fIversion\fR satisfies a "min-unbound" requirement if, and only if
   240    219   it is greater than or equal to the \fImin\fR, where the \fImin\fR has
   241         -been padded internally with
   242         -.QW a0 .
   243         -There is no constraint to a maximum.
          220  +been padded internally with 'a0'. There is no constraint to a maximum.
   244    221   .RE
   245    222   .TP
   246    223   \fBpackage prefer \fR?\fBlatest\fR|\fBstable\fR?
   247         -With no arguments, the commands returns either
   248         -.QW "latest"
   249         -or
   250         -.QW "stable" ,
          224  +With no arguments, the commands returns either "latest" or "stable",
   251    225   whichever describes the current mode of selection logic used by
   252    226   \fBpackage require\fR.
   253    227   .RS
   254    228   .PP
   255         -When passed the argument
   256         -.QW "latest" ,
   257         -it sets the selection logic mode to
   258         -.QW "latest" .
          229  +When passed the argument "latest", it sets the selection logic mode to
          230  +"latest".
   259    231   .PP
   260         -When passed the argument
   261         -.QW "stable" ,
   262         -if the mode is already
   263         -.QW "stable" ,
   264         -that value is kept.  If the mode is already
   265         -.QW "latest" , then the attempt to set it back to
   266         -.QW "stable"
   267         -is ineffective and the mode value remains
   268         -.QW "latest" .
          232  +When passed the argument "stable", if the mode is already "stable",
          233  +that value is kept.  If the mode is already "latest", then the attempt
          234  +to set it back to "stable" is ineffective and the mode value remains
          235  +"latest".
   269    236   .PP
   270    237   When passed any other value as an argument, raise an invalid argument
   271    238   error.
   272    239   .PP
   273    240   When an interpreter is created, its initial selection mode value is set to
   274         -.QW "stable"
   275         -unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR
          241  +"stable" unless the environment variable \fBTCL_PKG_PREFER_LATEST\fR
   276    242   is set.  If that environment variable is defined (with any value) then
   277         -the initial (and permanent) selection mode value is set to
   278         -.QW "latest" .
          243  +the initial (and permanent) selection mode value is set to "latest".
   279    244   .RE
   280    245   .SH "VERSION NUMBERS"
   281    246   .PP
   282    247   Version numbers consist of one or more decimal numbers separated
   283    248   by dots, such as 2 or 1.162 or 3.1.13.1.
   284    249   The first number is called the major version number.
   285    250   Larger numbers correspond to later versions of a package, with
   286    251   leftmost numbers having greater significance.
   287    252   For example, version 2.1 is later than 1.3 and version
   288    253   3.4.6 is later than 3.3.5.
   289    254   Missing fields are equivalent to zeroes:  version 1.3 is the
   290    255   same as version 1.3.0 and 1.3.0.0, so it is earlier than 1.3.1 or 1.3.0.2.
   291         -In addition, the letters
   292         -.QW a
   293         -(alpha) and/or
   294         -.QW b
   295         -(beta) may appear
          256  +In addition, the letters 'a' (alpha) and/or 'b' (beta) may appear
   296    257   exactly once to replace a dot for separation. These letters
   297         -semantically add a negative specifier into the version, where
   298         -.QW a
   299         -is -2, and
   300         -.QW b
   301         -is -1. Each may be specified only once, and
   302         -.QW a
   303         -and
   304         -.QW b
   305         -are mutually exclusive in a specifier. Thus 1.3a1 becomes (semantically)
          258  +semantically add a negative specifier into the version, where 'a' is
          259  +-2, and 'b' is -1. Each may be specified only once, and 'a' or 'b' are
          260  +mutually exclusive in a specifier. Thus 1.3a1 becomes (semantically)
   306    261   1.3.-2.1, 1.3b1 is 1.3.-1.1. Negative numbers are not directly allowed
   307    262   in version specifiers.
   308         -A version number not containing the letters
   309         -.QW a
   310         -or
   311         -.QW b
   312         -as specified above is called a \fBstable\fR version, whereas presence
   313         -of the letters causes the version to be called is \fBunstable\fR.
          263  +A version number not containing the letters 'a' or 'b' as specified
          264  +above is called a \fBstable\fR version, whereas presence of the letters
          265  +causes the version to be called is \fBunstable\fR.
   314    266   A later version number is assumed to be upwards compatible with
   315    267   an earlier version number as long as both versions have the same
   316    268   major version number.
   317    269   For example, Tcl scripts written for version 2.3 of a package should
   318    270   work unchanged under versions 2.3.2, 2.4, and 2.5.1.
   319    271   Changes in the major version number signify incompatible changes:
   320    272   if code is written to use version 2.1 of a package, it is not guaranteed
   321    273   to work unmodified with either version 1.7.3 or version 3.1.
   322    274   .SH "PACKAGE INDICES"
   323    275   .PP
   324    276   The recommended way to use packages in Tcl is to invoke \fBpackage require\fR
   325    277   and \fBpackage provide\fR commands in scripts, and use the procedure
   326    278   \fBpkg_mkIndex\fR to create package index files.
   327         -Once you have done this, packages will be loaded automatically
          279  +Once you've done this, packages will be loaded automatically
   328    280   in response to \fBpackage require\fR commands.
   329    281   See the documentation for \fBpkg_mkIndex\fR for details.
   330    282   .SH EXAMPLES
   331    283   To state that a Tcl script requires the Tk and http packages, put this
   332    284   at the top of the script:
   333    285   .CS
   334    286   \fBpackage require\fR Tk
................................................................................
   342    294   if {[catch {\fBpackage require\fR Snack}]} {
   343    295      # Error thrown - package not found.
   344    296      # Set up a dummy interface to work around the absence
   345    297   } else {
   346    298      # We have the package, configure the app to use it
   347    299   }
   348    300   .CE
          301  +
   349    302   .SH "SEE ALSO"
   350    303   msgcat(n), packagens(n), pkgMkIndex(n)
          304  +
   351    305   .SH KEYWORDS
   352    306   package, version

Changes to doc/packagens.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1998-2000 by Scriptics Corporation.
     3      3   '\" All rights reserved.
     4      4   '\" 
     5         -'\" RCS: @(#) $Id: packagens.n,v 1.6 2007/10/24 14:29:38 dkf Exp $
            5  +'\" RCS: @(#) $Id: packagens.n,v 1.7 2007/10/26 20:11:53 dgp Exp $
     6      6   '\" 
     7      7   .so man.macros
     8      8   .TH pkg::create n 8.3 Tcl "Tcl Built-In Commands"
     9      9   .BS
    10     10   '\" Note:  do not modify the .SH NAME line immediately below!
    11     11   .SH NAME
    12     12   pkg::create \- Construct an appropriate `package ifneeded' command for a given package specification
................................................................................
    16     16   
    17     17   .SH DESCRIPTION
    18     18   .PP
    19     19   \fB::pkg::create\fR is a utility procedure that is part of the standard Tcl
    20     20   library.  It is used to create an appropriate \fBpackage ifneeded\fR
    21     21   command for a given package specification.  It can be used to construct a
    22     22   \fBpkgIndex.tcl\fR file for use with the \fBpackage\fR mechanism.
           23  +
    23     24   .SH OPTIONS
    24     25   The parameters supported are:
    25     26   .TP
    26     27   \fB\-name\fR\0\fIpackageName\fR
    27     28   This parameter specifies the name of the package.  It is required.
    28     29   .TP
    29     30   \fB\-version\fR\0\fIpackageVersion\fR
................................................................................
    41     42   \fB\-source\fR\0\fIfilespec\fR
    42     43   This parameter is similar to the \fB\-load\fR parameter, except that it
    43     44   specifies a Tcl library that must be loaded with the
    44     45   \fBsource\fR command.  Any number of \fB\-source\fR parameters may be
    45     46   specified.
    46     47   .PP
    47     48   At least one \fB\-load\fR or \fB\-source\fR parameter must be given.
           49  +
    48     50   .SH "SEE ALSO"
    49     51   package(n)
           52  +
    50     53   .SH KEYWORDS
    51     54   auto-load, index, package, version

Changes to doc/pkgMkIndex.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1996 Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.19 2007/10/24 14:29:38 dkf Exp $
            7  +'\" RCS: @(#) $Id: pkgMkIndex.n,v 1.20 2007/10/26 20:11:53 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH pkg_mkIndex n 8.3 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   pkg_mkIndex \- Build an index for automatic loading of packages
................................................................................
    36     36   a call to \fBTcl_PkgProvide\fR.
    37     37   .IP [2]
    38     38   Create the index by invoking \fBpkg_mkIndex\fR.
    39     39   The \fIdir\fR argument gives the name of a directory and each
    40     40   \fIpattern\fR argument is a \fBglob\fR-style pattern that selects
    41     41   script or binary files in \fIdir\fR.
    42     42   The default pattern is \fB*.tcl\fR and \fB*.[info sharedlibextension]\fR.
    43         -.RS
    44         -.PP
           43  +.br
    45     44   \fBPkg_mkIndex\fR will create a file \fBpkgIndex.tcl\fR in \fIdir\fR
    46     45   with package information about all the files given by the \fIpattern\fR
    47     46   arguments.
    48     47   It does this by loading each file into a slave
    49     48   interpreter and seeing what packages
    50     49   and new commands appear (this is why it is essential to have
    51     50   \fBpackage provide\fR commands or \fBTcl_PkgProvide\fR calls
    52     51   in the files, as described above).
    53     52   If you have a package split among scripts and binary files, 
    54     53   or if you have dependencies among files,
    55     54   you may have to use the \fB\-load\fR option
    56     55   or adjust the order in which \fBpkg_mkIndex\fR processes
    57     56   the files.  See COMPLEX CASES below.
    58         -.RE
           57  +
    59     58   .IP [3]
    60     59   Install the package as a subdirectory of one of the directories given by
    61     60   the \fBtcl_pkgPath\fR variable.  If \fB$tcl_pkgPath\fR contains more
    62     61   than one directory, machine-dependent packages (e.g., those that
    63     62   contain binary shared libraries) should normally be installed
    64     63   under the first directory and machine-independent packages (e.g.,
    65     64   those that contain only Tcl scripts) should be installed under the
    66     65   second directory.
    67     66   The subdirectory should include
    68     67   the package's script and/or binary files as well as the \fBpkgIndex.tcl\fR
    69     68   file.  As long as the package is installed as a subdirectory of a
    70     69   directory in \fB$tcl_pkgPath\fR it will automatically be found during
    71     70   \fBpackage require\fR commands.
    72         -.RS
    73         -.PP
           71  +.br
    74     72   If you install the package anywhere else, then you must ensure that
    75     73   the directory containing the package is in the \fBauto_path\fR global variable
    76     74   or an immediate subdirectory of one of the directories in \fBauto_path\fR.
    77     75   \fBAuto_path\fR contains a list of directories that are searched
    78     76   by both the auto-loader and the package loader; by default it
    79     77   includes \fB$tcl_pkgPath\fR.
    80     78   The package loader also checks all of the subdirectories of the
    81     79   directories in \fBauto_path\fR.
    82     80   You can add a directory to \fBauto_path\fR explicitly in your
    83     81   application, or you can add the directory to your \fBTCLLIBPATH\fR
    84     82   environment variable:  if this environment variable is present,
    85     83   Tcl initializes \fBauto_path\fR from it during application startup.
    86         -.RE
    87     84   .IP [4]
    88     85   Once the above steps have been taken, all you need to do to use a
    89     86   package is to invoke \fBpackage require\fR.
    90     87   For example, if versions 2.1, 2.3, and 3.1 of package \fBTest\fR
    91     88   have been indexed by \fBpkg_mkIndex\fR, the command
    92     89   \fBpackage require Test\fR will make version 3.1 available
    93     90   and the command \fBpackage require \-exact Test 2.1\fR will
    94     91   make version 2.1 available.
    95     92   There may be many versions of a package in the various index files
    96     93   in \fBauto_path\fR, but only one will actually be loaded in a given
    97     94   interpreter, based on the first call to \fBpackage require\fR.
    98     95   Different versions of a package may be loaded in different
    99     96   interpreters.
           97  +
   100     98   .SH OPTIONS
   101     99   The optional switches are:
   102    100   .TP 15
   103    101   \fB\-direct\fR
   104    102   The generated index will implement direct loading of the package
   105    103   upon \fBpackage require\fR.  This is the default.
   106    104   .TP 15
................................................................................
   119    117   .TP 15
   120    118   \fB\-verbose\fR
   121    119   Generate output during the indexing process.  Output is via
   122    120   the \fBtclLog\fR procedure, which by default prints to stderr.
   123    121   .TP 15
   124    122   \fB\-\-\fR
   125    123   End of the flags, in case \fIdir\fR begins with a dash.
          124  +
   126    125   .SH "PACKAGES AND THE AUTO-LOADER"
   127    126   .PP
   128    127   The package management facilities overlap somewhat with the auto-loader,
   129    128   in that both arrange for files to be loaded on-demand.
   130    129   However, package management is a higher-level mechanism that uses
   131    130   the auto-loader for the last step in the loading process.
   132    131   It is generally better to index a package with \fBpkg_mkIndex\fR
................................................................................
   138    137   it can only handle a single version of each package. 
   139    138   It is probably not a good idea to index a given package with both
   140    139   \fBpkg_mkIndex\fR and \fBauto_mkindex\fR.
   141    140   If you use \fBpkg_mkIndex\fR to index a package, its commands cannot
   142    141   be invoked until \fBpackage require\fR has been used to select a
   143    142   version;  in contrast, packages indexed with \fBauto_mkindex\fR
   144    143   can be used immediately since there is no version control.
          144  +
   145    145   .SH "HOW IT WORKS"
   146    146   .PP
   147    147   \fBPkg_mkIndex\fR depends on the \fBpackage unknown\fR command,
   148    148   the \fBpackage ifneeded\fR command, and the auto-loader.
   149    149   The first time a \fBpackage require\fR command is invoked,
   150    150   the \fBpackage unknown\fR script is invoked.
   151    151   This is set by Tcl initialization to a script that
................................................................................
   160    160   was generated,
   161    161   a given file of a given version of a given package isn't
   162    162   actually loaded until the first time one of its commands
   163    163   is invoked.
   164    164   Thus, after invoking \fBpackage require\fR you may
   165    165   not see the package's commands in the interpreter, but you will be able
   166    166   to invoke the commands and they will be auto-loaded.
          167  +
   167    168   .SH "DIRECT LOADING"
   168    169   .PP
   169    170   Some packages, for instance packages which use namespaces and export
   170    171   commands or those which require special initialization, might select
   171    172   that their package files be loaded immediately upon \fBpackage require\fR
   172    173   instead of delaying the actual loading to the first use of one of the
   173    174   package's command. This is the default mode when generating the package
   174    175   index.  It can be overridden by specifying the \fI\-lazy\fR argument.
          176  +
   175    177   .SH "COMPLEX CASES"
   176    178   Most complex cases of dependencies among scripts
   177    179   and binary files, and packages being split among scripts and
   178    180   binary files are handled OK.  However, you may have to adjust
   179    181   the order in which files are processed by \fBpkg_mkIndex\fR.
   180    182   These issues are described in detail below.
   181    183   .PP
................................................................................
   223    225   If you have a package that is split across scripts and a binary file,
   224    226   then you should avoid the \fB\-load\fR flag. The problem is that
   225    227   if you load a package before computing the index it masks any
   226    228   other files that provide part of the same package.
   227    229   If you must use \fB\-load\fR,
   228    230   then you must specify the scripts first; otherwise the package loaded from
   229    231   the binary file may mask the package defined by the scripts.
          232  +
   230    233   .SH "SEE ALSO"
   231    234   package(n)
          235  +
   232    236   .SH KEYWORDS
   233    237   auto-load, index, package, version

Changes to doc/re_syntax.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1998 Sun Microsystems, Inc.
     3      3   '\" Copyright (c) 1999 Scriptics Corporation
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: re_syntax.n,v 1.12 2007/10/26 12:25:06 dkf Exp $
            8  +'\" RCS: @(#) $Id: re_syntax.n,v 1.13 2007/10/26 20:11:53 dgp Exp $
     9      9   '\"
    10     10   .so man.macros
    11     11   .TH re_syntax n "8.1" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   .SH NAME
    14     14   re_syntax \- Syntax of Tcl regular expressions
    15     15   .BE
    16     16   
    17     17   .SH DESCRIPTION
    18     18   .PP
    19     19   A \fIregular expression\fR describes strings of characters.
    20     20   It's a pattern that matches certain strings and doesn't match others.
    21     21   .SH "DIFFERENT FLAVORS OF REs"
    22         -Regular expressions
    23         -.PQ RE s ,
    24         -as defined by POSIX, come in two flavors: \fIextended\fR REs
    25         -.PQ ERE s
    26         -and \fIbasic\fR REs
    27         -.PQ BRE s .
           22  +Regular expressions (``RE''s), as defined by POSIX, come in two
           23  +flavors: \fIextended\fR REs (``EREs'') and \fIbasic\fR REs (``BREs'').
    28     24   EREs are roughly those of the traditional \fIegrep\fR, while BREs are
    29     25   roughly those of the traditional \fIed\fR.  This implementation adds
    30         -a third flavor, \fIadvanced\fR REs
    31         -.PQ ARE s ,
    32         -basically EREs with some significant extensions.
           26  +a third flavor, \fIadvanced\fR REs (``AREs''), basically EREs with
           27  +some significant extensions.
    33     28   .PP
    34     29   This manual page primarily describes AREs.  BREs mostly exist for
    35     30   backward compatibility in some old programs; they will be discussed at
    36     31   the end.  POSIX EREs are almost an exact subset of AREs.  Features of
    37     32   AREs that are not present in EREs will be indicated.
    38     33   .SH "REGULAR EXPRESSION SYNTAX"
    39     34   .PP
    40     35   Tcl regular expressions are implemented using the package written by
    41     36   Henry Spencer, based on the 1003.2 spec and some (not quite all) of
    42     37   the Perl5 extensions (thanks, Henry!).  Much of the description of
    43     38   regular expressions below is copied verbatim from his manual entry.
    44     39   .PP
    45     40   An ARE is one or more \fIbranches\fR,
    46         -separated by
    47         -.QW \fB|\fR ,
           41  +separated by `\fB|\fR',
    48     42   matching anything that matches any of the branches.
    49     43   .PP
    50     44   A branch is zero or more \fIconstraints\fR or \fIquantified atoms\fR,
    51     45   concatenated.
    52     46   It matches a match for the first, followed by a match for the second, etc;
    53     47   an empty branch matches the empty string.
    54     48   .PP
................................................................................
    91     85   .PP
    92     86   An atom is one of:
    93     87   .RS 2
    94     88   .IP \fB(\fIre\fB)\fR 6
    95     89   matches a match for \fIre\fR (\fIre\fR is any regular expression) with
    96     90   the match noted for possible reporting
    97     91   .IP \fB(?:\fIre\fB)\fR
    98         -as previous, but does no reporting (a
    99         -.QW non-capturing
   100         -set of parentheses)
           92  +as previous, but does no reporting (a ``non-capturing'' set of
           93  +parentheses)
   101     94   .IP \fB()\fR
   102     95   matches an empty string, noted for possible reporting
   103     96   .IP \fB(?:)\fR
   104     97   matches an empty string, without reporting
   105     98   .IP \fB[\fIchars\fB]\fR
   106     99   a \fIbracket expression\fR, matching any one of the \fIchars\fR (see
   107    100   \fBBRACKET EXPRESSIONS\fR for more detail)
   108    101   .IP \fB.\fR
   109    102   matches any single character
   110    103   .IP \fB\e\fIk\fR
   111    104   matches the non-alphanumeric character \fIk\fR
   112         -taken as an ordinary character, e.g.
   113         -.QW \fB\e\e\fR
   114         -matches a backslash character
          105  +taken as an ordinary character, e.g. \fB\e\e\fR matches a backslash
          106  +character
   115    107   .IP \fB\e\fIc\fR
   116    108   where \fIc\fR is alphanumeric (possibly followed by other characters),
   117    109   an \fIescape\fR (AREs only), see \fBESCAPES\fR below
   118    110   .IP \fB{\fR
   119    111   when followed by a character other than a digit, matches the
   120         -left-brace character
   121         -.QW \fB{\fR ;
   122         -when followed by a digit, it is the beginning of a \fIbound\fR (see above)
          112  +left-brace character `\fB{\fR'; when followed by a digit, it is the
          113  +beginning of a \fIbound\fR (see above)
   123    114   .IP \fIx\fR
   124    115   where \fIx\fR is a single character with no other significance,
   125    116   matches that character.
   126    117   .RE
   127    118   .PP
   128    119   A \fIconstraint\fR matches an empty string when specific conditions
   129    120   are met.  A constraint may not be followed by a quantifier.  The
................................................................................
   145    136   \fInegative lookahead\fR (AREs only), matches at any point where no
   146    137   substring matching \fIre\fR begins
   147    138   .RE
   148    139   .PP
   149    140   The lookahead constraints may not contain back references (see later),
   150    141   and all parentheses within them are considered non-capturing.
   151    142   .PP
   152         -An RE may not end with
   153         -.QW \fB\e\fR .
          143  +An RE may not end with `\fB\e\fR'.
   154    144   .SH "BRACKET EXPRESSIONS"
   155    145   A \fIbracket expression\fR is a list of characters enclosed in
   156         -.QW \fB[\|]\fR .
   157         -It normally matches any single character from the list (but see
   158         -below).  If the list begins with
   159         -.QW \fB^\fR ,
   160         -it matches any single character (but see below) \fInot\fR from the
   161         -rest of the list.
   162         -.PP
   163         -If two characters in the list are separated by
   164         -.QW \fB\-\fR ,
   165         -this is shorthand for the full \fIrange\fR of characters between those two
   166         -(inclusive) in the collating sequence, e.g.
   167         -.QW \fB[0\-9]\fR
   168         -in Unicode matches any conventional decimal digit. Two ranges may not share an
   169         -endpoint, so e.g.
   170         -.QW \fBa\-c\-e\fR
   171         -is illegal. Ranges are very collating-sequence-dependent, and portable
   172         -programs should avoid relying on them. 
   173         -.PP
   174         -To include a literal
   175         -.QW \fB]\fR
   176         -or
   177         -.QW \fB\-\fR
   178         -in the list, the simplest method is to enclose it in
   179         -.QW \fB[.\fR
   180         -and
   181         -.QW \fB.]\fR
   182         -to make it a collating element (see below). Alternatively, make it the first
   183         -character (following a possible
   184         -.QW \fB^\fR ),
   185         -or (AREs only) precede it with
   186         -.QW \fB\e\fR .
   187         -Alternatively, for
   188         -.QW \fB\-\fR ,
   189         -make it the last character, or the second endpoint of a range. To use a
   190         -literal
   191         -.QW \fB\-\fR
   192         -as the first endpoint of a range, make it a collating element
   193         -or (AREs only) precede it with
   194         -.QW \fB\e\fR .
   195         -With the exception of these, some combinations using
   196         -.QW \fB[\fR
   197         -(see next paragraphs), and escapes, all other special characters lose their
   198         -special significance within a bracket expression.
          146  +`\fB[\|]\fR'.  It normally matches any single character from the list
          147  +(but see below).  If the list begins with `\fB^\fR', it matches any
          148  +single character (but see below) \fInot\fR from the rest of the list.
          149  +.PP
          150  +If two characters in the list are separated by `\fB\-\fR', this is
          151  +shorthand for the full \fIrange\fR of characters between those two
          152  +(inclusive) in the collating sequence, e.g. \fB[0\-9]\fR in Unicode
          153  +matches any conventional decimal digit.  Two ranges may not share an
          154  +endpoint, so e.g. \fBa\-c\-e\fR is illegal.  Ranges are very
          155  +collating-sequence-dependent, and portable programs should avoid
          156  +relying on them.
          157  +.PP
          158  +To include a literal \fB]\fR or \fB\-\fR in the list, the simplest
          159  +method is to enclose it in \fB[.\fR and \fB.]\fR to make it a
          160  +collating element (see below).  Alternatively, make it the first
          161  +character (following a possible `\fB^\fR'), or (AREs only) precede it
          162  +with `\fB\e\fR'.  Alternatively, for `\fB\-\fR', make it the last
          163  +character, or the second endpoint of a range.  To use a literal
          164  +\fB\-\fR as the first endpoint of a range, make it a collating element
          165  +or (AREs only) precede it with `\fB\e\fR'.  With the exception of
          166  +these, some combinations using \fB[\fR (see next paragraphs), and
          167  +escapes, all other special characters lose their special significance
          168  +within a bracket expression.
   199    169   .PP
   200    170   Within a bracket expression, a collating element (a character, a
   201    171   multi-character sequence that collates as if it were a single
   202    172   character, or a collating-sequence name for either) enclosed in
   203         -.QW \fB[.\fR
   204         -and
   205         -.QW \fB.]\fR
   206         -stands for the sequence of characters of that collating element.
   207         -The sequence is a single element of the bracket
          173  +\fB[.\fR and \fB.]\fR stands for the sequence of characters of that
          174  +collating element.  The sequence is a single element of the bracket
   208    175   expression's list.  A bracket expression in a locale that has
   209    176   multi-character collating elements can thus match more than one
   210    177   character.  So (insidiously), a bracket expression that starts with
   211         -.QW \fB^\fR
   212         -can match multi-character collating elements even if none of
          178  +\fB^\fR can match multi-character collating elements even if none of
   213    179   them appear in the bracket expression!  (\fINote:\fR Tcl currently has
   214    180   no multi-character collating elements.  This information is only for
   215    181   illustration.)
   216    182   .PP
   217         -For example, assume the collating sequence includes a
   218         -.QW \fBch\fR
   219         -multi-character collating element.  Then the RE
   220         -.QW \fB[[.ch.]]*c\fR
   221         -(zero or more
   222         -.QW \fBch\fR 's
   223         -followed by
   224         -.QW \fBc\fR )
   225         -matches the first five characters of
   226         -.QW \fBchchcc\fR .
   227         -Also, the RE
   228         -.QW \fB[^c]b\fR
   229         -matches all of
   230         -.QW \fBchb\fR
   231         -(because
   232         -.QW \fB[^c]\fR
   233         -matches the multi-character
   234         -.QW \fBch\fR ).
          183  +For example, assume the collating sequence includes a \fBch\fR
          184  +multi-character collating element.  Then the RE \fB[[.ch.]]*c\fR (zero
          185  +or more \fBch\fR's followed by \fBc\fR) matches the first five
          186  +characters of `\fBchchcc\fR'.  Also, the RE \fB[^c]b\fR matches all of
          187  +`\fBchb\fR' (because \fB[^c]\fR matches the multi-character \fBch\fR).
   235    188   .PP
   236         -Within a bracket expression, a collating element enclosed in
   237         -.QW \fB[=\fR
   238         -and
   239         -.QW \fB=]\fR
   240         -is an equivalence class, standing for the sequences of
          189  +Within a bracket expression, a collating element enclosed in \fB[=\fR
          190  +and \fB=]\fR is an equivalence class, standing for the sequences of
   241    191   characters of all collating elements equivalent to that one, including
   242    192   itself.  (If there are no other equivalent collating elements, the
   243         -treatment is as if the enclosing delimiters were
   244         -.QW \fB[.\fR \&
   245         -and
   246         -.QW \fB.]\fR .)
   247         -For example, if
   248         -.QW \fBo\fR
   249         -and
   250         -.QW \fB\N'244'\fR
   251         -are the members of an equivalence class, then
   252         -.QW \fB[[=o=]]\fR ,
   253         -.QW \fB[[=\N'244'=]]\fR ,
   254         -and
   255         -.QW \fB[o\N'244']\fR \&
   256         -are all synonymous.  An equivalence class may
          193  +treatment is as if the enclosing delimiters were `\fB[.\fR'\& and
          194  +`\fB.]\fR'.)  For example, if \fBo\fR and \fB\o'o^'\fR are the members
          195  +of an equivalence class, then `\fB[[=o=]]\fR', `\fB[[=\o'o^'=]]\fR',
          196  +and `\fB[o\o'o^']\fR'\& are all synonymous.  An equivalence class may
   257    197   not be an endpoint of a range.  (\fINote:\fR Tcl currently implements
   258    198   only the Unicode locale.  It doesn't define any equivalence classes.
   259    199   The examples above are just illustrations.)
   260    200   .PP
   261    201   Within a bracket expression, the name of a \fIcharacter class\fR
   262         -enclosed in
   263         -.QW \fB[:\fR
   264         -and
   265         -.QW \fB:]\fR
   266         -stands for the list of all
   267         -characters (not all collating elements!) belonging to that class.
          202  +enclosed in \fB[:\fR and \fB:]\fR stands for the list of all
          203  +characters (not all collating elements!)  belonging to that class.
   268    204   Standard character classes are:
   269    205   .IP \fBalpha\fR 8
   270    206   A letter.
   271    207   .IP \fBupper\fR 8
   272    208   An upper-case letter.
   273    209   .IP \fBlower\fR 8
   274    210   A lower-case letter.
................................................................................
   275    211   .IP \fBdigit\fR 8
   276    212   A decimal digit.
   277    213   .IP \fBxdigit\fR 8
   278    214   A hexadecimal digit.
   279    215   .IP \fBalnum\fR 8
   280    216   An alphanumeric (letter or digit).
   281    217   .IP \fBprint\fR 8
   282         -A
   283         -.QW "printable"
   284         -(same as graph, except also including space).
          218  +A "printable" (same as graph, except also including space).
   285    219   .IP \fBblank\fR 8
   286    220   A space or tab character.
   287    221   .IP \fBspace\fR 8
   288    222   A character producing white space in displayed text.
   289    223   .IP \fBpunct\fR 8
   290    224   A punctuation character.
   291    225   .IP \fBgraph\fR 8
................................................................................
   294    228   A control character.
   295    229   .PP
   296    230   A locale may provide others.  (Note that the current Tcl
   297    231   implementation has only one locale: the Unicode locale.)  A character
   298    232   class may not be used as an endpoint of a range.
   299    233   .PP
   300    234   There are two special cases of bracket expressions: the bracket
   301         -expressions
   302         -.QW \fB[[:<:]]\fR
   303         -and
   304         -.QW \fB[[:>:]]\fR
   305         -are constraints, matching
          235  +expressions \fB[[:<:]]\fR and \fB[[:>:]]\fR are constraints, matching
   306    236   empty strings at the beginning and end of a word respectively.
   307         -.\" note, discussion of escapes below references this definition of word
          237  +'\" note, discussion of escapes below references this definition of word
   308    238   A word is defined as a sequence of word characters that is neither
   309    239   preceded nor followed by word characters.  A word character is an
   310         -\fIalnum\fR character or an underscore
   311         -.PQ \fB_\fR "" .
   312         -These special bracket expressions are deprecated; users of AREs should use
          240  +\fIalnum\fR character or an underscore (\fB_\fR).  These special
          241  +bracket expressions are deprecated; users of AREs should use
   313    242   constraint escapes instead (see below).
   314    243   .SH ESCAPES
   315         -Escapes (AREs only), which begin with a
   316         -.QW \fB\e\fR
   317         -followed by an
          244  +Escapes (AREs only), which begin with a \fB\e\fR followed by an
   318    245   alphanumeric character, come in several varieties: character entry,
   319         -class shorthands, constraint escapes, and back references.  A
   320         -.QW \fB\e\fR
          246  +class shorthands, constraint escapes, and back references.  A \fB\e\fR
   321    247   followed by an alphanumeric character but not constituting a valid
   322    248   escape is illegal in AREs.  In EREs, there are no escapes: outside a
   323         -bracket expression, a
   324         -.QW \fB\e\fR
   325         -followed by an alphanumeric character
          249  +bracket expression, a \fB\e\fR followed by an alphanumeric character
   326    250   merely stands for that character as an ordinary character, and inside
   327         -a bracket expression,
   328         -.QW \fB\e\fR
   329         -is an ordinary character.  (The latter
          251  +a bracket expression, \fB\e\fR is an ordinary character.  (The latter
   330    252   is the one actual incompatibility between EREs and AREs.)
   331    253   .PP
   332    254   Character-entry escapes (AREs only) exist to make it easier to specify
   333    255   non-printing and otherwise inconvenient characters in REs:
   334    256   .RS 2
   335    257   .TP 5
   336    258   \fB\ea\fR
................................................................................
   344    266   applications where there are multiple levels of backslash processing
   345    267   .TP
   346    268   \fB\ec\fIX\fR
   347    269   (where \fIX\fR is any character) the character whose low-order 5 bits
   348    270   are the same as those of \fIX\fR, and whose other bits are all zero
   349    271   .TP
   350    272   \fB\ee\fR
   351         -the character whose collating-sequence name is
   352         -.QW \fBESC\fR ,
   353         -or failing that, the character with octal value 033
          273  +the character whose collating-sequence name is `\fBESC\fR', or failing
          274  +that, the character with octal value 033
   354    275   .TP
   355    276   \fB\ef\fR
   356    277   formfeed, as in C
   357    278   .TP
   358    279   \fB\en\fR
   359    280   newline, as in C
   360    281   .TP
................................................................................
   390    311   .TP
   391    312   \fB\e\fIxyz\fR
   392    313   (where \fIxyz\fR is exactly three octal digits, and is not a back
   393    314   reference (see below)) the character whose octal value is
   394    315   \fB0\fIxyz\fR
   395    316   .RE
   396    317   .PP
   397         -Hexadecimal digits are
   398         -.QR 0 9 ,
   399         -.QR a f ,
   400         -and
   401         -.QR A F .
   402         -Octal digits are
   403         -.QR 0 7 .
          318  +Hexadecimal digits are `\fB0\fR'-`\fB9\fR', `\fBa\fR'-`\fBf\fR', and
          319  +`\fBA\fR'-`\fBF\fR'.  Octal digits are `\fB0\fR'-`\fB7\fR'.
   404    320   .PP
   405    321   The character-entry escapes are always taken as ordinary characters.
   406         -For example,
   407         -.QW \fB\e135\fR
   408         -is
   409         -.QW \fB]\fR
   410         -in Unicode, but
   411         -.QW \fB\e135\fR
   412         -does not terminate a bracket expression.  Beware, however, that some
          322  +For example, \fB\e135\fR is \fB]\fR in Unicode, but \fB\e135\fR does
          323  +not terminate a bracket expression.  Beware, however, that some
   413    324   applications (e.g., C compilers and the Tcl interpreter if the regular
   414    325   expression is not quoted with braces) interpret such sequences
   415    326   themselves before the regular-expression package gets to see them,
   416         -which may require doubling (quadrupling, etc.) the
   417         -.QW \fB\e\fR .
          327  +which may require doubling (quadrupling, etc.) the `\fB\e\fR'.
   418    328   .PP
   419    329   Class-shorthand escapes (AREs only) provide shorthands for certain
   420    330   commonly-used character classes:
   421    331   .RS 2
   422    332   .TP 10
   423    333   \fB\ed\fR
   424    334   \fB[[:digit:]]\fR
................................................................................
   435    345   \fB\eS\fR
   436    346   \fB[^[:space:]]\fR
   437    347   .TP
   438    348   \fB\eW\fR
   439    349   \fB[^[:alnum:]_]\fR (note underscore)
   440    350   .RE
   441    351   .PP
   442         -Within bracket expressions,
   443         -.QW \fB\ed\fR ,
   444         -.QW \fB\es\fR ,
   445         -and
   446         -.QW \fB\ew\fR \&
   447         -lose their outer brackets, and
   448         -.QW \fB\eD\fR ,
   449         -.QW \fB\eS\fR ,
   450         -and
   451         -.QW \fB\eW\fR \&
   452         -are illegal.  (So, for example,
   453         -.QW \fB[a-c\ed]\fR
   454         -is equivalent to
   455         -.QW \fB[a-c[:digit:]]\fR .
   456         -Also,
   457         -.QW \fB[a-c\eD]\fR ,
   458         -which is equivalent to
   459         -.QW \fB[a-c^[:digit:]]\fR ,
   460         -is illegal.)
          352  +Within bracket expressions, `\fB\ed\fR', `\fB\es\fR', and
          353  +`\fB\ew\fR'\& lose their outer brackets, and `\fB\eD\fR', `\fB\eS\fR',
          354  +and `\fB\eW\fR'\& are illegal.  (So, for example, \fB[a-c\ed]\fR is
          355  +equivalent to \fB[a-c[:digit:]]\fR.  Also, \fB[a-c\eD]\fR, which is
          356  +equivalent to \fB[a-c^[:digit:]]\fR, is illegal.)
   461    357   .PP
   462    358   A constraint escape (AREs only) is a constraint, matching the empty
   463    359   string if specific conditions are met, written as an escape:
   464    360   .RS 2
   465    361   .TP 6
   466    362   \fB\eA\fR
   467    363   matches only at the beginning of the string (see \fBMATCHING\fR,
   468         -below, for how this differs from
   469         -.QW \fB^\fR )
          364  +below, for how this differs from `\fB^\fR')
   470    365   .TP
   471    366   \fB\em\fR
   472    367   matches only at the beginning of a word
   473    368   .TP
   474    369   \fB\eM\fR
   475    370   matches only at the end of a word
   476    371   .TP
................................................................................
   478    373   matches only at the beginning or end of a word
   479    374   .TP
   480    375   \fB\eY\fR
   481    376   matches only at a point that is not the beginning or end of a word
   482    377   .TP
   483    378   \fB\eZ\fR
   484    379   matches only at the end of the string (see \fBMATCHING\fR, below, for
   485         -how this differs from
   486         -.QW \fB$\fR )
          380  +how this differs from `\fB$\fR')
   487    381   .TP
   488    382   \fB\e\fIm\fR
   489    383   (where \fIm\fR is a nonzero digit) a \fIback reference\fR, see below
   490    384   .TP
   491    385   \fB\e\fImnn\fR
   492    386   (where \fIm\fR is a nonzero digit, and \fInn\fR is some more digits,
   493    387   and the decimal value \fImnn\fR is not greater than the number of
   494    388   closing capturing parentheses seen so far) a \fIback reference\fR, see
   495    389   below
   496    390   .RE
   497    391   .PP
   498         -A word is defined as in the specification of
   499         -.QW \fB[[:<:]]\fR
   500         -and
   501         -.QW \fB[[:>:]]\fR
   502         -above.  Constraint escapes are illegal within bracket expressions.
          392  +A word is defined as in the specification of \fB[[:<:]]\fR and
          393  +\fB[[:>:]]\fR above.  Constraint escapes are illegal within bracket
          394  +expressions.
   503    395   .PP
   504    396   A back reference (AREs only) matches the same string matched by the
   505    397   parenthesized subexpression specified by the number, so that (e.g.)
   506         -.QW \fB([bc])\e1\fR
   507         -matches
   508         -.QW \fBbb\fR
   509         -or
   510         -.QW \fBcc\fR
   511         -but not
   512         -.QW \fBbc\fR .
   513         -The subexpression must entirely precede the back reference in the RE.
          398  +\fB([bc])\e1\fR matches \fBbb\fR or \fBcc\fR but not `\fBbc\fR'.  The
          399  +subexpression must entirely precede the back reference in the RE.
   514    400   Subexpressions are numbered in the order of their leading parentheses.
   515    401   Non-capturing parentheses do not define subexpressions.
   516    402   .PP
   517    403   There is an inherent historical ambiguity between octal
   518    404   character-entry escapes and back references, which is resolved by
   519    405   heuristics, as hinted at above.  A leading zero always indicates an
   520    406   octal escape.  A single non-zero digit, not followed by another digit,
................................................................................
   524    410   back reference), and otherwise is taken as octal.
   525    411   .SH "METASYNTAX"
   526    412   In addition to the main syntax described above, there are some special
   527    413   forms and miscellaneous syntactic facilities available.
   528    414   .PP
   529    415   Normally the flavor of RE being used is specified by
   530    416   application-dependent means.  However, this can be overridden by a
   531         -\fIdirector\fR.  If an RE of any flavor begins with
   532         -.QW \fB***:\fR ,
   533         -the rest of the RE is an ARE.  If an RE of any flavor begins with
   534         -.QW \fB***=\fR ,
   535         -the rest of the RE is taken to be a literal string, with
          417  +\fIdirector\fR.  If an RE of any flavor begins with `\fB***:\fR', the
          418  +rest of the RE is an ARE.  If an RE of any flavor begins with
          419  +`\fB***=\fR', the rest of the RE is taken to be a literal string, with
   536    420   all characters considered ordinary characters.
   537    421   .PP
   538    422   An ARE may begin with \fIembedded options\fR: a sequence
   539         -.QW \fB(?\fIxyz\fB)\fR
   540         -where
   541         -.QW \fIxyz\fR
   542         -is one or more alphabetic characters) specifies options affecting the rest of
   543         -the RE.  These supplement, and can override, any options specified by the
          423  +\fB(?\fIxyz\fB)\fR (where \fIxyz\fR is one or more alphabetic
          424  +characters) specifies options affecting the rest of the RE.  These
          425  +supplement, and can override, any options specified by the
   544    426   application.  The available option letters are:
   545    427   .RS 2
   546    428   .TP 3
   547    429   \fBb\fR
   548    430   rest of RE is a BRE
   549    431   .TP 3
   550    432   \fBc\fR
................................................................................
   562    444   \fBn\fR
   563    445   newline-sensitive matching (see \fBMATCHING\fR, below)
   564    446   .TP 3
   565    447   \fBp\fR
   566    448   partial newline-sensitive matching (see \fBMATCHING\fR, below)
   567    449   .TP 3
   568    450   \fBq\fR
   569         -rest of RE is a literal
   570         -.PQ quoted
   571         -string, all ordinary characters
          451  +rest of RE is a literal (``quoted'') string, all ordinary characters
   572    452   .TP 3
   573    453   \fBs\fR
   574    454   non-newline-sensitive matching (usual default)
   575    455   .TP 3
   576    456   \fBt\fR
   577    457   tight syntax (usual default; see below)
   578    458   .TP 3
   579    459   \fBw\fR
   580         -inverse partial newline-sensitive
   581         -.PQ weird
   582         -matching (see \fBMATCHING\fR, below)
          460  +inverse partial newline-sensitive (``weird'') matching (see
          461  +\fBMATCHING\fR, below)
   583    462   .TP 3
   584    463   \fBx\fR
   585    464   expanded syntax (see below)
   586    465   .RE
   587    466   .PP
   588         -Embedded options take effect at the
   589         -.QW \fB)\fR
   590         -terminating the sequence. They are available only at the start of an ARE, and
   591         -may not be used later within it.
          467  +Embedded options take effect at the \fB)\fR terminating the sequence.
          468  +They are available only at the start of an ARE, and may not be used
          469  +later within it.
   592    470   .PP
   593    471   In addition to the usual (\fItight\fR) RE syntax, in which all
   594    472   characters are significant, there is an \fIexpanded\fR syntax,
   595    473   available in all flavors of RE with the \fB-expanded\fR switch, or in
   596    474   AREs with the embedded x option.  In the expanded syntax, white-space
   597    475   characters are ignored and all characters between a \fB#\fR and the
   598    476   following newline (or the end of the RE) are ignored, permitting
   599    477   paragraphing and commenting a complex RE.  There are three exceptions
   600    478   to that basic rule:
   601    479   .IP \(bu 3
   602         -a white-space character or
   603         -.QW \fB#\fR
   604         -preceded by
   605         -.QW \fB\e\fR
   606         -is retained
          480  +a white-space character or `\fB#\fR' preceded by `\fB\e\fR' is
          481  +retained
   607    482   .IP \(bu 3
   608         -white space or
   609         -.QW \fB#\fR
   610         -within a bracket expression is retained
          483  +white space or `\fB#\fR' within a bracket expression is retained
   611    484   .IP \(bu 3
   612    485   white space and comments are illegal within multi-character symbols
   613         -like the ARE
   614         -.QW \fB(?:\fR
   615         -or the BRE
   616         -.QW \fB\e(\fR
          486  +like the ARE `\fB(?:\fR' or the BRE `\fB\e(\fR'
   617    487   .PP
   618    488   Expanded-syntax white-space characters are blank, tab, newline, and
   619    489   any character that belongs to the \fIspace\fR character class.
   620    490   .PP
   621    491   Finally, in an ARE, outside bracket expressions, the sequence
   622         -.QW \fB(?#\fIttt\fB)\fR
   623         -(where \fIttt\fR is any text not containing a
   624         -.QW \fB)\fR )
   625         -is a comment, completely ignored.  Again, this is not allowed between the
   626         -characters of multi-character symbols like
   627         -.QW \fB(?:\fR .
   628         -Such comments are more a historical artifact than a
          492  +`\fB(?#\fIttt\fB)\fR' (where \fIttt\fR is any text not containing a
          493  +`\fB)\fR') is a comment, completely ignored.  Again, this is not
          494  +allowed between the characters of multi-character symbols like
          495  +`\fB(?:\fR'.  Such comments are more a historical artifact than a
   629    496   useful facility, and their use is deprecated; use the expanded syntax
   630    497   instead.
   631    498   .PP
   632    499   \fINone\fR of these metasyntax extensions is available if the
   633         -application (or an initial
   634         -.QW \fB***=\fR
   635         -director) has specified that the
          500  +application (or an initial \fB***=\fR director) has specified that the
   636    501   user's input be treated as a literal string rather than as an RE.
   637    502   .SH MATCHING
   638    503   In the event that an RE could match more than one substring of a given
   639    504   string, the RE matches the one starting earliest in the string.  If
   640    505   the RE could match more than one substring starting at that point, its
   641    506   choice is determined by its \fIpreference\fR: either the longest
   642    507   substring, or the shortest.
   643    508   .PP
   644    509   Most atoms, and all constraints, have no preference.  A parenthesized
   645    510   RE has the same preference (possibly none) as the RE.  A quantified
   646         -atom with quantifier
   647         -.QW \fB{\fIm\fB}\fR
   648         -or
   649         -.QW \fB{\fIm\fB}?\fR
   650         -has the same
          511  +atom with quantifier \fB{\fIm\fB}\fR or \fB{\fIm\fB}?\fR has the same
   651    512   preference (possibly none) as the atom itself.  A quantified atom with
   652         -other normal quantifiers (including
   653         -.QW \fB{\fIm\fB,\fIn\fB}\fR
   654         -with \fIm\fR equal to \fIn\fR) prefers longest match.  A quantified atom
   655         -with other non-greedy quantifiers (including
   656         -.QW \fB{\fIm\fB,\fIn\fB}?\fR
          513  +other normal quantifiers (including \fB{\fIm\fB,\fIn\fB}\fR with
          514  +\fIm\fR equal to \fIn\fR) prefers longest match.  A quantified atom
          515  +with other non-greedy quantifiers (including \fB{\fIm\fB,\fIn\fB}?\fR
   657    516   with \fIm\fR equal to \fIn\fR) prefers shortest match.  A branch has
   658    517   the same preference as the first quantified atom in it which has a
   659    518   preference.  An RE consisting of two or more branches connected by the
   660         -.QW \fB|\fR
   661         -operator prefers longest match.
          519  +\fB|\fR operator prefers longest match.
   662    520   .PP
   663    521   Subject to the constraints imposed by the rules for matching the whole
   664    522   RE, subexpressions also match the longest or shortest possible
   665    523   substrings, based on their preferences, with subexpressions starting
   666    524   earlier in the RE taking priority over ones starting later.  Note that
   667    525   outer subexpressions thus take priority over their component
   668    526   subexpressions.
   669    527   .PP
   670         -Note that the quantifiers
   671         -.QW \fB{1,1}\fR
   672         -and
   673         -.QW \fB{1,1}?\fR
   674         -can be used to force longest and shortest preference, respectively, on a
          528  +Note that the quantifiers \fB{1,1}\fR and \fB{1,1}?\fR can be used to
          529  +force longest and shortest preference, respectively, on a
   675    530   subexpression or a whole RE.
   676    531   .PP
   677    532   Match lengths are measured in characters, not collating elements.  An
   678    533   empty string is considered longer than no match at all.  For example,
   679         -.QW \fBbb*\fR
   680         -matches the three middle characters of
   681         -.QW \fBabbbc\fR ,
   682         -.QW \fB(week|wee)(night|knights)\fR
   683         -matches all ten characters of
   684         -.QW \fBweeknights\fR ,
   685         -when
   686         -.QW \fB(.*).*\fR
   687         -is matched against
   688         -.QW \fBabc\fR
   689         -the
          534  +\fBbb*\fR matches the three middle characters of `\fBabbbc\fR',
          535  +\fB(week|wee)(night|knights)\fR matches all ten characters of
          536  +`\fBweeknights\fR', when \fB(.*).*\fR is matched against \fBabc\fR the
   690    537   parenthesized subexpression matches all three characters, and when
   691         -.QW \fB(a*)*\fR
   692         -is matched against
   693         -.QW \fBbc\fR
   694         -both the whole RE and the
          538  +\fB(a*)*\fR is matched against \fBbc\fR both the whole RE and the
   695    539   parenthesized subexpression match an empty string.
   696    540   .PP
   697    541   If case-independent matching is specified, the effect is much as if
   698    542   all case distinctions had vanished from the alphabet.  When an
   699    543   alphabetic that exists in multiple cases appears as an ordinary
   700    544   character outside a bracket expression, it is effectively transformed
   701         -into a bracket expression containing both cases, so that
   702         -.QW \fBx\fR
   703         -becomes
   704         -.QW \fB[xX]\fR .
   705         -When it appears inside a bracket expression,
          545  +into a bracket expression containing both cases, so that \fBx\fR
          546  +becomes `\fB[xX]\fR'.  When it appears inside a bracket expression,
   706    547   all case counterparts of it are added to the bracket expression, so
   707         -that
   708         -.QW \fB[x]\fR
   709         -becomes
   710         -.QW \fB[xX]\fR
   711         -and
   712         -.QW \fB[^x]\fR
   713         -becomes
   714         -.QW \fB[^xX]\fR.
          548  +that \fB[x]\fR becomes \fB[xX]\fR and \fB[^x]\fR becomes
          549  +`\fB[^xX]\fR'.
   715    550   .PP
   716         -If newline-sensitive matching is specified,
   717         -.QW \fB.\fR
   718         -and bracket expressions using
   719         -.QW \fB^\fR
   720         -will never match the newline character (so
          551  +If newline-sensitive matching is specified, \fB.\fR and bracket
          552  +expressions using \fB^\fR will never match the newline character (so
   721    553   that matches will never cross newlines unless the RE explicitly
   722         -arranges it) and
   723         -.QW \fB^\fR
   724         -and
   725         -.QW \fB$\fR
   726         -will match the empty string after
          554  +arranges it) and \fB^\fR and \fB$\fR will match the empty string after
   727    555   and before a newline respectively, in addition to matching at
   728         -beginning and end of string respectively.  ARE
   729         -.QW \fB\eA\fR
   730         -and
   731         -.QW \fB\eZ\fR
          556  +beginning and end of string respectively.  ARE \fB\eA\fR and \fB\eZ\fR
   732    557   continue to match beginning or end of string \fIonly\fR.
   733    558   .PP
   734    559   If partial newline-sensitive matching is specified, this affects
   735         -.QW \fB.\fR
   736         -and bracket expressions as with newline-sensitive matching, but not
   737         -.QW \fB^\fR
   738         -and
   739         -.QW \fB$\fR.
          560  +\fB.\fR and bracket expressions as with newline-sensitive matching,
          561  +but not \fB^\fR and `\fB$\fR'.
   740    562   .PP
   741    563   If inverse partial newline-sensitive matching is specified, this
   742         -affects
   743         -.QW \fB^\fR
   744         -and
   745         -.QW \fB$\fR
   746         -as with newline-sensitive matching, but not
   747         -.QW \fB.\fR
   748         -and bracket expressions.  This isn't very useful but is
          564  +affects \fB^\fR and \fB$\fR as with newline-sensitive matching, but
          565  +not \fB.\fR and bracket expressions.  This isn't very useful but is
   749    566   provided for symmetry.
   750    567   .SH "LIMITS AND COMPATIBILITY"
   751    568   No particular limit is imposed on the length of REs.  Programs
   752    569   intended to be highly portable should not employ REs longer than 256
   753    570   bytes, as a POSIX-compliant implementation can refuse to accept such
   754    571   REs.
   755    572   .PP
   756    573   The only feature of AREs that is actually incompatible with POSIX EREs
   757         -is that
   758         -.QW \fB\e\fR
   759         -does not lose its special significance inside bracket
          574  +is that \fB\e\fR does not lose its special significance inside bracket
   760    575   expressions.  All other ARE features use syntax which is illegal or
   761         -has undefined or unspecified effects in POSIX EREs; the
   762         -.QW \fB***\fR
          576  +has undefined or unspecified effects in POSIX EREs; the \fB***\fR
   763    577   syntax of directors likewise is outside the POSIX syntax for both BREs
   764    578   and EREs.
   765    579   .PP
   766    580   Many of the ARE extensions are borrowed from Perl, but some have been
   767    581   changed to clean them up, and a few Perl extensions are not present.
   768         -Incompatibilities of note include
   769         -.QW \fB\eb\fR ,
   770         -.QW \fB\eB\fR ,
   771         -the lack of special treatment for a trailing newline, the addition of
          582  +Incompatibilities of note include `\fB\eb\fR', `\fB\eB\fR', the lack
          583  +of special treatment for a trailing newline, the addition of
   772    584   complemented bracket expressions to the things affected by
   773    585   newline-sensitive matching, the restrictions on parentheses and back
   774    586   references in lookahead constraints, and the longest/shortest-match
   775    587   (rather than first-match) matching semantics.
   776    588   .PP
   777    589   The matching rules for REs containing both normal and non-greedy
   778    590   quantifiers have changed since early beta-test versions of this
   779    591   package.  (The new rules are much simpler and cleaner, but don't work
   780    592   as hard at guessing the user's real intentions.)
   781    593   .PP
   782    594   Henry Spencer's original 1986 \fIregexp\fR package, still in
   783    595   widespread use (e.g., in pre-8.1 releases of Tcl), implemented an
   784    596   early version of today's EREs.  There are four incompatibilities
   785         -between \fIregexp\fR's near-EREs
   786         -.PQ RRE "s for short"
   787         -and AREs.  In roughly increasing order of significance:
          597  +between \fIregexp\fR's near-EREs (`RREs' for short) and AREs.  In
          598  +roughly increasing order of significance:
   788    599   .IP \(bu 3
   789         -In AREs,
   790         -.QW \fB\e\fR
   791         -followed by an alphanumeric character is either an
          600  +In AREs, \fB\e\fR followed by an alphanumeric character is either an
   792    601   escape or an error, while in RREs, it was just another way of writing
   793    602   the alphanumeric.  This should not be a problem because there was no
   794    603   reason to write such a sequence in RREs.
   795    604   .IP \(bu 3
   796         -.QW \fB{\fR
   797         -followed by a digit in an ARE is the beginning of a bound,
   798         -while in RREs,
   799         -.QW \fB{\fR
   800         -was always an ordinary character.  Such
          605  +\fB{\fR followed by a digit in an ARE is the beginning of a bound,
          606  +while in RREs, \fB{\fR was always an ordinary character.  Such
   801    607   sequences should be rare, and will often result in an error because
   802    608   following characters will not look like a valid bound.
   803    609   .IP \(bu 3
   804         -In AREs,
   805         -.QW \fB\e\fR
   806         -remains a special character within
   807         -.QW \fB[\|]\fR ,
   808         -so a literal
   809         -.QW \fB\e\fR
   810         -within
   811         -.QW \fB[\|]\fR
   812         -must be written
   813         -.QW \fB\e\e\fR .
   814         -.QW \fB\e\e\fR
   815         -also gives a literal
   816         -.QW \fB\e\fR
   817         -within
   818         -.QW \fB[\|]\fR
   819         -in RREs, but only truly paranoid programmers routinely doubled the backslash.
          610  +In AREs, \fB\e\fR remains a special character within `\fB[\|]\fR', so
          611  +a literal \fB\e\fR within \fB[\|]\fR must be written `\fB\e\e\fR'.
          612  +\fB\e\e\fR also gives a literal \fB\e\fR within \fB[\|]\fR in RREs,
          613  +but only truly paranoid programmers routinely doubled the backslash.
   820    614   .IP \(bu 3
   821    615   AREs report the longest/shortest match for the RE, rather than the
   822    616   first found in a specified search order.  This may affect some RREs
   823    617   which were written in the expectation that the first match would be
   824    618   reported.  (The careful crafting of RREs to optimize the search order
   825    619   for fast matching is obsolete (AREs examine all possible matches in
   826    620   parallel, and their performance is largely insensitive to their
   827    621   complexity) but cases where the search order was exploited to
   828    622   deliberately find a match which was \fInot\fR the longest/shortest
   829    623   will need rewriting.)
   830    624   .SH "BASIC REGULAR EXPRESSIONS"
   831         -BREs differ from EREs in several respects.
   832         -.QW \fB|\fR ,
   833         -.QW \fB+\fR ,
   834         -and
   835         -.QW \fB?\fR
   836         -are ordinary characters and there is no equivalent for their
   837         -functionality.  The delimiters for bounds are
   838         -.QW \fB\e{\fR
   839         -and
   840         -.QW \fB\e}\fR ,
   841         -with
   842         -.QW \fB{\fR
   843         -and
   844         -.QW \fB}\fR
   845         -by themselves ordinary characters.  The parentheses for nested subexpressions
   846         -are
   847         -.QW \fB\e(\fR
   848         -and
   849         -.QW \fB\e)\fR ,
   850         -with
   851         -.QW \fB(\fR
   852         -and
   853         -.QW \fB)\fR
   854         -by themselves ordinary characters.
   855         -.QW \fB^\fR
   856         -is an ordinary character except at the beginning
   857         -of the RE or the beginning of a parenthesized subexpression,
   858         -.QW \fB$\fR
          625  +BREs differ from EREs in several respects.  `\fB|\fR', `\fB+\fR', and
          626  +\fB?\fR are ordinary characters and there is no equivalent for their
          627  +functionality.  The delimiters for bounds are \fB\e{\fR and
          628  +`\fB\e}\fR', with \fB{\fR and \fB}\fR by themselves ordinary
          629  +characters.  The parentheses for nested subexpressions are \fB\e(\fR
          630  +and `\fB\e)\fR', with \fB(\fR and \fB)\fR by themselves ordinary
          631  +characters.  \fB^\fR is an ordinary character except at the beginning
          632  +of the RE or the beginning of a parenthesized subexpression, \fB$\fR
   859    633   is an ordinary character except at the end of the RE or the end of a
   860         -parenthesized subexpression, and
   861         -.QW \fB*\fR
   862         -is an ordinary character if
          634  +parenthesized subexpression, and \fB*\fR is an ordinary character if
   863    635   it appears at the beginning of the RE or the beginning of a
   864         -parenthesized subexpression (after a possible leading
   865         -.QW \fB^\fR ).
   866         -Finally, single-digit back references are available, and
   867         -.QW \fB\e<\fR
   868         -and
   869         -.QW \fB\e>\fR
   870         -are synonyms for
   871         -.QW \fB[[:<:]]\fR
   872         -and
   873         -.QW \fB[[:>:]]\fR
          636  +parenthesized subexpression (after a possible leading `\fB^\fR').
          637  +Finally, single-digit back references are available, and \fB\e<\fR and
          638  +\fB\e>\fR are synonyms for \fB[[:<:]]\fR and \fB[[:>:]]\fR
   874    639   respectively; no other escapes are available.
          640  +
   875    641   .SH "SEE ALSO"
   876    642   RegExp(3), regexp(n), regsub(n), lsearch(n), switch(n), text(n)
          643  +
   877    644   .SH KEYWORDS
   878    645   match, regular expression, string
   879         -.\" Local Variables:
   880         -.\" mode: nroff
   881         -.\" End:
          646  +
          647  +'\" Local Variables:
          648  +'\" mode: nroff
          649  +'\" End:

Changes to doc/read.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: read.n,v 1.12 2007/10/24 14:29:39 dkf Exp $
            8  +'\" RCS: @(#) $Id: read.n,v 1.13 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH read n 8.1 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   read \- Read from a channel
................................................................................
    49     49   the command returns before reaching the end of the file.
    50     50   .PP
    51     51   \fBRead\fR translates end-of-line sequences in the input into
    52     52   newline characters according to the \fB\-translation\fR option
    53     53   for the channel.
    54     54   See the \fBfconfigure\fR manual entry for a discussion on ways in
    55     55   which \fBfconfigure\fR will alter input.
           56  +
    56     57   .SH "USE WITH SERIAL PORTS"
    57         -.\" Note:  this advice actually applies to many versions of Tcl
           58  +'\" Note:  this advice actually applies to many versions of Tcl
           59  +
    58     60   For most applications a channel connected to a serial port should be
    59     61   configured to be nonblocking: \fBfconfigure \fIchannelId \fB\-blocking
    60     62   \fI0\fR.  Then \fBread\fR behaves much like described above.  Care
    61     63   must be taken when using \fBread\fR on blocking serial ports:
    62     64   .TP
    63     65   \fBread \fIchannelId numChars\fR 
    64     66   In this form \fBread\fR blocks until \fInumChars\fR have been received
................................................................................
    74     76   with each line in the file corresponding to an element in the list:
    75     77   .CS
    76     78   set fl [open /proc/meminfo]
    77     79   set data [\fBread\fR $fl]
    78     80   close $fl
    79     81   set lines [split $data \\n]
    80     82   .CE
           83  +
    81     84   .SH "SEE ALSO"
    82     85   file(n), eof(n), fblocked(n), fconfigure(n), Tcl_StandardChannels(3)
           86  +
    83     87   .SH KEYWORDS
    84     88   blocking, channel, end of line, end of file, nonblocking, read, translation, encoding

Changes to doc/refchan.n.

     1      1   '\" 
     2      2   '\" Copyright (c) 2006 Andreas Kupries
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\"
     7         -'\" RCS: @(#) $Id: refchan.n,v 1.6 2007/10/25 09:44:22 dkf Exp $
            7  +'\" RCS: @(#) $Id: refchan.n,v 1.7 2007/10/26 20:11:53 dgp Exp $
     8      8   .so man.macros
     9      9   .TH reflectedchan n 8.5 Tcl "Tcl Built-In Commands"
    10     10   .BS
    11     11   '\" Note:  do not modify the .SH NAME line immediately below!
    12     12   .SH NAME
    13     13   reflectedchan \- Command handler API of reflected channels, version 1
    14     14   .SH SYNOPSIS
................................................................................
    49     49   (e.g. \fBbreak\fR, etc.) is treated as (and converted to) an error.
    50     50   .PP
    51     51   \fBNote:\fR If the creation of the channel was aborted due to failures
    52     52   here, then the \fBfinalize\fR subcommand will not be called.
    53     53   .PP
    54     54   The \fImode\fR argument tells the handler whether the channel was
    55     55   opened for reading, writing, or both. It is a list containing any of
    56         -the strings
    57         -.QW "\fBread\fR"
    58         -or
    59         -.QW "\fBwrite\fR" .
    60         -The list will always contain at least one element.
           56  +the strings "\fBread\fR" or "\fBwrite\fR". The list will always
           57  +contain at least one element.
    61     58   .PP
    62     59   The subcommand must throw an error if the chosen mode is not
    63     60   supported by the \fIcmdPrefix\fR.
    64     61   .RE
    65     62   .TP
    66     63   \fIcmdPrefix \fBfinalize \fIchannelId\fR
    67     64   .
................................................................................
    85     82   aborted during \fBinitialize\fR (See above).
    86     83   .RE
    87     84   .TP
    88     85   \fIcmdPrefix \fBwatch \fIchannelId eventspec\fR
    89     86   .
    90     87   This subcommand notifies the \fIcmdPrefix\fR that the specified
    91     88   \fIchannelId\fR is interested in the events listed in the
    92         -\fIeventspec\fR. This argument is a list containing any of
    93         -.QW "\fBread\fR"
    94         -and
    95         -.QW "\fBwrite\fR" .
    96         -The list may be empty, which signals that the
           89  +\fIeventspec\fR. This argument is a list containing any of "\fBread\fR"
           90  +and "\fBwrite\fR". The list may be empty, which signals that the
    97     91   channel does not wish to be notified of any events. In that situation,
    98     92   the handler should disable event generation completely.
    99     93   .RS
   100     94   .PP
   101     95   \fBWarning:\fR Any return value of the subcommand is ignored. This
   102     96   includes all errors thrown by the subcommand, break, continue, and
   103     97   custom return codes.
................................................................................
   187    181   greater than or equal to zero.
   188    182   .PP
   189    183   If the subcommand throws an error the command which caused its
   190    184   invocation (usually \fBseek\fR, or \fBtell\fR) will appear to have
   191    185   thrown this error. Any exception beyond \fIerror\fR (e.g. \fIbreak\fR,
   192    186   etc.) is treated as and converted to an error.
   193    187   .PP
   194         -The offset/base combination of 0/\fBcurrent\fR signals a \fBtell\fR
          188  +The offset/base combination of 0/"\fBcurrent\fR" signals a \fBtell\fR
   195    189   request, i.e. seek nothing relative to the current location, making
   196    190   the new location identical to the current one, which is then returned.
   197    191   .RE
   198    192   .TP
   199    193   \fIcmdPrefix \fBconfigure \fIchannelId option value\fR
   200    194   .
   201    195   This \fIoptional\fR subcommand is for setting the type-specific options of

Changes to doc/regexp.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1998 Sun Microsystems, Inc.
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\" 
     7         -'\" RCS: @(#) $Id: regexp.n,v 1.22 2007/10/25 14:07:32 dkf Exp $
            7  +'\" RCS: @(#) $Id: regexp.n,v 1.23 2007/10/26 20:11:53 dgp Exp $
     8      8   '\" 
     9      9   .so man.macros
    10     10   .TH regexp n 8.3 Tcl "Tcl Built-In Commands"
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   regexp \- Match a regular expression against a string
           15  +
    15     16   .SH SYNOPSIS
    16     17   \fBregexp \fR?\fIswitches\fR? \fIexp string \fR?\fImatchVar\fR? ?\fIsubMatchVar subMatchVar ...\fR?
    17     18   .BE
    18     19   
    19     20   .SH DESCRIPTION
    20     21   .PP
    21     22   Determines whether the regular expression \fIexp\fR matches part or
................................................................................
    57     58   will contain a list of two decimal strings giving the indices
    58     59   in \fIstring\fR of the first and last characters in the matching
    59     60   range of characters.
    60     61   .TP 15
    61     62   \fB\-line\fR
    62     63   Enables newline-sensitive matching.  By default, newline is a
    63     64   completely ordinary character with no special meaning.  With this
    64         -flag,
    65         -.QW [^
    66         -bracket expressions and
    67         -.QW .
    68         -never match newline,
    69         -.QW ^
           65  +flag, `[^' bracket expressions and `.' never match newline, `^'
    70     66   matches an empty string after any newline in addition to its normal
    71         -function, and
    72         -.QW $
    73         -matches an empty string before any newline in
           67  +function, and `$' matches an empty string before any newline in
    74     68   addition to its normal function.  This flag is equivalent to
    75     69   specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the
    76     70   \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page).
    77     71   .TP 15
    78     72   \fB\-linestop\fR
    79         -Changes the behavior of
    80         -.QW [^
    81         -bracket expressions and
    82         -.QW .
    83         -so that they
           73  +Changes the behavior of `[^' bracket expressions and `.' so that they
    84     74   stop at newlines.  This is the same as specifying the \fB(?p)\fR
    85     75   embedded option (see the \fBre_syntax\fR manual page).
    86     76   .TP 15
    87     77   \fB\-lineanchor\fR
    88         -Changes the behavior of
    89         -.QW ^
    90         -and
    91         -.QW $
    92         -(the
    93         -.QW anchors )
    94         -so they match the
           78  +Changes the behavior of `^' and `$' (the ``anchors'') so they match the
    95     79   beginning and end of a line respectively.  This is the same as
    96     80   specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR
    97     81   manual page).
    98     82   .TP 15
    99     83   \fB\-nocase\fR
   100     84   Causes upper-case characters in \fIstring\fR to be treated as
   101     85   lower case during the matching process.
................................................................................
   110     94   Causes the command to return, as a list, the data that would otherwise
   111     95   be placed in match variables.  When using \fB-inline\fR,
   112     96   match variables may not be specified.  If used with \fB-all\fR, the
   113     97   list will be concatenated at each iteration, such that a flat list is
   114     98   always returned.  For each match iteration, the command will append the
   115     99   overall match data, plus one element for each subexpression in the
   116    100   regular expression.  Examples are:
   117         -.RS
   118    101   .CS
   119         -.ta 2i
   120         -\fBregexp\fR -inline -- {\\w(\\w)} " inlined "
   121         -	 \fB\(->\fI in n\fR
   122         -\fBregexp\fR -all -inline -- {\\w(\\w)} " inlined "
   123         -	 \fB\(->\fI in n li i ne e\fR
          102  +    regexp -inline -- {\\w(\\w)} " inlined "
          103  + => {in n}
          104  +    regexp -all -inline -- {\\w(\\w)} " inlined "
          105  + => {in n li i ne e}
   124    106   .CE
   125         -.RE
   126    107   .TP 15
   127    108   \fB\-start\fR \fIindex\fR
   128    109   Specifies a character index offset into the string to start
   129    110   matching the regular expression at.  
   130    111   .VS 8.5
   131    112   The \fIindex\fR value is interpreted in the same manner
   132    113   as the \fIindex\fR argument to \fBstring index\fR.
   133    114   .VE 8.5
   134         -When using this switch,
   135         -.QW ^
          115  +When using this switch, `^'
   136    116   will not match the beginning of the line, and \\A will still
   137    117   match the start of the string at \fIindex\fR.  If \fB\-indices\fR
   138    118   is specified, the indices will be indexed starting from the
   139    119   absolute beginning of the input string.
   140    120   \fIindex\fR will be constrained to the bounds of the input string.
   141    121   .TP 15
   142    122   \fB\-\|\-\fR
   143    123   Marks the end of switches.  The argument following this one will
   144    124   be treated as \fIexp\fR even if it starts with a \fB\-\fR.
   145    125   .PP
   146         -If there are more \fIsubMatchVar\fRs than parenthesized
          126  +If there are more \fIsubMatchVar\fR's than parenthesized
   147    127   subexpressions within \fIexp\fR, or if a particular subexpression
   148    128   in \fIexp\fR doesn't match the string (e.g. because it was in a
   149    129   portion of the expression that wasn't matched), then the corresponding
   150         -\fIsubMatchVar\fR will be set to
   151         -.QW "\fB\-1 \-1\fR"
   152         -if \fB\-indices\fR has been specified or to an empty string otherwise.
          130  +\fIsubMatchVar\fR will be set to ``\fB\-1 \-1\fR'' if \fB\-indices\fR
          131  +has been specified or to an empty string otherwise.
   153    132   .SH EXAMPLES
   154    133   Find the first occurrence of a word starting with \fBfoo\fR in a
   155    134   string that is not actually an instance of \fBfoobar\fR, and get the
   156    135   letters following it up to the end of the word into a variable:
   157    136   .CS
   158    137   \fBregexp\fR {\\<foo(?!bar\\>)(\\w*)} $string \-> restOfWord
   159    138   .CE
................................................................................
   173    152   .CE
   174    153   .PP
   175    154   List all words (consisting of all sequences of non-whitespace
   176    155   characters) in a string:
   177    156   .CS
   178    157   \fBregexp\fR \-all \-inline {\\S+} $string
   179    158   .CE
          159  +
   180    160   .SH "SEE ALSO"
   181    161   re_syntax(n), regsub(n),
   182    162   .VS 8.5
   183    163   string(n)
   184    164   .VE
          165  +
          166  +
   185    167   .SH KEYWORDS
   186    168   match, regular expression, string

Changes to doc/registry.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1997 Sun Microsystems, Inc.
     3      3   '\" Copyright (c) 2002 ActiveState Corporation.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\"
     8         -'\" RCS: @(#) $Id: registry.n,v 1.16 2007/10/25 14:07:32 dkf Exp $
            8  +'\" RCS: @(#) $Id: registry.n,v 1.17 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH registry n 1.1 registry "Tcl Bundled Packages"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   registry \- Manipulate the Windows registry
................................................................................
   148    148   The registry value contains a null-terminated string.  The data is 
   149    149   represented in Tcl as a string.
   150    150   .TP
   151    151   \fBexpand_sz\fR
   152    152   .
   153    153   The registry value contains a null-terminated string that contains
   154    154   unexpanded references to environment variables in the normal Windows
   155         -style (for example,
   156         -.QW "%PATH%" ).
   157         -The data is represented in Tcl as a string.
          155  +style (for example, "%PATH%").  The data is represented in Tcl as a
          156  +string.
   158    157   .TP
   159    158   \fBdword\fR
   160    159   .
   161    160   The registry value contains a little-endian 32-bit number.  The data is
   162    161   represented in Tcl as a decimal string.
   163    162   .TP
   164    163   \fBdword_big_endian\fR

Changes to doc/regsub.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2000 Scriptics Corporation.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: regsub.n,v 1.18 2007/10/24 14:29:39 dkf Exp $
            9  +'\" RCS: @(#) $Id: regsub.n,v 1.19 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH regsub n 8.3 Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   regsub \- Perform substitutions based on regular expression pattern matching
................................................................................
    27     27   present.
    28     28   (Regular expression matching is described in the \fBre_syntax\fR
    29     29   reference page.)
    30     30   If there is a match, then while copying \fIstring\fR to \fIvarName\fR
    31     31   (or to the result of this command if \fIvarName\fR is not present)
    32     32   the portion of \fIstring\fR that
    33     33   matched \fIexp\fR is replaced with \fIsubSpec\fR.
    34         -If \fIsubSpec\fR contains a
    35         -.QW &
    36         -or
    37         -.QW \e0 ,
    38         -then it is replaced in the substitution with the portion of \fIstring\fR that 
           34  +If \fIsubSpec\fR contains a ``&'' or ``\e0'', then it is replaced
           35  +in the substitution with the portion of \fIstring\fR that
    39     36   matched \fIexp\fR.
    40         -If \fIsubSpec\fR contains a
    41         -.QW \e\fIn\fR ,
    42         -where \fIn\fR is a digit
           37  +If \fIsubSpec\fR contains a ``\e\fIn\fR'', where \fIn\fR is a digit
    43     38   between 1 and 9, then it is replaced in the substitution with
    44     39   the portion of \fIstring\fR that matched the \fIn\fR-th
    45     40   parenthesized subexpression of \fIexp\fR.
    46     41   Additional backslashes may be used in \fIsubSpec\fR to prevent special
    47         -interpretation of
    48         -.QW &
    49         -or
    50         -.QW \e0
    51         -or
    52         -.QW \e\fIn\fR
    53         -or backslash.
           42  +interpretation of ``&'' or ``\e0'' or ``\e\fIn\fR'' or
           43  +backslash.
    54     44   The use of backslashes in \fIsubSpec\fR tends to interact badly
    55     45   with the Tcl parser's use of backslashes, so it's generally
    56     46   safest to enclose \fIsubSpec\fR in braces if it includes
    57     47   backslashes.
    58     48   .LP
    59     49   If the initial arguments to \fBregsub\fR start with \fB\-\fR then
    60     50   they are treated as switches.  The following switches are
................................................................................
    61     51   currently supported:
    62     52   .TP 10
    63     53   \fB\-all\fR
    64     54   All ranges in \fIstring\fR that match \fIexp\fR are found and
    65     55   substitution is performed for each of these ranges.
    66     56   Without this switch only the first
    67     57   matching range is found and substituted.
    68         -If \fB\-all\fR is specified, then
    69         -.QW &
    70         -and
    71         -.QW \e\fIn\fR
           58  +If \fB\-all\fR is specified, then ``&'' and ``\e\fIn\fR''
    72     59   sequences are handled for each substitution using the information
    73     60   from the corresponding match.
    74     61   .TP 15
    75     62   \fB\-expanded\fR
    76     63   Enables use of the expanded regular expression syntax where
    77     64   whitespace and comments are ignored.  This is the same as specifying
    78     65   the \fB(?x)\fR embedded option (see the \fBre_syntax\fR manual page).
    79     66   .TP 15
    80     67   \fB\-line\fR
    81     68   Enables newline-sensitive matching.  By default, newline is a
    82     69   completely ordinary character with no special meaning.  With this
    83         -flag,
    84         -.QW [^
    85         -bracket expressions and
    86         -.QW .
    87         -never match newline,
    88         -.QW ^
           70  +flag, `[^' bracket expressions and `.' never match newline, `^'
    89     71   matches an empty string after any newline in addition to its normal
    90         -function, and
    91         -.QW $
    92         -matches an empty string before any newline in
           72  +function, and `$' matches an empty string before any newline in
    93     73   addition to its normal function.  This flag is equivalent to
    94     74   specifying both \fB\-linestop\fR and \fB\-lineanchor\fR, or the
    95     75   \fB(?n)\fR embedded option (see the \fBre_syntax\fR manual page).
    96     76   .TP 15
    97     77   \fB\-linestop\fR
    98         -Changes the behavior of
    99         -.QW [^
   100         -bracket expressions and
   101         -.QW .
   102         -so that they stop at newlines.  This is the same as specifying the \fB(?p)\fR
           78  +Changes the behavior of `[^' bracket expressions and `.' so that they
           79  +stop at newlines.  This is the same as specifying the \fB(?p)\fR
   103     80   embedded option (see the \fBre_syntax\fR manual page).
   104     81   .TP 15
   105     82   \fB\-lineanchor\fR
   106         -Changes the behavior of
   107         -.QW ^
   108         -and
   109         -.QW $
   110         -(the
   111         -.QW anchors )
   112         -so they match the
           83  +Changes the behavior of `^' and `$' (the ``anchors'') so they match the
   113     84   beginning and end of a line respectively.  This is the same as
   114     85   specifying the \fB(?w)\fR embedded option (see the \fBre_syntax\fR
   115     86   manual page).
   116     87   .TP 10
   117     88   \fB\-nocase\fR
   118     89   Upper-case characters in \fIstring\fR will be converted to lower-case
   119     90   before matching against \fIexp\fR;  however, substitutions specified
................................................................................
   122     93   \fB\-start\fR \fIindex\fR
   123     94   Specifies a character index offset into the string to start
   124     95   matching the regular expression at.  
   125     96   .VS 8.5
   126     97   The \fIindex\fR value is interpreted in the same manner
   127     98   as the \fIindex\fR argument to \fBstring index\fR.
   128     99   .VE 8.5
   129         -When using this switch,
   130         -.QW ^
          100  +When using this switch, `^'
   131    101   will not match the beginning of the line, and \\A will still
   132    102   match the start of the string at \fIindex\fR.
   133    103   \fIindex\fR will be constrained to the bounds of the input string.
   134    104   .TP 10
   135    105   \fB\-\|\-\fR
   136    106   Marks the end of switches.  The argument following this one will
   137    107   be treated as \fIexp\fR even if it starts with a \fB\-\fR.

Changes to doc/return.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Contributions from Don Porter, NIST, 2003.  (not subject to US copyright)
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: return.n,v 1.13 2007/10/25 09:49:18 dkf Exp $
            9  +'\" RCS: @(#) $Id: return.n,v 1.14 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH return n 8.5 Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   return \- Return from a procedure, or set return code of a script
................................................................................
    17     17   .SH SYNOPSIS
    18     18   \fBreturn \fR?\fIresult\fR?
    19     19   .sp
    20     20   \fBreturn \fR?\fB-code \fIcode\fR? ?\fIresult\fR?
    21     21   .sp
    22     22   \fBreturn \fR?\fIoption value \fR...? ?\fIresult\fR?
    23     23   .BE
           24  +
    24     25   .SH DESCRIPTION
    25     26   .PP
    26     27   In its simplest usage, the \fBreturn\fR command is used without options
    27     28   in the body of a procedure to immediately return control to the caller
    28     29   of the procedure.  If a \fIresult\fR argument is provided, its value
    29     30   becomes the result of the procedure passed back to the caller.  
    30     31   If \fIresult\fR is not specified then an empty string will be returned
................................................................................
    36     37   the \fBreturn\fR command will cause script evaluation
    37     38   to immediately cease, and the value \fIresult\fR (or an empty string)
    38     39   will be returned as the result of the \fBsource\fR command.
    39     40   .SH "EXCEPTIONAL RETURN CODES"
    40     41   .PP
    41     42   In addition to the result of a procedure, the return
    42     43   code of a procedure may also be set by \fBreturn\fR
    43         -through use of the \fB\-code\fR option.
           44  +through use of the \fB-code\fR option.
    44     45   In the usual case where the \fB\-code\fR option isn't
    45     46   specified the procedure will return normally.
    46     47   However, the \fB\-code\fR option may be used to generate an
    47     48   exceptional return from the procedure.
    48     49   \fICode\fR may have any of the following values:
    49     50   .TP 13
    50         -\fBok (\fRor \fB0)\fR
           51  +\fBok (or 0)\fR
    51     52   Normal return:  same as if the option is omitted.  The return code
    52     53   of the procedure is 0 (\fBTCL_OK\fR).
    53     54   .TP 13
    54     55   \fBerror (1)\fR
    55     56   Error return: the return code of the procedure is 1 (\fBTCL_ERROR\fR).
    56     57   The procedure command behaves in its calling context as if it
    57     58   were the command \fBerror \fIresult\fR.  See below for additional
................................................................................
    73     74   were the command \fBcontinue\fR.
    74     75   .TP 13
    75     76   \fIvalue\fR
    76     77   \fIValue\fR must be an integer;  it will be returned as the
    77     78   return code for the current procedure.
    78     79   .LP
    79     80   When a procedure wants to signal that it has received invalid
    80         -arguments from its caller, it may use
    81         -.QW "\fBreturn \-code error\fR"
           81  +arguments from its caller, it may use \fBreturn -code error\fR
    82     82   with \fIresult\fR set to a suitable error message.  Otherwise
    83     83   usage of the \fBreturn -code\fR option is mostly limited to
    84     84   procedures that implement a new control structure.
    85     85   .PP
    86     86   The \fBreturn -code\fR command acts similarly within script
    87     87   files that are evaluated by the \fBsource\fR command.  During the
    88     88   evaluation of the contents of a file as a script by \fBsource\fR,
    89         -an invocation of the
    90         -.QW "\fBreturn -code \fIcode\fR"
    91         -command will cause the return code of \fBsource\fR to be \fIcode\fR.
           89  +an invocation of the \fBreturn -code \fIcode\fR command will cause
           90  +the return code of \fBsource\fR to be \fIcode\fR.
    92     91   .SH "RETURN OPTIONS"
    93     92   .PP
    94     93   .VS 8.5
    95     94   In addition to a result and a return code, evaluation of a command
    96     95   in Tcl also produces a dictionary of return options.  In general
    97     96   usage, all \fIoption value\fR pairs given as arguments to \fBreturn\fR
    98     97   become entries in the return options dictionary, and any values at all
    99     98   are acceptable except as noted below.  The \fBcatch\fR command may be
   100         -used to capture all of this information \(em the return code, the result,
   101         -and the return options dictionary \(em that arise from evaluation of a script.
           99  +used to capture all of this information -- the return code, the result,
          100  +and the return options dictionary -- that arise from evaluation of a script.
   102    101   .VE 8.5
   103    102   .PP
   104         -As documented above, the \fB\-code\fR entry in the return options dictionary
          103  +As documented above, the \fB-code\fR entry in the return options dictionary
   105    104   receives special treatment by Tcl.  There are other return options also
   106    105   recognized and treated specially by Tcl.  They are:
   107    106   .TP
   108         -\fB\-errorcode \fIlist\fR
   109         -The \fB\-errorcode\fR option receives special treatment only when the value
   110         -of the \fB\-code\fR option is \fBTCL_ERROR\fR.  Then the \fIlist\fR value
          107  +\fB-errorcode \fIlist\fR
          108  +The \fB-errorcode\fR option receives special treatment only when the value
          109  +of the \fB-code\fR option is \fBTCL_ERROR\fR.  Then the \fIlist\fR value
   111    110   is meant to be additional information about the error,
   112    111   presented as a Tcl list for further processing by programs.
   113         -If no \fB\-errorcode\fR option is provided to \fBreturn\fR when
   114         -the \fB\-code error\fR option is provided, Tcl will set the value
   115         -of the \fB\-errorcode\fR entry in the return options dictionary 
   116         -to the default value of \fBNONE\fR.  The \fB\-errorcode\fR return
          112  +If no \fB-errorcode\fR option is provided to \fBreturn\fR when
          113  +the \fB-code error\fR option is provided, Tcl will set the value
          114  +of the \fB-errorcode\fR entry in the return options dictionary 
          115  +to the default value of \fBNONE\fR.  The \fB-errorcode\fR return
   117    116   option will also be stored in the global variable \fBerrorCode\fR.
   118    117   .TP
   119         -\fB\-errorinfo \fIinfo\fR
   120         -The \fB\-errorinfo\fR option receives special treatment only when the value
   121         -of the \fB\-code\fR option is \fBTCL_ERROR\fR.  Then \fIinfo\fR is the initial
          118  +\fB-errorinfo \fIinfo\fR
          119  +The \fB-errorinfo\fR option receives special treatment only when the value
          120  +of the \fB-code\fR option is \fBTCL_ERROR\fR.  Then \fIinfo\fR is the initial
   122    121   stack trace, meant to provide to a human reader additional information
   123    122   about the context in which the error occurred.  The stack trace will
   124    123   also be stored in the global variable \fBerrorInfo\fR.  
   125         -If no \fB\-errorinfo\fR option is provided to \fBreturn\fR when
   126         -the \fB\-code error\fR option is provided, Tcl will provide its own
   127         -initial stack trace value in the entry for \fB\-errorinfo\fR.  Tcl's
          124  +If no \fB-errorinfo\fR option is provided to \fBreturn\fR when
          125  +the \fB-code error\fR option is provided, Tcl will provide its own
          126  +initial stack trace value in the entry for \fB-errorinfo\fR.  Tcl's
   128    127   initial stack trace will include only the call to the procedure, and
   129    128   stack unwinding will append information about higher stack levels, but
   130    129   there will be no information about the context of the error within
   131    130   the procedure.  Typically the \fIinfo\fR value is supplied from
   132         -the value of \fB\-errorinfo\fR in a return options dictionary captured
          131  +the value of \fB-errorinfo\fR in a return options dictionary captured
   133    132   by the \fBcatch\fR command (or from the copy of that information
   134    133   stored in the global variable \fBerrorInfo\fR).
   135    134   .TP
   136         -\fB\-level \fIlevel\fR
          135  +\fB-level \fIlevel\fR
   137    136   .VS 8.5
   138         -The \fB\-level\fR and \fB\-code\fR options work together to set the return
          137  +The \fB-level\fR and \fB-code\fR options work together to set the return
   139    138   code to be returned by one of the commands currently being evaluated.
   140    139   The \fIlevel\fR value must be a non-negative integer representing a number
   141    140   of levels on the call stack.  It defines the number of levels up the stack
   142    141   at which the return code of a command currently being evaluated should
   143         -be \fIcode\fR.  If no \fB\-level\fR option is provided, the default value
          142  +be \fIcode\fR.  If no \fB-level\fR option is provided, the default value
   144    143   of \fIlevel\fR is 1, so that \fBreturn\fR sets the return code that the
   145    144   current procedure returns to its caller, 1 level up the call stack.  The
   146    145   mechanism by which these options work is described in more detail below.
   147    146   .VE 8.5
   148    147   .TP
   149         -\fB\-options \fIoptions\fR
          148  +\fB-options \fIoptions\fR
   150    149   .VS 8.5
   151    150   The value \fIoptions\fR must be a valid dictionary.  The entries of that
   152    151   dictionary are treated as additional \fIoption value\fR pairs for the
   153    152   \fBreturn\fR command.
   154    153   .VE 8.5
   155    154   .SH "RETURN CODE HANDLING MECHANISMS"
   156    155   .PP
................................................................................
   166    165   of the call stack.  It is also the mechanism by which commands
   167    166   like \fBbreak\fR, \fBcontinue\fR, and \fBreturn\fR cause script
   168    167   evaluation to terminate without evaluating all commands in sequence.
   169    168   .PP
   170    169   Some of Tcl's built-in commands evaluate scripts as part of their
   171    170   functioning.  These commands can make use of exceptional return
   172    171   codes to enable special features.  For example, the built-in
   173         -Tcl commands that provide loops \(em such as \fBwhile\fR, \fBfor\fR,
   174         -and \fBforeach\fR \(em evaluate a script that is the body of the
          172  +Tcl commands that provide loops -- such as \fBwhile\fR, \fBfor\fR,
          173  +and \fBforeach\fR -- evaluate a script that is the body of the
   175    174   loop.  If evaluation of the loop body returns the return code
   176    175   of \fBTCL_BREAK\fR or \fBTCL_CONTINUE\fR, the loop command can react in such
   177    176   a way as to give the \fBbreak\fR and \fBcontinue\fR commands
   178    177   their documented interpretation in loops.
   179    178   .PP
   180    179   .VS 8.5
   181    180   Procedure invocation also involves evaluation of a script, the body
   182    181   of the procedure.  Procedure invocation provides special treatment
   183    182   when evaluation of the procedure body returns the return code 
   184         -\fBTCL_RETURN\fR.  In that circumstance, the \fB\-level\fR entry in the
          183  +\fBTCL_RETURN\fR.  In that circumstance, the \fB-level\fR entry in the
   185    184   return options dictionary is decremented.  If after decrementing,
   186         -the value of the \fB\-level\fR entry is 0, then the value of
   187         -the \fB\-code\fR entry becomes the return code of the procedure.
   188         -If after decrementing, the value of the \fB\-level\fR entry is
          185  +the value of the \fB-level\fR entry is 0, then the value of
          186  +the \fB-code\fR entry becomes the return code of the procedure.
          187  +If after decrementing, the value of the \fB-level\fR entry is
   189    188   greater than zero, then the return code of the procedure is
   190    189   \fBTCL_RETURN\fR.  If the procedure invocation occurred during the
   191    190   evaluation of the body of another procedure, the process will
   192    191   repeat itself up the call stack, decrementing the value of the
   193         -\fB\-level\fR entry at each level, so that the \fIcode\fR will
          192  +\fB-level\fR entry at each level, so that the \fIcode\fR will
   194    193   be the return code of the current command \fIlevel\fR levels
   195    194   up the call stack.  The \fBsource\fR command performs the
   196    195   same handling of the \fBTCL_RETURN\fR return code, which explains
   197    196   the similarity of \fBreturn\fR invocation during a \fBsource\fR
   198    197   to \fBreturn\fR invocation within a procedure.
   199    198   .PP
   200    199   The return code of the \fBreturn\fR command itself triggers this
   201    200   special handling by procedure invocation.  If \fBreturn\fR
   202         -is provided the option \fB\-level 0\fR, then the return code
          201  +is provided the option \fB-level 0\fR, then the return code
   203    202   of the \fBreturn\fR command itself will be the value \fIcode\fR
   204         -of the \fB\-code\fR option (or \fBTCL_OK\fR by default).  Any other value
   205         -for the \fB\-level\fR option (including the default value of 1)
          203  +of the \fB-code\fR option (or \fBTCL_OK\fR by default).  Any other value
          204  +for the \fB-level\fR option (including the default value of 1)
   206    205   will cause the return code of the \fBreturn\fR command itself
   207    206   to be \fBTCL_RETURN\fR, triggering a return from the enclosing procedure.
   208    207   .VE 8.5
   209    208   .SH EXAMPLES
   210    209   First, a simple example of using \fBreturn\fR to return from a
   211    210   procedure, interrupting the procedure body.
   212    211   .CS
................................................................................
   220    219   Next, an example of using \fBreturn\fR to set the value
   221    220   returned by the procedure.
   222    221   .CS
   223    222   proc returnX {} {\fBreturn\fR X}
   224    223   puts [returnX]    ;# prints "X"
   225    224   .CE
   226    225   .PP
   227         -Next, a more complete example, using
   228         -.QW "\fBreturn \-code error\fR"
          226  +Next, a more complete example, using \fBreturn -code error\fR
   229    227   to report invalid arguments.
   230    228   .CS
   231    229   proc factorial {n} {
   232    230      if {![string is integer $n] || ($n < 0)} {
   233         -      \fBreturn\fR -code error \e
   234         -            "expected non-negative integer,\e
   235         -             but got \e"$n\e""
          231  +      \fBreturn\fR -code error \\
          232  +            "expected non-negative integer,\\
          233  +             but got \\"$n\\""
   236    234      }
   237    235      if {$n < 2} {
   238    236         \fBreturn\fR 1
   239    237      }
   240    238      set m [expr {$n - 1}]
   241    239      set code [catch {factorial $m} factor]
   242    240      if {$code != 0} {
   243    241         \fBreturn\fR -code $code $factor
   244    242      }
   245    243      set product [expr {$n * $factor}]
   246    244      if {$product < 0} {
   247         -      \fBreturn\fR -code error \e
          245  +      \fBreturn\fR -code error \\
   248    246               "overflow computing factorial of $n"
   249    247      }
   250    248      \fBreturn\fR $product
   251    249   }
   252    250   .CE
   253    251   .PP
   254    252   Next, a procedure replacement for \fBbreak\fR.
................................................................................
   255    253   .CS
   256    254   proc myBreak {} {
   257    255      \fBreturn\fR -code break
   258    256   }
   259    257   .CE
   260    258   .PP
   261    259   .VS 8.5
   262         -With the \fB\-level 0\fR option, \fBreturn\fR itself can serve
          260  +With the \fB-level 0\fR option, \fBreturn\fR itself can serve
   263    261   as a replacement for \fBbreak\fR.
   264    262   .CS
   265    263   interp alias {} Break {} \fBreturn\fR -level 0 -code break
   266    264   .CE
   267    265   .PP
   268         -An example of using \fBcatch\fR and \fBreturn \-options\fR to
          266  +An example of using \fBcatch\fR and \fBreturn -options\fR to
   269    267   re-raise a caught error:
   270    268   .CS
   271    269   proc doSomething {} {
   272    270      set resource [allocate]
   273    271      catch {
   274    272         # Long script of operations
   275    273         # that might raise an error
................................................................................
   290    288      }
   291    289      set options [dict merge {-level 1} $args]
   292    290      dict incr options -level
   293    291      \fBreturn\fR -options $options $result
   294    292   }
   295    293   .CE
   296    294   .VE 8.5
          295  +
   297    296   .SH "SEE ALSO"
   298         -break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n),
   299         -tclvars(n)
          297  +break(n), catch(n), continue(n), dict(n), error(n), proc(n), source(n), tclvars(n)
          298  +
   300    299   .SH KEYWORDS
   301    300   break, catch, continue, error, procedure, return

Changes to doc/scan.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2000 Scriptics Corporation.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: scan.n,v 1.20 2007/10/24 14:29:39 dkf Exp $
            9  +'\" RCS: @(#) $Id: scan.n,v 1.21 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH scan n 8.4 Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   scan \- Parse string using conversion specifiers in the style of sscanf
................................................................................
    56     56   first skips any white-space characters in \fIstring\fR (unless the
    57     57   conversion character is \fB[\fR or \fBc\fR).
    58     58   Then it converts the next input characters according to the 
    59     59   conversion specifier and stores the result in the variable given
    60     60   by the next argument to \fBscan\fR.
    61     61   .PP
    62     62   If the \fB%\fR is followed by a decimal number and a \fB$\fR, as in
    63         -.QW \fB%2$d\fR ,
    64         -then the variable to use is not taken from the next
           63  +``\fB%2$d\fR'', then the variable to use is not taken from the next
    65     64   sequential argument.  Instead, it is taken from the argument indicated
    66     65   by the number, where 1 corresponds to the first \fIvarName\fR.  If
    67     66   there are any positional specifiers in \fIformat\fR then all of the
    68     67   specifiers must be positional.  Every \fIvarName\fR on the argument
    69     68   list must correspond to exactly one conversion specifier or an error
    70     69   is generated, or in the inline case, any position can be specified
    71     70   at most once and the empty positions will be filled in with empty strings.

Changes to doc/source.n.

     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2000 Scriptics Corporation.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: source.n,v 1.13 2007/10/25 14:07:32 dkf Exp $
            9  +'\" RCS: @(#) $Id: source.n,v 1.14 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH source n "" Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   source \- Evaluate a file or resource as a Tcl script
................................................................................
    17     17   .SH SYNOPSIS
    18     18   \fBsource \fIfileName\fR
    19     19   .sp
    20     20   .VS 8.5
    21     21   \fBsource\fR \fB\-encoding \fIencodingName fileName\fR
    22     22   .VE 8.5
    23     23   .BE
           24  +
    24     25   .SH DESCRIPTION
    25     26   .PP
    26     27   This command takes the contents of the specified file or resource
    27     28   and passes it to the Tcl interpreter as a text script.  The return
    28     29   value from \fBsource\fR is the return value of the last command
    29     30   executed in the script.  If an error occurs in evaluating the contents
    30     31   of the script then the \fBsource\fR command will return that error.
    31     32   If a \fBreturn\fR command is invoked from within the script then the
    32     33   remainder of the file will be skipped and the \fBsource\fR command
    33     34   will return normally with the result from the \fBreturn\fR command.
    34     35   .PP
    35         -The end-of-file character for files is
    36         -.QW \e032
    37         -(^Z) for all platforms. The source command will read files up to this
    38         -character.  This
           36  +The end-of-file character for files is '\\32' (^Z) for all platforms.
           37  +The source command will read files up to this character.  This
    39     38   restriction does not exist for the \fBread\fR or \fBgets\fR commands,
    40     39   allowing for files containing code and data segments (scripted documents).
    41         -If you require a
    42         -.QW ^Z
    43         -in code for string comparison, you can use
    44         -.QW \e032
    45         -or
    46         -.QW \eu001a ,
    47         -which will be safely substituted by the Tcl
    48         -interpreter into
    49         -.QW ^Z .
           40  +If you require a ``^Z'' in code for string comparison, you can use
           41  +``\\032'' or ``\\u001a'', which will be safely substituted by the Tcl
           42  +interpreter into ``^Z''.
    50     43   .PP
    51     44   .VS 8.5
    52     45   The \fB-encoding\fR option is used to specify the encoding of
    53     46   the data stored in \fIfileName\fR.  When the \fB-encoding\fR option
    54     47   is omitted, the system encoding is assumed.
    55     48   .VE 8.5
    56     49   .SH EXAMPLE
    57     50   Run the script in the file \fBfoo.tcl\fR and then the script in the
    58     51   file \fBbar.tcl\fR:
    59     52   .CS
    60     53   \fBsource\fR foo.tcl
    61     54   \fBsource\fR bar.tcl
    62     55   .CE
    63         -.PP
    64     56   Alternatively:
    65     57   .CS
    66     58   foreach scriptFile {foo.tcl bar.tcl} {
    67     59      \fBsource\fR $scriptFile
    68     60   }
    69     61   .CE
           62  +
    70     63   .SH "SEE ALSO"
    71     64   file(n), cd(n), encoding(n), info(n)
           65  +
    72     66   .SH KEYWORDS
    73     67   file, script

Changes to doc/split.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: split.n,v 1.6 2007/10/25 09:25:27 dkf Exp $
            8  +'\" RCS: @(#) $Id: split.n,v 1.7 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH split n "" Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   split \- Split a string into a proper Tcl list
    16     16   .SH SYNOPSIS
    17     17   \fBsplit \fIstring \fR?\fIsplitChars\fR?
    18     18   .BE
           19  +
    19     20   .SH DESCRIPTION
    20     21   .PP
    21     22   Returns a list created by splitting \fIstring\fR at each character
    22     23   that is in the \fIsplitChars\fR argument.
    23     24   Each element of the result list will consist of the
    24     25   characters from \fIstring\fR that lie between instances of the
    25     26   characters in \fIsplitChars\fR.
................................................................................
    28     29   character of \fIstring\fR is in \fIsplitChars\fR.
    29     30   If \fIsplitChars\fR is an empty string then each character of
    30     31   \fIstring\fR becomes a separate element of the result list.
    31     32   \fISplitChars\fR defaults to the standard white-space characters.
    32     33   .SH EXAMPLES
    33     34   Divide up a USENET group name into its hierarchical components:
    34     35   .CS
    35         -.ta 2i
    36     36   \fBsplit\fR "comp.lang.tcl.announce" .
    37         -	\fB\(->\fI comp lang tcl announce\fR
           37  +     \fI=> comp lang tcl announce\fR
    38     38   .CE
    39     39   .PP
    40     40   See how the \fBsplit\fR command splits on \fIevery\fR character in
    41     41   \fIsplitChars\fR, which can result in information loss if you are not
    42     42   careful:
    43     43   .CS
    44         -.ta 2i
    45     44   \fBsplit\fR "alpha beta gamma" "temp"
    46         -	\fB\(->\fI al {ha b} {} {a ga} {} a\fR
           45  +     \fI=> al {ha b} {} {a ga} {} a\fR
    47     46   .CE
    48     47   .PP
    49     48   Extract the list words from a string that is not a well-formed list:
    50     49   .CS
    51         -.ta 2i
    52     50   \fBsplit\fR "Example with {unbalanced brace character"
    53         -	\fB\(->\fI Example with \\{unbalanced brace character\fR
           51  +     \fI=> Example with \\{unbalanced brace character\fR
    54     52   .CE
    55     53   .PP
    56     54   Split a string into its constituent characters
    57     55   .CS
    58         -.ta 2i
    59     56   \fBsplit\fR "Hello world" {}
    60         -	\fB\(->\fI H e l l o { } w o r l d\fR
           57  +     \fI=> H e l l o { } w o r l d\fR
    61     58   .CE
    62     59   .SS "PARSING RECORD-ORIENTED FILES"
    63     60   Parse a Unix /etc/passwd file, which consists of one entry per line,
    64     61   with each line consisting of a colon-separated list of fields:
    65     62   .CS
    66     63   ## Read the file
    67     64   set fid [open /etc/passwd]
................................................................................
    79     76   
    80     77      ## Assign fields to variables and print some out...
    81     78      lassign $fields \\
    82     79            userName password uid grp longName homeDir shell
    83     80      puts "$longName uses [file tail $shell] for a login shell"
    84     81   }
    85     82   .CE
           83  +
    86     84   .SH "SEE ALSO"
    87     85   join(n), list(n), string(n)
           86  +
    88     87   .SH KEYWORDS
    89     88   list, split, string

Changes to doc/string.n.

     1      1   .\"
     2      2   .\" Copyright (c) 1993 The Regents of the University of California.
     3      3   .\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   .\"
     5      5   .\" See the file "license.terms" for information on usage and redistribution
     6      6   .\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   .\" 
     8         -.\" RCS: @(#) $Id: string.n,v 1.37 2007/10/25 14:07:32 dkf Exp $
            8  +.\" RCS: @(#) $Id: string.n,v 1.38 2007/10/26 20:11:53 dgp Exp $
     9      9   .\" 
    10     10   .so man.macros
    11     11   .TH string n 8.1 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   .\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   string \- Manipulate strings
    16     16   .SH SYNOPSIS
    17     17   \fBstring \fIoption arg \fR?\fIarg ...?\fR
    18     18   .BE
           19  +
    19     20   .SH DESCRIPTION
    20     21   .PP
    21     22   Performs one of several string operations, depending on \fIoption\fR.
    22     23   The legal \fIoption\fRs (which may be abbreviated) are:
    23     24   .TP
    24     25   \fBstring bytelength \fIstring\fR
    25         -.
    26     26   Returns a decimal string giving the number of bytes used to represent
    27     27   \fIstring\fR in memory.  Because UTF\-8 uses one to three bytes to
    28     28   represent Unicode characters, the byte length will not be the same as
    29     29   the character length in general.  The cases where a script cares about
    30     30   the byte length are rare.  In almost all cases, you should use the
    31     31   \fBstring length\fR operation (including determining the length of a
    32     32   Tcl ByteArray object).  Refer to the \fBTcl_NumUtfChars\fR manual
    33     33   entry for more details on the UTF\-8 representation.
    34     34   .TP
    35     35   \fBstring compare\fR ?\fB\-nocase\fR? ?\fB\-length int\fR? \fIstring1 string2\fR
    36         -.
    37     36   Perform a character-by-character comparison of strings \fIstring1\fR
    38     37   and \fIstring2\fR.  Returns \-1, 0, or 1, depending on whether
    39     38   \fIstring1\fR is lexicographically less than, equal to, or greater
    40     39   than \fIstring2\fR.  If \fB\-length\fR is specified, then only the
    41     40   first \fIlength\fR characters are used in the comparison.  If
    42     41   \fB\-length\fR is negative, it is ignored.  If \fB\-nocase\fR is
    43     42   specified, then the strings are compared in a case-insensitive manner.
    44     43   .TP
    45     44   \fBstring equal\fR ?\fB\-nocase\fR? ?\fB-length int\fR? \fIstring1 string2\fR
    46         -.
    47     45   Perform a character-by-character comparison of strings \fIstring1\fR
    48     46   and \fIstring2\fR.  Returns 1 if \fIstring1\fR and \fIstring2\fR are
    49     47   identical, or 0 when not.  If \fB\-length\fR is specified, then only
    50     48   the first \fIlength\fR characters are used in the comparison.  If
    51     49   \fB\-length\fR is negative, it is ignored.  If \fB\-nocase\fR is
    52     50   specified, then the strings are compared in a case-insensitive manner.
    53     51   .TP
    54     52   \fBstring first \fIneedleString haystackString\fR ?\fIstartIndex\fR?
    55         -.
    56     53   Search \fIhaystackString\fR for a sequence of characters that exactly match
    57     54   the characters in \fIneedleString\fR.  If found, return the index of the
    58     55   first character in the first such match within \fIhaystackString\fR.  If not
    59     56   found, return \-1.  If \fIstartIndex\fR is specified (in any of the
    60     57   forms accepted by the \fBindex\fR method), then the search is
    61     58   constrained to start with the character in \fIhaystackString\fR specified by
    62     59   the index.  For example,
................................................................................
    68     65   .CS
    69     66   \fBstring first a 0123456789abcdef 11\fR
    70     67   .CE
    71     68   will return \fB\-1\fR.
    72     69   .RE
    73     70   .TP
    74     71   \fBstring index \fIstring charIndex\fR
    75         -.
    76     72   Returns the \fIcharIndex\fR'th character of the \fIstring\fR argument.
    77     73   A \fIcharIndex\fR of 0 corresponds to the first character of the
    78     74   string.  \fIcharIndex\fR may be specified as follows:
    79     75   .VS 8.5
    80     76   .RS
    81     77   .IP \fIinteger\fR 10
    82     78   For any index value that passes \fBstring is integer -strict\fR,
    83     79   the char specified at this integral index
    84         -(e.g. \fB2\fR would refer to the
    85         -.QW "c"
    86         -in
    87         -.QW "abcd" ).
           80  +(e.g. \fB2\fR would refer to the "c" in "abcd").
    88     81   .IP \fBend\fR 10
    89     82   The last char of the string
    90         -(e.g. \fBend\fR would refer to the
    91         -.QW "d"
    92         -in
    93         -.QW "abcd" ).
           83  +(e.g. \fBend\fR would refer to the "d" in "abcd").
    94     84   .IP \fBend\fR\-\fIN\fR 10
    95     85   The last char of the string minus the specified integer offset \fIN\fR
    96         -(e.g. \fBend\fR\-1 would refer to the
    97         -.QW "c"
    98         -in
    99         -.QW "abcd" ).
           86  +(e.g. \fBend\fR\-1 would refer to the "c" in "abcd").
   100     87   .IP \fBend\fR+\fIN\fR 10
   101     88   The last char of the string plus the specified integer offset \fIN\fR
   102         -(e.g. \fBend\fR+\-1 would refer to the
   103         -.QW "c"
   104         -in
   105         -"abcd" ).
           89  +(e.g. \fBend\fR+\-1 would refer to the "c" in "abcd").
   106     90   .IP \fIM\fR+\fIN\fR 10
   107     91   The char specified at the integral index that is the sum of 
   108     92   integer values \fIM\fR and \fIN\fR
   109         -(e.g. \fB1+1\fR would refer to the
   110         -.QW "c"
   111         -in
   112         -.QW "abcd" ).
           93  +(e.g. \fB1+1\fR would refer to the "c" in "abcd").
   113     94   .IP \fIM\fR\-\fIN\fR 10
   114     95   The char specified at the integral index that is the difference of 
   115     96   integer values \fIM\fR and \fIN\fR
   116         -(e.g. \fB2\-1\fR would refer to the
   117         -.QW "b"
   118         -in
   119         -.QW "abcd" ).
           97  +(e.g. \fB2\-1\fR would refer to the "b" in "abcd").
   120     98   .PP
   121     99   In the specifications above, the integer value \fIM\fR contains no
   122    100   trailing whitespace and the integer value \fIN\fR contains no
   123    101   leading whitespace.
   124    102   .PP
   125    103   If \fIcharIndex\fR is less than 0 or greater than or equal to the
   126    104   length of the string then this command returns an empty string.
   127    105   .RE
   128    106   .VE
   129    107   .TP
   130    108   \fBstring is \fIclass\fR ?\fB\-strict\fR? ?\fB\-failindex \fIvarname\fR? \fIstring\fR
   131         -.
   132    109   Returns 1 if \fIstring\fR is a valid member of the specified character
   133    110   class, otherwise returns 0.  If \fB\-strict\fR is specified, then an
   134    111   empty string returns 0, otherwise an empty string will return 1 on
   135    112   any class.  If \fB\-failindex\fR is specified, then if the function
   136    113   returns 0, the index in the string where the class was no longer valid
   137    114   will be stored in the variable named \fIvarname\fR.  The \fIvarname\fR
   138    115   will not be set if the function returns 1.  The following character
................................................................................
   164    141   .IP \fBinteger\fR 12
   165    142   Any of the valid string formats for a 32-bit integer value in Tcl,
   166    143   with optional surrounding whitespace.  In case of under/overflow in
   167    144   the value, 0 is returned and the \fIvarname\fR will contain \-1.
   168    145   .IP \fBlist\fR 12
   169    146   Any proper list structure, with optional surrounding whitespace. In
   170    147   case of improper list structure, 0 is returned and the \fIvarname\fR
   171         -will contain the index of the
   172         -.QW element
   173         -where the list parsing fails, or \-1 if this cannot be determined.
          148  +will contain the index of the "element" where the list parsing fails,
          149  +or \-1 if this cannot be determined.
   174    150   .IP \fBlower\fR 12
   175    151   Any Unicode lower case alphabet character.
   176    152   .IP \fBprint\fR 12
   177    153   Any Unicode printing character, including space.
   178    154   .IP \fBpunct\fR 12
   179    155   Any Unicode punctuation character.
   180    156   .IP \fBspace\fR 12
................................................................................
   198    174   .PP
   199    175   In the case of \fBboolean\fR, \fBtrue\fR and \fBfalse\fR, if the
   200    176   function will return 0, then the \fIvarname\fR will always be set to
   201    177   0, due to the varied nature of a valid boolean value.
   202    178   .RE
   203    179   .TP
   204    180   \fBstring last \fIneedleString haystackString\fR ?\fIlastIndex\fR?
   205         -.
   206    181   Search \fIhaystackString\fR for a sequence of characters that exactly match
   207    182   the characters in \fIneedleString\fR.  If found, return the index of the
   208    183   first character in the last such match within \fIhaystackString\fR.  If there
   209    184   is no match, then return \-1.  If \fIlastIndex\fR is specified (in any
   210    185   of the forms accepted by the \fBindex\fR method), then only the
   211    186   characters in \fIhaystackString\fR at or before the specified \fIlastIndex\fR
   212    187   will be considered by the search.  For example,
................................................................................
   218    193   .CS
   219    194   \fBstring last a 0a23456789abcdef 9\fR
   220    195   .CE
   221    196   will return \fB1\fR.
   222    197   .RE
   223    198   .TP
   224    199   \fBstring length \fIstring\fR
   225         -.
   226    200   Returns a decimal string giving the number of characters in
   227    201   \fIstring\fR.  Note that this is not necessarily the same as the
   228    202   number of bytes used to store the string.  If the object is a
   229    203   ByteArray object (such as those returned from reading a binary encoded
   230    204   channel), then this will return the actual byte length of the object.
   231    205   .TP
   232    206   \fBstring map\fR ?\fB\-nocase\fR? \fImapping string\fR
   233         -.
   234    207   Replaces substrings in \fIstring\fR based on the key-value pairs in
   235    208   \fImapping\fR.  \fImapping\fR is a list of \fIkey value key value ...\fR
   236    209   as in the form returned by \fBarray get\fR.  Each instance of a
   237    210   key in the string will be replaced with its corresponding value.  If
   238    211   \fB\-nocase\fR is specified, then matching is done without regard to
   239    212   case differences. Both \fIkey\fR and \fIvalue\fR may be multiple
   240    213   characters.  Replacement is done in an ordered manner, so the key
................................................................................
   253    226   .CS
   254    227   \fBstring map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc\fR
   255    228   .CE
   256    229   it will return the string \fB02c322c222c\fR.
   257    230   .RE
   258    231   .TP
   259    232   \fBstring match\fR ?\fB\-nocase\fR? \fIpattern\fR \fIstring\fR
   260         -.
   261    233   See if \fIpattern\fR matches \fIstring\fR; return 1 if it does, 0 if
   262    234   it doesn't.  If \fB\-nocase\fR is specified, then the pattern attempts
   263    235   to match against the string in a case insensitive manner.  For the two
   264    236   strings to match, their contents must be identical except that the
   265    237   following special sequences may appear in \fIpattern\fR:
   266    238   .RS
   267    239   .IP \fB*\fR 10
................................................................................
   270    242   .IP \fB?\fR 10
   271    243   Matches any single character in \fIstring\fR.
   272    244   .IP \fB[\fIchars\fB]\fR 10
   273    245   Matches any character in the set given by \fIchars\fR.  If a sequence
   274    246   of the form \fIx\fB\-\fIy\fR appears in \fIchars\fR, then any
   275    247   character between \fIx\fR and \fIy\fR, inclusive, will match.  When
   276    248   used with \fB\-nocase\fR, the end points of the range are converted to
   277         -lower case first.  Whereas
   278         -.QW [A\-z]
   279         -matches
   280         -.QW _
   281         -when matching case-sensitively (since
   282         -.QW _
   283         -falls between the
   284         -.QW Z
   285         -and
   286         -.QW a ),
   287         -with \fB\-nocase\fR this is considered like
   288         -.QW [A\-Za\-z]
   289         -(and probably what was meant in the first place).
          249  +lower case first.  Whereas {[A\-z]} matches '_' when matching
          250  +case-sensitively ('_' falls between the 'Z' and 'a'), with
          251  +\fB\-nocase\fR this is considered like {[A\-Za\-z]} (and probably what
          252  +was meant in the first place).
   290    253   .IP \fB\e\fIx\fR 10
   291         -Matches the single character \fIx\fR. This provides a way of avoiding
          254  +Matches the single character \fIx\fR.  This provides a way of avoiding
   292    255   the special interpretation of the characters \fB*?[]\e\fR in
   293    256   \fIpattern\fR.
   294    257   .RE
   295    258   .TP
   296    259   \fBstring range \fIstring first last\fR
   297         -.
   298    260   Returns a range of consecutive characters from \fIstring\fR, starting
   299    261   with the character whose index is \fIfirst\fR and ending with the
   300    262   character whose index is \fIlast\fR. An index of 0 refers to the first
   301    263   character of the string.  \fIfirst\fR and \fIlast\fR may be specified
   302    264   as for the \fBindex\fR method.  If \fIfirst\fR is less than zero then
   303    265   it is treated as if it were zero, and if \fIlast\fR is greater than or
   304    266   equal to the length of the string then it is treated as if it were
   305    267   \fBend\fR.  If \fIfirst\fR is greater than \fIlast\fR then an empty
   306    268   string is returned.
   307    269   .TP
   308    270   \fBstring repeat \fIstring count\fR
   309         -.
   310         -Returns the concatenation of \fIstring\fR repeated \fIcount\fR number
   311         -of times.
          271  +Returns \fIstring\fR repeated \fIcount\fR number of times.
   312    272   .TP
   313    273   \fBstring replace \fIstring first last\fR ?\fInewstring\fR?
   314         -.
   315    274   Removes a range of consecutive characters from \fIstring\fR, starting
   316    275   with the character whose index is \fIfirst\fR and ending with the
   317    276   character whose index is \fIlast\fR.  An index of 0 refers to the
   318    277   first character of the string.  \fIFirst\fR and \fIlast\fR may be
   319    278   specified as for the \fBindex\fR method.  If \fInewstring\fR is
   320    279   specified, then it is placed in the removed character range.  If
   321    280   \fIfirst\fR is less than zero then it is treated as if it were zero,
   322    281   and if \fIlast\fR is greater than or equal to the length of the string
   323    282   then it is treated as if it were \fBend\fR.  If \fIfirst\fR is greater
   324    283   than \fIlast\fR or the length of the initial string, or \fIlast\fR is
   325    284   less than 0, then the initial string is returned untouched.
          285  +.VS 8.5
   326    286   .TP
   327    287   \fBstring reverse \fIstring\fR
   328         -.
   329         -.VS 8.5
   330    288   Returns a string that is the same length as \fIstring\fR but with its
   331    289   characters in the reverse order.
   332    290   .VE 8.5
   333    291   .TP
   334    292   \fBstring tolower \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
   335         -.
   336    293   Returns a value equal to \fIstring\fR except that all upper (or title)
   337    294   case letters have been converted to lower case.  If \fIfirst\fR is
   338    295   specified, it refers to the first char index in the string to start
   339    296   modifying.  If \fIlast\fR is specified, it refers to the char index in
   340    297   the string to stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be
   341    298   specified as for the \fBindex\fR method.
   342    299   .TP
   343    300   \fBstring totitle \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
   344         -.
   345    301   Returns a value equal to \fIstring\fR except that the first character
   346    302   in \fIstring\fR is converted to its Unicode title case variant (or
   347    303   upper case if there is no title case variant) and the rest of the
   348    304   string is converted to lower case.  If \fIfirst\fR is specified, it
   349    305   refers to the first char index in the string to start modifying.  If
   350    306   \fIlast\fR is specified, it refers to the char index in the string to
   351    307   stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be specified as
   352    308   for the \fBindex\fR method.
   353    309   .TP
   354    310   \fBstring toupper \fIstring\fR ?\fIfirst\fR? ?\fIlast\fR?
   355         -.
   356    311   Returns a value equal to \fIstring\fR except that all lower (or title)
   357    312   case letters have been converted to upper case.  If \fIfirst\fR is
   358    313   specified, it refers to the first char index in the string to start
   359    314   modifying.  If \fIlast\fR is specified, it refers to the char index in
   360    315   the string to stop at (inclusive).  \fIfirst\fR and \fIlast\fR may be
   361    316   specified as for the \fBindex\fR method.
   362    317   .TP
   363    318   \fBstring trim \fIstring\fR ?\fIchars\fR?
   364         -.
   365    319   Returns a value equal to \fIstring\fR except that any leading or
   366    320   trailing characters present in the string given by \fIchars\fR are removed.  If
   367    321   \fIchars\fR is not specified then white space is removed (spaces,
   368    322   tabs, newlines, and carriage returns).
   369    323   .TP
   370    324   \fBstring trimleft \fIstring\fR ?\fIchars\fR?
   371         -.
   372    325   Returns a value equal to \fIstring\fR except that any leading
   373    326   characters present in the string given by \fIchars\fR are removed.  If
   374    327   \fIchars\fR is not specified then white space is removed (spaces,
   375    328   tabs, newlines, and carriage returns).
   376    329   .TP
   377    330   \fBstring trimright \fIstring\fR ?\fIchars\fR?
   378         -.
   379    331   Returns a value equal to \fIstring\fR except that any trailing
   380    332   characters present in the string given by \fIchars\fR are removed.  If
   381    333   \fIchars\fR is not specified then white space is removed (spaces,
   382    334   tabs, newlines, and carriage returns).
   383    335   .TP
   384    336   \fBstring wordend \fIstring charIndex\fR
   385         -.
   386    337   Returns the index of the character just after the last one in the word
   387    338   containing character \fIcharIndex\fR of \fIstring\fR.  \fIcharIndex\fR
   388    339   may be specified as for the \fBindex\fR method.  A word is
   389    340   considered to be any contiguous range of alphanumeric (Unicode letters
   390    341   or decimal digits) or underscore (Unicode connector punctuation)
   391    342   characters, or any single character other than these.
   392    343   .TP
   393    344   \fBstring wordstart \fIstring charIndex\fR
   394         -.
   395    345   Returns the index of the first character in the word containing
   396    346   character \fIcharIndex\fR of \fIstring\fR.  \fIcharIndex\fR may be
   397    347   specified as for the \fBindex\fR method.  A word is considered to be any
   398    348   contiguous range of alphanumeric (Unicode letters or decimal digits)
   399    349   or underscore (Unicode connector punctuation) characters, or any
   400    350   single character other than these.
   401    351   .SH EXAMPLE
................................................................................
   405    355   set length [\fBstring length\fR $string]
   406    356   if {$length == 0} {
   407    357      set isPrefix 0
   408    358   } else {
   409    359      set isPrefix [\fBstring equal\fR -length $length $string "foobar"]
   410    360   }
   411    361   .CE
          362  +
   412    363   .SH "SEE ALSO"
   413    364   expr(n), list(n)
          365  +
   414    366   .SH KEYWORDS
   415    367   case conversion, compare, index, match, pattern, string, word, equal,
   416    368   ctype, character, reverse
          369  +
   417    370   .\" Local Variables:
   418    371   .\" mode: nroff
   419    372   .\" End:

Changes to doc/subst.n.

     2      2   '\" Copyright (c) 1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\" Copyright (c) 2001 Donal K. Fellows
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\" 
     9         -'\" RCS: @(#) $Id: subst.n,v 1.11 2007/10/26 12:25:06 dkf Exp $
            9  +'\" RCS: @(#) $Id: subst.n,v 1.12 2007/10/26 20:11:53 dgp Exp $
    10     10   '\" 
    11     11   .so man.macros
    12     12   .TH subst n 7.4 Tcl "Tcl Built-In Commands"
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16     16   subst \- Perform backslash, command, and variable substitutions
................................................................................
    52     52   raised the exception.  If a continue exception occurs during the
    53     53   evaluation of a command or variable substitution, an empty string
    54     54   will be substituted for that entire command or variable substitution
    55     55   (as long as it is well-formed Tcl.)  If a return exception occurs,
    56     56   or any other return code is returned during command or variable
    57     57   substitution, then the returned value is substituted for that
    58     58   substitution.  See the EXAMPLES below.  In this way, all exceptional
    59         -return codes are
    60         -.QW caught
    61         -by \fBsubst\fR.  The \fBsubst\fR command
           59  +return codes are ``caught'' by \fBsubst\fR.  The \fBsubst\fR command
    62     60   itself will either return an error, or will complete successfully.
    63     61   .SH EXAMPLES
    64     62   .PP
    65     63   When it performs its substitutions, \fIsubst\fR does not give any
    66     64   special treatment to double quotes or curly braces (except within
    67     65   command substitutions) so the script
    68     66   .CS
    69     67   set a 44
    70     68   \fBsubst\fR {xyz {$a}}
    71     69   .CE
    72         -returns
    73         -.QW "\fBxyz {44}\fR" ,
    74         -not
    75         -.QW "\fBxyz {$a}\fR"
           70  +returns ``\fBxyz {44}\fR'', not ``\fBxyz {$a}\fR''
    76     71   and the script
    77     72   .CS
    78         -set a "p\e} q \e{r"
           73  +set a "p\\} q \\{r"
    79     74   \fBsubst\fR {xyz {$a}}
    80     75   .CE
    81         -return
    82         -.QW "\fBxyz {p} q {r}\fR" ,
    83         -not
    84         -.QW "\fBxyz {p\e} q \e{r}\fR" .
           76  +return ``\fBxyz {p} q {r}\fR'', not ``\fBxyz {p\\} q \\{r}\fR''.
    85     77   .PP
    86     78   When command substitution is performed, it includes any variable
    87     79   substitution necessary to evaluate the script.  
    88     80   .CS
    89     81   set a 44
    90     82   \fBsubst\fR -novariables {$a [format $a]}
    91     83   .CE
    92         -returns
    93         -.QW "\fB$a 44\fR" ,
    94         -not
    95         -.QW "\fB$a $a\fR" .
    96         -Similarly, when
           84  +returns ``\fB$a 44\fR'', not ``\fB$a $a\fR''.  Similarly, when
    97     85   variable substitution is performed, it includes any command
    98     86   substitution necessary to retrieve the value of the variable.
    99     87   .CS
   100     88   proc b {} {return c}
   101     89   array set a {c c [b] tricky}
   102     90   \fBsubst\fR -nocommands {[b] $a([b])}
   103     91   .CE
   104         -returns
   105         -.QW "\fB[b] c\fR" ,
   106         -not
   107         -.QW "\fB[b] tricky\fR".
           92  +returns ``\fB[b] c\fR'', not ``\fB[b] tricky\fR''.
   108     93   .PP
   109     94   The continue and break exceptions allow command substitutions to
   110     95   prevent substitution of the rest of the command substitution and the
   111     96   rest of \fIstring\fR respectively, giving script authors more options
   112     97   when processing text using \fIsubst\fR.  For example, the script
   113     98   .CS
   114     99   \fBsubst\fR {abc,[break],def}
   115    100   .CE
   116         -returns
   117         -.QW \fBabc,\fR ,
   118         -not
   119         -.QW \fBabc,,def\fR
   120         -and the script
          101  +returns ``\fBabc,\fR'', not ``\fBabc,,def\fR'' and the script
   121    102   .CS
   122    103   \fBsubst\fR {abc,[continue;expr {1+2}],def}
   123    104   .CE
   124         -returns
   125         -.QW \fBabc,,def\fR ,
   126         -not
   127         -.QW \fBabc,3,def\fR .
          105  +returns ``\fBabc,,def\fR'', not ``\fBabc,3,def\fR''.
   128    106   .PP
   129    107   Other exceptional return codes substitute the returned value
   130    108   .CS
   131    109   \fBsubst\fR {abc,[return foo;expr {1+2}],def}
   132    110   .CE
   133         -returns
   134         -.QW \fBabc,foo,def\fR ,
   135         -not
   136         -.QW \fBabc,3,def\fR
   137         -and
          111  +returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR'' and
   138    112   .CS
   139    113   \fBsubst\fR {abc,[return -code 10 foo;expr {1+2}],def}
   140    114   .CE
   141         -also returns
   142         -.QW \fBabc,foo,def\fR ,
   143         -not
   144         -.QW \fBabc,3,def\fR .
          115  +also returns ``\fBabc,foo,def\fR'', not ``\fBabc,3,def\fR''.
          116  +
   145    117   .SH "SEE ALSO"
   146    118   Tcl(n), eval(n), break(n), continue(n)
   147    119   
   148    120   .SH KEYWORDS
   149    121   backslash substitution, command substitution, variable substitution

Changes to doc/switch.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: switch.n,v 1.11 2007/10/24 14:29:39 dkf Exp $
            8  +'\" RCS: @(#) $Id: switch.n,v 1.12 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH switch n 8.5 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   switch \- Evaluate one of several scripts, depending on a given value
................................................................................
    98     98   since the braces around the whole list make it unnecessary to include a
    99     99   backslash at the end of each line.
   100    100   Since the \fIpattern\fR arguments are in braces in the second form,
   101    101   no command or variable substitutions are performed on them;  this makes
   102    102   the behavior of the second form different than the first form in some
   103    103   cases.
   104    104   .PP
   105         -If a \fIbody\fR is specified as
   106         -.QW \fB\-\fR
   107         -it means that the \fIbody\fR
          105  +If a \fIbody\fR is specified as ``\fB\-\fR'' it means that the \fIbody\fR
   108    106   for the next pattern should also be used as the body for this
   109         -pattern (if the next pattern also has a body of
   110         -.QW \fB\-\fR
          107  +pattern (if the next pattern also has a body of ``\fB\-\fR''
   111    108   then the body after that is used, and so on).
   112    109   This feature makes it possible to share a single \fIbody\fR among
   113    110   several patterns.
   114    111   .PP
   115    112   Beware of how you place comments in \fBswitch\fR commands.  Comments
   116    113   should only be placed \fBinside\fR the execution body of one of the
   117    114   patterns, and not intermingled with the patterns.

Changes to doc/tclsh.1.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: tclsh.1,v 1.11 2007/10/24 14:29:39 dkf Exp $
            8  +'\" RCS: @(#) $Id: tclsh.1,v 1.12 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH tclsh 1 "" Tcl "Tcl Applications"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   tclsh \- Simple shell containing Tcl interpreter
................................................................................
    44     44   read Tcl commands from the named file;  \fBtclsh\fR will exit
    45     45   when it reaches the end of the file.
    46     46   The end of the file may be marked either by the physical end of
    47     47   the medium, or by the character, '\\032' ('\\u001a', control-Z).
    48     48   If this character is present in the file, the \fBtclsh\fR application
    49     49   will read text up to but not including the character.  An application
    50     50   that requires this character in the file may safely encode it as
    51         -.QW \e032 ,
    52         -.QW \ex1a ,
    53         -or
    54         -.QW \eu001a ;
    55         -or may generate it by use of commands 
           51  +``\\032'', ``\\x1a'', or ``\\u001a''; or may generate it by use of commands 
    56     52   such as \fBformat\fR or \fBbinary\fR.
    57     53   There is no automatic evaluation of \fB.tclshrc\fR when the name
    58     54   of a script file is presented on the \fBtclsh\fR command
    59     55   line, but the script file can always \fBsource\fR it if desired.
    60     56   .PP
    61     57   If you create a Tcl script in a file whose first line is
    62     58   .CS
................................................................................
   123    119   Contains 1 if \fBtclsh\fR is running interactively (no
   124    120   \fIfileName\fR was specified and standard input is a terminal-like
   125    121   device), 0 otherwise.
   126    122   
   127    123   .SH PROMPTS
   128    124   .PP
   129    125   When \fBtclsh\fR is invoked interactively it normally prompts for each
   130         -command with
   131         -.QW "\fB% \fR" .
   132         -You can change the prompt by setting the
          126  +command with ``\fB% \fR''.  You can change the prompt by setting the
   133    127   variables \fBtcl_prompt1\fR and \fBtcl_prompt2\fR.  If variable
   134    128   \fBtcl_prompt1\fR exists then it must consist of a Tcl script
   135    129   to output a prompt;  instead of outputting a prompt \fBtclsh\fR
   136    130   will evaluate the script in \fBtcl_prompt1\fR.
   137    131   The variable \fBtcl_prompt2\fR is used in a similar way when
   138    132   a newline is typed but the current command isn't yet complete;
   139    133   if \fBtcl_prompt2\fR isn't set then no prompt is output for

Changes to doc/tcltest.n.

     4      4   '\" Copyright (c) 1998-1999 Scriptics Corporation
     5      5   '\" Copyright (c) 2000 Ajuba Solutions
     6      6   '\" Contributions from Don Porter, NIST, 2002. (not subject to US copyright)
     7      7   '\"
     8      8   '\" See the file "license.terms" for information on usage and redistribution
     9      9   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
    10     10   '\" 
    11         -'\" RCS: @(#) $Id: tcltest.n,v 1.50 2007/10/25 14:07:32 dkf Exp $
           11  +'\" RCS: @(#) $Id: tcltest.n,v 1.51 2007/10/26 20:11:53 dgp Exp $
    12     12   '\" 
    13     13   .so man.macros
    14     14   .TH "tcltest" n 2.3 tcltest "Tcl Bundled Packages"
    15     15   .BS
    16     16   '\" Note:  do not modify the .SH NAME line immediately below!
    17     17   .SH NAME
    18     18   tcltest \- Test harness support code and utilities
................................................................................
    75     75   tcltest package.
    76     76   .PP
    77     77   All the commands provided by the \fBtcltest\fR package are defined
    78     78   in and exported from the \fB::tcltest\fR namespace, as indicated in
    79     79   the \fBSYNOPSIS\fR above.  In the following sections, all commands
    80     80   will be described by their simple names, in the interest of brevity.
    81     81   .PP
    82         -The central command of \fBtcltest\fR is \fBtest\fR that defines
    83         -and runs a test.  Testing with \fBtest\fR involves evaluation
           82  +The central command of \fBtcltest\fR is [\fBtest\fR] that defines
           83  +and runs a test.  Testing with [\fBtest\fR] involves evaluation
    84     84   of a Tcl script and comparing the result to an expected result, as
    85     85   configured and controlled by a number of options.  Several other
    86     86   commands provided by \fBtcltest\fR govern the configuration of
    87         -\fBtest\fR and the collection of many \fBtest\fR commands into
           87  +[\fBtest\fR] and the collection of many [\fBtest\fR] commands into
    88     88   test suites.
    89     89   .PP
    90     90   See \fBCREATING TEST SUITES WITH TCLTEST\fR below for an extended example
    91     91   of how to use the commands of \fBtcltest\fR to produce test suites
    92     92   for your Tcl-enabled code.
    93     93   .SH COMMANDS
    94     94   .TP
    95     95   \fBtest\fR \fIname description ?option value ...?\fR
    96     96   Defines and possibly runs a test with the name \fIname\fR and
    97     97   description \fIdescription\fR.  The name and description of a test
    98         -are used in messages reported by \fBtest\fR during the
           98  +are used in messages reported by [\fBtest\fR] during the
    99     99   test, as configured by the options of \fBtcltest\fR.  The
   100         -remaining \fIoption value\fR arguments to \fBtest\fR
          100  +remaining \fIoption value\fR arguments to [\fBtest\fR]
   101    101   define the test, including the scripts to run, the conditions
   102    102   under which to run them, the expected result, and the means
   103    103   by which the expected and actual results should be compared.
   104    104   See \fBTESTS\fR below for a complete description of the valid
   105         -options and how they define a test.  The \fBtest\fR command
          105  +options and how they define a test.  The [\fBtest\fR] command
   106    106   returns an empty string.  
   107    107   .TP
   108    108   \fBtest\fR \fIname description ?constraints? body result\fR
   109         -.
   110         -This form of \fBtest\fR is provided to support test suites written
          109  +This form of [\fBtest\fR] is provided to support test suites written
   111    110   for version 1 of the \fBtcltest\fR package, and also a simpler
   112    111   interface for a common usage.  It is the same as
   113         -.QW "\fBtest\fR \fIname description\fB \-constraints \fIconstraints\fB \-body \fIbody\fB \-result \fIresult\fR" .
   114         -All other options to \fBtest\fR
          112  +[\fBtest\fR \fIname description\fB -constraints \fIconstraints\fB -body
          113  +\fIbody\fB -result \fIresult\fR].  All other options to [\fBtest\fR]
   115    114   take their default values.  When \fIconstraints\fR is omitted, this
   116         -form of \fBtest\fR can be distinguished from the first because
   117         -all \fIoption\fRs begin with
   118         -.QW \- .
          115  +form of [\fBtest\fR] can be distinguished from the first because
          116  +all \fIoption\fRs begin with ``-''.
   119    117   .TP
   120    118   \fBloadTestedCommands\fR
   121    119   Evaluates in the caller's context the script specified by 
   122         -\fBconfigure \-load\fR or \fBconfigure \-loadfile\fR.
          120  +[\fBconfigure -load\fR] or [\fBconfigure -loadfile\fR].
   123    121   Returns the result of that script evaluation, including any error
   124    122   raised by the script.  Use this command and the related
   125    123   configuration options to provide the commands to be tested to
   126    124   the interpreter running the test suite.
   127    125   .TP
   128    126   \fBmakeFile\fR \fIcontents name ?directory?\fR
   129    127   Creates a file named \fIname\fR relative to
   130    128   directory \fIdirectory\fR and write \fIcontents\fR
   131         -to that file using the encoding \fBencoding system\fR.
          129  +to that file using the encoding [\fBencoding system\fR].
   132    130   If \fIcontents\fR does not end with a newline, a newline
   133    131   will be appended so that the file named \fIname\fR
   134    132   does end with a newline.  Because the system encoding is used,
   135    133   this command is only suitable for making text files.
   136    134   The file will be removed by the next evaluation
   137         -of \fBcleanupTests\fR, unless it is removed by
   138         -\fBremoveFile\fR first.  The default value of
   139         -\fIdirectory\fR is the directory \fBconfigure -tmpdir\fR.
          135  +of [\fBcleanupTests\fR], unless it is removed by
          136  +[\fBremoveFile\fR] first.  The default value of
          137  +\fIdirectory\fR is the directory [\fBconfigure -tmpdir\fR].
   140    138   Returns the full path of the file created.  Use this command
   141    139   to create any text file required by a test with contents as needed.
   142    140   .TP
   143    141   \fBremoveFile\fR \fIname ?directory?\fR
   144    142   Forces the file referenced by \fIname\fR to be removed.  This file name
   145    143   should be relative to \fIdirectory\fR.   The default value of
   146         -\fIdirectory\fR is the directory \fBconfigure -tmpdir\fR.
          144  +\fIdirectory\fR is the directory [\fBconfigure -tmpdir\fR].
   147    145   Returns an empty string.  Use this command to delete files
   148         -created by \fBmakeFile\fR.
          146  +created by [\fBmakeFile\fR].  
   149    147   .TP
   150    148   \fBmakeDirectory\fR \fIname ?directory?\fR
   151    149   Creates a directory named \fIname\fR relative to directory \fIdirectory\fR.
   152         -The directory will be removed by the next evaluation of \fBcleanupTests\fR,
   153         -unless it is removed by \fBremoveDirectory\fR first.
          150  +The directory will be removed by the next evaluation of [\fBcleanupTests\fR],
          151  +unless it is removed by [\fBremoveDirectory\fR] first.
   154    152   The default value of \fIdirectory\fR is the directory
   155         -\fBconfigure -tmpdir\fR.
          153  +[\fBconfigure -tmpdir\fR].
   156    154   Returns the full path of the directory created.  Use this command
   157    155   to create any directories that are required to exist by a test.
   158    156   .TP
   159    157   \fBremoveDirectory\fR \fIname ?directory?\fR
   160    158   Forces the directory referenced by \fIname\fR to be removed. This
   161    159   directory should be relative to \fIdirectory\fR.
   162    160   The default value of \fIdirectory\fR is the directory
   163         -\fBconfigure -tmpdir\fR.
          161  +[\fBconfigure -tmpdir\fR].
   164    162   Returns an empty string.  Use this command to delete any directories
   165         -created by \fBmakeDirectory\fR.
          163  +created by [\fBmakeDirectory\fR].  
   166    164   .TP
   167    165   \fBviewFile\fR \fIfile ?directory?\fR
   168    166   Returns the contents of \fIfile\fR, except for any
   169         -final newline, just as \fBread -nonewline\fR would return.
          167  +final newline, just as [\fBread -nonewline\fR] would return.
   170    168   This file name should be relative to \fIdirectory\fR.   
   171    169   The default value of \fIdirectory\fR is the directory
   172         -\fBconfigure -tmpdir\fR.  Use this command
          170  +[\fBconfigure -tmpdir\fR].  Use this command
   173    171   as a convenient way to turn the contents of a file generated
   174    172   by a test into the result of that test for matching against
   175    173   an expected result.  The contents of the file are read using
   176    174   the system encoding, so its usefulness is limited to text
   177    175   files.
   178    176   .TP
   179    177   \fBcleanupTests\fR
   180    178   Intended to clean up and summarize after several tests have been
   181    179   run.  Typically called once per test file, at the end of the file
   182    180   after all tests have been completed.  For best effectiveness, be
   183         -sure that the \fBcleanupTests\fR is evaluated even if an error
          181  +sure that the [\fBcleanupTests\fR] is evaluated even if an error
   184    182   occurs earlier in the test file evaluation.  
   185    183   .sp
   186    184   Prints statistics about the tests run and removes files that were
   187         -created by \fBmakeDirectory\fR and \fBmakeFile\fR since the
   188         -last \fBcleanupTests\fR.  Names of files and directories 
   189         -in the directory \fBconfigure -tmpdir\fR created since
   190         -the last \fBcleanupTests\fR, but not created by
   191         -\fBmakeFile\fR or \fBmakeDirectory\fR are printed
   192         -to \fBoutputChannel\fR.  This command also restores the original
          185  +created by [\fBmakeDirectory\fR] and [\fBmakeFile\fR] since the
          186  +last [\fBcleanupTests\fR].  Names of files and directories 
          187  +in the directory [\fBconfigure -tmpdir\fR] created since
          188  +the last [\fBcleanupTests\fR], but not created by
          189  +[\fBmakeFile\fR] or [\fBmakeDirectory\fR] are printed
          190  +to [\fBoutputChannel\fR].  This command also restores the original
   193    191   shell environment, as described by the ::env
   194    192   array. Returns an empty string.
   195    193   .TP
   196    194   \fBrunAllTests\fR
   197    195   This is a master command meant to run an entire suite of tests,
   198    196   spanning multiple files and/or directories, as governed by
   199    197   the configurable options of \fBtcltest\fR.  See \fBRUNNING ALL TESTS\fR
   200    198   below for a complete description of the many variations possible
   201         -with \fBrunAllTests\fR.
          199  +with [\fBrunAllTests\fR].
   202    200   .SH "CONFIGURATION COMMANDS"
   203    201   .TP
   204    202   \fBconfigure\fR
   205    203   Returns the list of configurable options supported by \fBtcltest\fR.
   206    204   See \fBCONFIGURABLE OPTIONS\fR below for the full list of options,
   207    205   their valid values, and their effect on \fBtcltest\fR operations.
   208    206   .TP
................................................................................
   212    210   .TP
   213    211   \fBconfigure \fIoption value ?option value ...?\fR
   214    212   Sets the value of each configurable option \fIoption\fR to the
   215    213   corresponding value \fIvalue\fR, in order.  Raises an error if
   216    214   an \fIoption\fR is not a supported configurable option, or if
   217    215   \fIvalue\fR is not a valid value for the corresponding \fIoption\fR,
   218    216   or if a \fIvalue\fR is not provided.  When an error is raised, the
   219         -operation of \fBconfigure\fR is halted, and subsequent \fIoption value\fR
          217  +operation of [\fBconfigure\fR] is halted, and subsequent \fIoption value\fR
   220    218   arguments are not processed.
   221    219   .sp
   222    220   If the environment variable \fB::env(TCLTEST_OPTIONS)\fR exists when
   223         -the \fBtcltest\fR package is loaded (by
   224         -.QW "\fBpackage require tcltest\fR" )
   225         -then its value is taken as a list of arguments to pass to \fBconfigure\fR.
          221  +the \fBtcltest\fR package is loaded (by [\fBpackage require tcltest\fR])
          222  +then its value is taken as a list of arguments to pass to [\fBconfigure\fR].
   226    223   This allows the default values of the configuration options to be
   227    224   set by the environment.
   228    225   .TP
   229    226   \fBcustomMatch \fImode script\fR
   230         -Registers \fImode\fR as a new legal value of the \fB\-match\fR option
   231         -to \fBtest\fR.  When the \fB\-match \fImode\fR option is
   232         -passed to \fBtest\fR, the script \fIscript\fR will be evaluated
          227  +Registers \fImode\fR as a new legal value of the \fB-match\fR option
          228  +to [\fBtest\fR].  When the \fB-match \fImode\fR option is
          229  +passed to [\fBtest\fR], the script \fIscript\fR will be evaluated
   233    230   to compare the actual result of evaluating the body of the test
   234    231   to the expected result.
   235    232   To perform the match, the \fIscript\fR is completed with two additional
   236    233   words, the expected result, and the actual result, and the completed script
   237    234   is evaluated in the global namespace.
   238    235   The completed script is expected to return a boolean value indicating
   239    236   whether or not the results match.  The built-in matching modes of
   240         -\fBtest\fR are \fBexact\fR, \fBglob\fR, and \fBregexp\fR.
          237  +[\fBtest\fR] are \fBexact\fR, \fBglob\fR, and \fBregexp\fR.
   241    238   .TP
   242    239   \fBtestConstraint \fIconstraint ?boolean?\fR
   243    240   Sets or returns the boolean value associated with the named \fIconstraint\fR.
   244    241   See \fBTEST CONSTRAINTS\fR below for more information.
   245    242   .TP
   246    243   \fBinterpreter\fR \fI?executableName?\fR
   247         -Sets or returns the name of the executable to be \fBexec\fRed by
   248         -\fBrunAllTests\fR to run each test file when
   249         -\fBconfigure -singleproc\fR is false.
   250         -The default value for \fBinterpreter\fR is the name of the
   251         -currently running program as returned by \fBinfo nameofexecutable\fR.
          244  +Sets or returns the name of the executable to be [\fBexec\fR]ed by
          245  +[\fBrunAllTests\fR] to run each test file when
          246  +[\fBconfigure -singleproc\fR] is false.
          247  +The default value for [\fBinterpreter\fR] is the name of the
          248  +currently running program as returned by [\fBinfo nameofexecutable\fR].
   252    249   .TP
   253    250   \fBoutputChannel\fR \fI?channelID?\fR
   254    251   Sets or returns the output channel ID.  This defaults to stdout.
   255    252   Any test that prints test related output should send
   256         -that output to \fBoutputChannel\fR rather than letting
          253  +that output to [\fBoutputChannel\fR] rather than letting
   257    254   that output default to stdout.
   258    255   .TP
   259    256   \fBerrorChannel\fR \fI?channelID?\fR
   260    257   Sets or returns the error channel ID.  This defaults to stderr.
   261    258   Any test that prints error messages should send
   262         -that output to \fBerrorChannel\fR rather than printing
          259  +that output to [\fBerrorChannel\fR] rather than printing
   263    260   directly to stderr.
   264    261   .SH "SHORTCUT COMMANDS"
   265    262   .TP
   266    263   \fBdebug \fI?level?\fR
   267         -Same as \fBconfigure -debug \fI?level?\fR.
          264  +Same as [\fBconfigure -debug \fI?level?\fR].
   268    265   .TP
   269    266   \fBerrorFile \fI?filename?\fR
   270         -Same as \fBconfigure -errfile \fI?filename?\fR.
          267  +Same as [\fBconfigure -errfile \fI?filename?\fR].
   271    268   .TP
   272    269   \fBlimitConstraints \fI?boolean?\fR
   273         -Same as \fBconfigure -limitconstraints \fI?boolean?\fR.
          270  +Same as [\fBconfigure -limitconstraints \fI?boolean?\fR].
   274    271   .TP
   275    272   \fBloadFile \fI?filename?\fR
   276         -Same as \fBconfigure -loadfile \fI?filename?\fR.
          273  +Same as [\fBconfigure -loadfile \fI?filename?\fR].
   277    274   .TP
   278    275   \fBloadScript \fI?script?\fR
   279         -Same as \fBconfigure -load \fI?script?\fR.
          276  +Same as [\fBconfigure -load \fI?script?\fR].
   280    277   .TP
   281    278   \fBmatch \fI?patternList?\fR
   282         -Same as \fBconfigure -match \fI?patternList?\fR.
          279  +Same as [\fBconfigure -match \fI?patternList?\fR].
   283    280   .TP
   284    281   \fBmatchDirectories \fI?patternList?\fR
   285         -Same as \fBconfigure -relateddir \fI?patternList?\fR.
          282  +Same as [\fBconfigure -relateddir \fI?patternList?\fR].
   286    283   .TP
   287    284   \fBmatchFiles \fI?patternList?\fR
   288         -Same as \fBconfigure -file \fI?patternList?\fR.
          285  +Same as [\fBconfigure -file \fI?patternList?\fR].
   289    286   .TP
   290    287   \fBoutputFile \fI?filename?\fR
   291         -Same as \fBconfigure -outfile \fI?filename?\fR.
          288  +Same as [\fBconfigure -outfile \fI?filename?\fR].
   292    289   .TP
   293    290   \fBpreserveCore \fI?level?\fR
   294         -Same as \fBconfigure -preservecore \fI?level?\fR.
          291  +Same as [\fBconfigure -preservecore \fI?level?\fR].
   295    292   .TP
   296    293   \fBsingleProcess \fI?boolean?\fR
   297         -Same as \fBconfigure -singleproc \fI?boolean?\fR.
          294  +Same as [\fBconfigure -singleproc \fI?boolean?\fR].
   298    295   .TP
   299    296   \fBskip \fI?patternList?\fR
   300         -Same as \fBconfigure -skip \fI?patternList?\fR.
          297  +Same as [\fBconfigure -skip \fI?patternList?\fR].
   301    298   .TP
   302    299   \fBskipDirectories \fI?patternList?\fR
   303         -Same as \fBconfigure -asidefromdir \fI?patternList?\fR.
          300  +Same as [\fBconfigure -asidefromdir \fI?patternList?\fR].
   304    301   .TP
   305    302   \fBskipFiles \fI?patternList?\fR
   306         -Same as \fBconfigure -notfile \fI?patternList?\fR.
          303  +Same as [\fBconfigure -notfile \fI?patternList?\fR].
   307    304   .TP
   308    305   \fBtemporaryDirectory \fI?directory?\fR
   309         -Same as \fBconfigure -tmpdir \fI?directory?\fR.
          306  +Same as [\fBconfigure -tmpdir \fI?directory?\fR].
   310    307   .TP
   311    308   \fBtestsDirectory \fI?directory?\fR
   312         -Same as \fBconfigure -testdir \fI?directory?\fR.
          309  +Same as [\fBconfigure -testdir \fI?directory?\fR].
   313    310   .TP
   314    311   \fBverbose \fI?level?\fR
   315         -Same as \fBconfigure -verbose \fI?level?\fR.
          312  +Same as [\fBconfigure -verbose \fI?level?\fR].
   316    313   .SH "OTHER COMMANDS"
   317    314   .PP
   318    315   The remaining commands provided by \fBtcltest\fR have better
   319    316   alternatives provided by \fBtcltest\fR or \fBTcl\fR itself.  They
   320    317   are retained to support existing test suites, but should be avoided
   321    318   in new code.
   322    319   .TP
   323    320   \fBtest\fR \fIname description optionList\fR
   324         -This form of \fBtest\fR was provided to enable passing many
   325         -options spanning several lines to \fBtest\fR as a single
          321  +This form of [\fBtest\fR] was provided to enable passing many
          322  +options spanning several lines to [\fBtest\fR] as a single
   326    323   argument quoted by braces, rather than needing to backslash quote
   327         -the newlines between arguments to \fBtest\fR.  The \fIoptionList\fR
          324  +the newlines between arguments to [\fBtest\fR].  The \fIoptionList\fR
   328    325   argument is expected to be a list with an even number of elements
   329    326   representing \fIoption\fR and \fIvalue\fR arguments to pass
   330         -to \fBtest\fR.  However, these values are not passed directly, as
   331         -in the alternate forms of \fBswitch\fR.  Instead, this form makes
          327  +to [\fBtest\fR].  However, these values are not passed directly, as
          328  +in the alternate forms of [\fBswitch\fR].  Instead, this form makes
   332    329   an unfortunate attempt to overthrow Tcl's substitution rules by
   333    330   performing substitutions on some of the list elements as an attempt to
   334         -implement a
   335         -.QW "do what I mean"
   336         -interpretation of a brace-enclosed
   337         -.QW block .
   338         -The result is nearly impossible to document clearly, and
          331  +implement a ``do what I mean'' interpretation of a brace-enclosed
          332  +``block''.  The result is nearly impossible to document clearly, and
   339    333   for that reason this form is not recommended.  See the examples in
   340    334   \fBCREATING TEST SUITES WITH TCLTEST\fR below to see that this
   341    335   form is really not necessary to avoid backslash-quoted newlines.
   342    336   If you insist on using this form, examine
   343    337   the source code of \fBtcltest\fR if you want to know the substitution
   344    338   details, or just enclose the third through last argument
   345         -to \fBtest\fR in braces and hope for the best.
          339  +to [\fBtest\fR] in braces and hope for the best.
   346    340   .TP
   347    341   \fBworkingDirectory\fR \fI?directoryName?\fR
   348    342   Sets or returns the current working directory when the test suite is
   349    343   running.  The default value for workingDirectory is the directory in
   350         -which the test suite was launched.  The Tcl commands \fBcd\fR and
   351         -\fBpwd\fR are sufficient replacements.
          344  +which the test suite was launched.  The Tcl commands [\fBcd\fR] and
          345  +[\fBpwd\fR] are sufficient replacements.
   352    346   .TP
   353    347   \fBnormalizeMsg\fR \fImsg\fR
   354         -Returns the result of removing the
   355         -.QW extra
   356         -newlines from \fImsg\fR, where
   357         -.QW extra
   358         -is rather imprecise.  Tcl offers plenty of string
          348  +Returns the result of removing the ``extra'' newlines from \fImsg\fR,
          349  +where ``extra'' is rather imprecise.  Tcl offers plenty of string
   359    350   processing commands to modify strings as you wish, and
   360         -\fBcustomMatch\fR allows flexible matching of actual and expected
          351  +[\fBcustomMatch\fR] allows flexible matching of actual and expected
   361    352   results.
   362    353   .TP
   363    354   \fBnormalizePath\fR \fIpathVar\fR
   364    355   Resolves symlinks in a path, thus creating a path without internal
   365    356   redirection.  It is assumed that \fIpathVar\fR is absolute.
   366         -\fIpathVar\fR is modified in place.  The Tcl command \fBfile normalize\fR
          357  +\fIpathVar\fR is modified in place.  The Tcl command [\fBfile normalize\fR]
   367    358   is a sufficient replacement.
   368    359   .TP
   369    360   \fBbytestring\fR \fIstring\fR
   370    361   Construct a string that consists of the requested sequence of bytes,
   371    362   as opposed to a string of properly formed UTF-8 characters using the
   372    363   value supplied in \fIstring\fR.  This allows the tester to create
   373    364   denormalized or improperly formed strings to pass to C procedures that
   374    365   are supposed to accept strings with embedded NULL types and confirm
   375    366   that a string result has a certain pattern of bytes.  This is
   376         -exactly equivalent to the Tcl command \fBencoding convertfrom identity\fR.
          367  +exactly equivalent to the Tcl command [\fBencoding convertfrom identity\fR].
   377    368   .SH TESTS
   378    369   .PP
   379         -The \fBtest\fR command is the heart of the \fBtcltest\fR package.
          370  +The [\fBtest\fR] command is the heart of the \fBtcltest\fR package.
   380    371   Its essential function is to evaluate a Tcl script and compare
   381         -the result with an expected result.  The options of \fBtest\fR
          372  +the result with an expected result.  The options of [\fBtest\fR]
   382    373   define the test script, the environment in which to evaluate it,
   383    374   the expected result, and how the compare the actual result to
   384    375   the expected result.  Some configuration options of \fBtcltest\fR
   385         -also influence how \fBtest\fR operates.
          376  +also influence how [\fBtest\fR] operates.
   386    377   .PP
   387         -The valid options for \fBtest\fR are summarized:
          378  +The valid options for [\fBtest\fR] are summarized:
   388    379   .PP
   389    380   .CS
   390    381   \fBtest\fR \fIname\fR \fIdescription\fR
   391    382           ?-constraints \fIkeywordList|expression\fR?
   392    383           ?-setup \fIsetupScript\fR?
   393    384           ?-body \fItestScript\fR?
   394    385           ?-cleanup \fIcleanupScript\fR?
................................................................................
   399    390           ?-match \fImode\fR?
   400    391   .CE
   401    392   .PP
   402    393   The \fIname\fR may be any string.  It is conventional to choose
   403    394   a \fIname\fR according to the pattern:
   404    395   .PP
   405    396   .CS
   406         -\fItarget\fR\-\fImajorNum\fR.\fIminorNum\fR
          397  +\fItarget\fR-\fImajorNum\fR.\fIminorNum\fR
   407    398   .CE
   408    399   .PP
   409    400   For white-box (regression) tests, the target should be the name of the
   410    401   C function or Tcl procedure being tested.  For black-box tests, the
   411    402   target should be the name of the feature being tested.  Some conventions
   412    403   call for the names of black-box tests to have the suffix \fB_bb\fR.
   413    404   Related tests should share a major number.  As a test suite evolves,
   414    405   it is best to have the same test name continue to correspond to the
   415         -same test, so that it remains meaningful to say things like
   416         -.QW "Test foo-1.3 passed in all releases up to 3.4, but began failing in release 3.5."
          406  +same test, so that it remains meaningful to say things like ``Test
          407  +foo-1.3 passed in all releases up to 3.4, but began failing in
          408  +release 3.5.''
   417    409   .PP
   418         -During evaluation of \fBtest\fR, the \fIname\fR will be compared
          410  +During evaluation of [\fBtest\fR], the \fIname\fR will be compared
   419    411   to the lists of string matching patterns returned by
   420         -\fBconfigure -match\fR, and \fBconfigure -skip\fR.  The test
          412  +[\fBconfigure -match\fR], and [\fBconfigure -skip\fR].  The test
   421    413   will be run only if \fIname\fR matches any of the patterns from
   422         -\fBconfigure -match\fR and matches none of the patterns
   423         -from \fBconfigure -skip\fR.
          414  +[\fBconfigure -match\fR] and matches none of the patterns
          415  +from [\fBconfigure -skip\fR].
   424    416   .PP
   425    417   The \fIdescription\fR should be a short textual description of the
   426    418   test.  The \fIdescription\fR is included in output produced by the
   427    419   test, typically test failure messages.  Good \fIdescription\fR values
   428    420   should briefly explain the purpose of the test to users of a test suite.
   429    421   The name of a Tcl or C function being tested should be included in the
   430    422   description for regression tests.  If the test case exists to reproduce
   431    423   a bug, include the bug ID in the description. 
   432    424   .PP
   433    425   Valid attributes and associated values are:
   434    426   .TP
   435         -\fB\-constraints \fIkeywordList|expression\fR
   436         -The optional \fB\-constraints\fR attribute can be list of one or more
   437         -keywords or an expression.  If the \fB\-constraints\fR value is a list of
          427  +\fB-constraints \fIkeywordList|expression\fR
          428  +The optional \fB-constraints\fR attribute can be list of one or more
          429  +keywords or an expression.  If the \fB-constraints\fR value is a list of
   438    430   keywords, each of these keywords should be the name of a constraint
   439         -defined by a call to \fBtestConstraint\fR.  If any of the listed
          431  +defined by a call to [\fBtestConstraint\fR].  If any of the listed
   440    432   constraints is false or does not exist, the test is skipped.  If the
   441         -\fB\-constraints\fR value is an expression, that expression
          433  +\fB-constraints\fR value is an expression, that expression
   442    434   is evaluated. If the expression evaluates to true, then the test is run.
   443         -Note that the expression form of \fB\-constraints\fR may interfere with the
   444         -operation of \fBconfigure -constraints\fR and
   445         -\fBconfigure -limitconstraints\fR, and is not recommended.
          435  +Note that the expression form of \fB-constraints\fR may interfere with the
          436  +operation of [\fBconfigure -constraints\fR] and
          437  +[\fBconfigure -limitconstraints\fR], and is not recommended.
   446    438   Appropriate constraints should be added to any tests that should
   447    439   not always be run.  That is, conditional evaluation of a test
   448         -should be accomplished by the \fB\-constraints\fR option, not by
   449         -conditional evaluation of \fBtest\fR.  In that way, the same
          440  +should be accomplished by the \fB-constraints\fR option, not by
          441  +conditional evaluation of [\fBtest\fR].  In that way, the same
   450    442   number of tests are always reported by the test suite, though
   451    443   the number skipped may change based on the testing environment.
   452    444   The default value is an empty list.  
   453    445   See \fBTEST CONSTRAINTS\fR below for a list of built-in constraints 
   454    446   and information on how to add your own constraints.
   455    447   .TP
   456         -\fB\-setup \fIscript\fR
   457         -The optional \fB\-setup\fR attribute indicates a \fIscript\fR that will be run
   458         -before the script indicated by the \fB\-body\fR attribute.  If evaluation
          448  +\fB-setup \fIscript\fR
          449  +The optional \fB-setup\fR attribute indicates a \fIscript\fR that will be run
          450  +before the script indicated by the \fB-body\fR attribute.  If evaluation
   459    451   of \fIscript\fR raises an error, the test will fail.  The default value
   460    452   is an empty script.
   461    453   .TP
   462         -\fB\-body \fIscript\fR
   463         -The \fB\-body\fR attribute indicates the \fIscript\fR to run to carry out the 
          454  +\fB-body \fIscript\fR
          455  +The \fB-body\fR attribute indicates the \fIscript\fR to run to carry out the 
   464    456   test.  It must return a result that can be checked for correctness.
   465    457   If evaluation of \fIscript\fR raises an error, the test will fail.
   466    458   The default value is an empty script.
   467    459   .TP
   468         -\fB\-cleanup \fIscript\fR
   469         -The optional \fB\-cleanup\fR attribute indicates a \fIscript\fR that will be
   470         -run after the script indicated by the \fB\-body\fR attribute.
          460  +\fB-cleanup \fIscript\fR
          461  +The optional \fB-cleanup\fR attribute indicates a \fIscript\fR that will be
          462  +run after the script indicated by the \fB-body\fR attribute.
   471    463   If evaluation of \fIscript\fR raises an error, the test will fail.
   472    464   The default value is an empty script.
   473    465   .TP
   474         -\fB\-match \fImode\fR
   475         -The \fB\-match\fR attribute determines how expected answers supplied by
   476         -\fB\-result\fR, \fB\-output\fR, and \fB\-errorOutput\fR are compared.  Valid
          466  +\fB-match \fImode\fR
          467  +The \fB-match\fR attribute determines how expected answers supplied by
          468  +\fB-result\fR, \fB-output\fR, and \fB-errorOutput\fR are compared.  Valid
   477    469   values for \fImode\fR are \fBregexp\fR, \fBglob\fR, \fBexact\fR, and
   478         -any value registered by a prior call to \fBcustomMatch\fR.  The default
          470  +any value registered by a prior call to [\fBcustomMatch\fR].  The default
   479    471   value is \fBexact\fR.
   480    472   .TP
   481         -\fB\-result \fIexpectedValue\fR
   482         -The \fB\-result\fR attribute supplies the \fIexpectedValue\fR against which
          473  +\fB-result \fIexpectedValue\fR
          474  +The \fB-result\fR attribute supplies the \fIexpectedValue\fR against which
   483    475   the return value from script will be compared. The default value is
   484    476   an empty string.
   485    477   .TP
   486         -\fB\-output \fIexpectedValue\fR
   487         -The \fB\-output\fR attribute supplies the \fIexpectedValue\fR against which
   488         -any output sent to \fBstdout\fR or \fBoutputChannel\fR during evaluation
          478  +\fB-output \fIexpectedValue\fR
          479  +The \fB-output\fR attribute supplies the \fIexpectedValue\fR against which
          480  +any output sent to \fBstdout\fR or [\fBoutputChannel\fR] during evaluation
   489    481   of the script(s) will be compared.  Note that only output printed using
   490         -\fB::puts\fR is used for comparison.  If \fB\-output\fR is not specified,
   491         -output sent to \fBstdout\fR and \fBoutputChannel\fR is not processed for
          482  +[\fB::puts\fR] is used for comparison.  If \fB-output\fR is not specified,
          483  +output sent to \fBstdout\fR and [\fBoutputChannel\fR] is not processed for
   492    484   comparison.
   493    485   .TP
   494         -\fB\-errorOutput \fIexpectedValue\fR
   495         -The \fB\-errorOutput\fR attribute supplies the \fIexpectedValue\fR against
   496         -which any output sent to \fBstderr\fR or \fBerrorChannel\fR during 
          486  +\fB-errorOutput \fIexpectedValue\fR
          487  +The \fB-errorOutput\fR attribute supplies the \fIexpectedValue\fR against
          488  +which any output sent to \fBstderr\fR or [\fBerrorChannel\fR] during 
   497    489   evaluation of the script(s) will be compared. Note that only output
   498         -printed using \fB::puts\fR is used for comparison.  If \fB\-errorOutput\fR
   499         -is not specified, output sent to \fBstderr\fR and \fBerrorChannel\fR is
          490  +printed using [\fB::puts\fR] is used for comparison.  If \fB-errorOutput\fR
          491  +is not specified, output sent to \fBstderr\fR and [\fBerrorChannel\fR] is
   500    492   not processed for comparison.
   501    493   .TP
   502         -\fB\-returnCodes \fIexpectedCodeList\fR
   503         -The optional \fB\-returnCodes\fR attribute supplies \fIexpectedCodeList\fR,
          494  +\fB-returnCodes \fIexpectedCodeList\fR
          495  +The optional \fB-returnCodes\fR attribute supplies \fIexpectedCodeList\fR,
   504    496   a list of return codes that may be accepted from evaluation of the
   505         -\fB\-body\fR script.  If evaluation of the \fB\-body\fR script returns
          497  +\fB-body\fR script.  If evaluation of the \fB-body\fR script returns
   506    498   a code not in the \fIexpectedCodeList\fR, the test fails.  All
   507         -return codes known to \fBreturn\fR, in both numeric and symbolic
          499  +return codes known to [\fBreturn\fR], in both numeric and symbolic
   508    500   form, including extended return codes, are acceptable elements in
   509    501   the \fIexpectedCodeList\fR.  Default value is \fB{ok return}\fR.
   510    502   .PP
   511         -To pass, a test must successfully evaluate its \fB\-setup\fR, \fB\-body\fR,
   512         -and \fB\-cleanup\fR scripts.  The return code of the \fB\-body\fR script and
          503  +To pass, a test must successfully evaluate its \fB-setup\fR, \fB-body\fR,
          504  +and \fB-cleanup\fR scripts.  The return code of the \fB-body\fR script and
   513    505   its result must match expected values, and if specified, output and error
   514         -data from the test must match expected \fB\-output\fR and \fB\-errorOutput\fR
          506  +data from the test must match expected \fB-output\fR and \fB-errorOutput\fR
   515    507   values.  If any of these conditions are not met, then the test fails.
   516    508   Note that all scripts are evaluated in the context of the caller
   517         -of \fBtest\fR.
          509  +of [\fBtest\fR].
   518    510   .PP
   519         -As long as \fBtest\fR is called with valid syntax and legal
          511  +As long as [\fBtest\fR] is called with valid syntax and legal
   520    512   values for all attributes, it will not raise an error.  Test
   521         -failures are instead reported as output written to \fBoutputChannel\fR.
          513  +failures are instead reported as output written to [\fBoutputChannel\fR].
   522    514   In default operation, a successful test produces no output.  The output
   523         -messages produced by \fBtest\fR are controlled by the
   524         -\fBconfigure \-verbose\fR option as described in \fBCONFIGURABLE OPTIONS\fR
          515  +messages produced by [\fBtest\fR] are controlled by the
          516  +[\fBconfigure -verbose\fR] option as described in \fBCONFIGURABLE OPTIONS\fR
   525    517   below.  Any output produced by the test scripts themselves should be
   526         -produced using \fB::puts\fR to \fBoutputChannel\fR or
   527         -\fBerrorChannel\fR, so that users of the test suite may
   528         -easily capture output with the \fBconfigure \-outfile\fR and
   529         -\fBconfigure \-errfile\fR options, and so that the \fB\-output\fR
   530         -and \fB\-errorOutput\fR attributes work properly.
          518  +produced using [\fB::puts\fR] to [\fBoutputChannel\fR] or
          519  +[\fBerrorChannel\fR], so that users of the test suite may
          520  +easily capture output with the [\fBconfigure -outfile\fR] and
          521  +[\fBconfigure -errfile\fR] options, and so that the \fB-output\fR
          522  +and \fB-errorOutput\fR attributes work properly.
   531    523   .SH "TEST CONSTRAINTS"
   532    524   .PP
   533    525   Constraints are used to determine whether or not a test should be skipped.
   534    526   Each constraint has a name, which may be any string, and a boolean
   535         -value.  Each \fBtest\fR has a \fB\-constraints\fR value which is a
          527  +value.  Each [\fBtest\fR] has a \fB-constraints\fR value which is a
   536    528   list of constraint names.  There are two modes of constraint control.
   537    529   Most frequently, the default mode is used, indicated by a setting
   538         -of \fBconfigure \-limitconstraints\fR to false.  The test will run
          530  +of [\fBconfigure -limitconstraints\fR] to false.  The test will run
   539    531   only if all constraints in the list are true-valued.  Thus,
   540         -the \fB\-constraints\fR option of \fBtest\fR is a convenient, symbolic
          532  +the \fB-constraints\fR option of [\fBtest\fR] is a convenient, symbolic
   541    533   way to define any conditions required for the test to be possible or
   542         -meaningful.  For example, a \fBtest\fR with \fB\-constraints unix\fR
          534  +meaningful.  For example, a [\fBtest\fR] with \fB-constraints unix\fR
   543    535   will only be run if the constraint \fBunix\fR is true, which indicates
   544    536   the test suite is being run on a Unix platform.
   545    537   .PP
   546         -Each \fBtest\fR should include whatever \fB\-constraints\fR are
          538  +Each [\fBtest\fR] should include whatever \fB-constraints\fR are
   547    539   required to constrain it to run only where appropriate.  Several
   548    540   constraints are pre-defined in the \fBtcltest\fR package, listed
   549    541   below.  The registration of user-defined constraints is performed
   550         -by the \fBtestConstraint\fR command.  User-defined constraints
          542  +by the [\fBtestConstraint\fR] command.  User-defined constraints
   551    543   may appear within a test file, or within the script specified
   552         -by the \fBconfigure \-load\fR or \fBconfigure \-loadfile\fR
          544  +by the [\fBconfigure -load\fR] or [\fBconfigure -loadfile\fR]
   553    545   options.
   554    546   .PP
   555    547   The following is a list of constraints pre-defined by the
   556    548   \fBtcltest\fR package itself:
   557    549   .TP
   558    550   \fIsingleTestInterp\fR
   559    551   test can only be run if all test files are sourced into a single interpreter
................................................................................
   651    643   \fIroot\fR
   652    644   test can only run if Unix user is root
   653    645   .TP
   654    646   \fInotRoot\fR
   655    647   test can only run if Unix user is not root
   656    648   .TP
   657    649   \fIeformat\fR
   658         -test can only run if app has a working version of sprintf with respect to the
   659         -.QW "e"
   660         -format of floating-point numbers.
          650  +test can only run if app has a working version of sprintf with respect
          651  +to the "e" format of floating-point numbers.
   661    652   .TP
   662    653   \fIstdio\fR
   663         -test can only be run if \fBinterpreter\fR can be \fBopen\fRed
          654  +test can only be run if [\fBinterpreter\fR] can be [\fBopen\fR]ed
   664    655   as a pipe.
   665    656   .PP
   666    657   The alternative mode of constraint control is enabled by setting
   667         -\fBconfigure \-limitconstraints\fR to true.  With that configuration
          658  +[\fBconfigure -limitconstraints\fR] to true.  With that configuration
   668    659   setting, all existing constraints other than those in the constraint
   669         -list returned by \fBconfigure \-constraints\fR are set to false.
   670         -When the value of \fBconfigure \-constraints\fR
          660  +list returned by [\fBconfigure -constraints\fR] are set to false.
          661  +When the value of [\fBconfigure -constraints\fR]
   671    662   is set, all those constraints are set to true.  The effect is that
   672         -when both options \fBconfigure \-constraints\fR and
   673         -\fBconfigure \-limitconstraints\fR are in use, only those tests including
   674         -only constraints from the \fBconfigure \-constraints\fR list
          663  +when both options [\fBconfigure -constraints\fR] and
          664  +[\fBconfigure -limitconstraints\fR] are in use, only those tests including
          665  +only constraints from the [\fBconfigure -constraints\fR] list
   675    666   are run; all others are skipped.  For example, one might set
   676    667   up a configuration with
   677    668   .PP
   678    669   .CS
   679    670   \fBconfigure\fR -constraints knownBug \e
   680    671             -limitconstraints true \e
   681    672             -verbose pass
   682    673   .CE
   683    674   .PP
   684    675   to run exactly those tests that exercise known bugs, and discover
   685    676   whether any of them pass, indicating the bug had been fixed.  
   686    677   .SH "RUNNING ALL TESTS"
   687    678   .PP
   688         -The single command \fBrunAllTests\fR is evaluated to run an entire
          679  +The single command [\fBrunAllTests\fR] is evaluated to run an entire
   689    680   test suite, spanning many files and directories.  The configuration
   690    681   options of \fBtcltest\fR control the precise operations.  The
   691         -\fBrunAllTests\fR command begins by printing a summary of its
   692         -configuration to \fBoutputChannel\fR.
          682  +[\fBrunAllTests\fR] command begins by printing a summary of its
          683  +configuration to [\fBoutputChannel\fR].
   693    684   .PP
   694    685   Test files to be evaluated are sought in the directory
   695         -\fBconfigure \-testdir\fR.  The list of files in that directory
   696         -that match any of the patterns in \fBconfigure \-file\fR and
   697         -match none of the patterns in \fBconfigure \-notfile\fR is generated
          686  +[\fBconfigure -testdir\fR].  The list of files in that directory
          687  +that match any of the patterns in [\fBconfigure -file\fR] and
          688  +match none of the patterns in [\fBconfigure -notfile\fR] is generated
   698    689   and sorted.  Then each file will be evaluated in turn.  If
   699         -\fBconfigure \-singleproc\fR is true, then each file will
   700         -be \fBsource\fRd in the caller's context.  If it is false,
   701         -then a copy of \fBinterpreter\fR will be \fBexec\fRd to
          690  +[\fBconfigure -singleproc\fR] is true, then each file will
          691  +be [\fBsource\fR]d in the caller's context.  If it is false,
          692  +then a copy of [\fBinterpreter\fR] will be [\fBexec\fR]d to
   702    693   evaluate each file.  The multi-process operation is useful
   703    694   when testing can cause errors so severe that a process 
   704    695   terminates.  Although such an error may terminate a child
   705    696   process evaluating one file, the master process can continue
   706    697   with the rest of the test suite.  In multi-process operation,
   707    698   the configuration of \fBtcltest\fR in the master process is
   708    699   passed to the child processes as command line arguments,
   709         -with the exception of \fBconfigure \-outfile\fR.  The
   710         -\fBrunAllTests\fR command in the
          700  +with the exception of [\fBconfigure -outfile\fR].  The
          701  +[\fBrunAllTests\fR] command in the
   711    702   master process collects all output from the child processes
   712    703   and collates their results into one master report.  Any
   713    704   reports of individual test failures, or messages requested
   714         -by a \fBconfigure \-verbose\fR setting are passed directly
   715         -on to \fBoutputChannel\fR by the master process.
          705  +by a [\fBconfigure -verbose\fR] setting are passed directly
          706  +on to [\fBoutputChannel\fR] by the master process.
   716    707   .PP
   717    708   After evaluating all selected test files, a summary of the
   718         -results is printed to \fBoutputChannel\fR.  The summary
   719         -includes the total number of \fBtest\fRs evaluated, broken
          709  +results is printed to [\fBoutputChannel\fR].  The summary
          710  +includes the total number of [\fBtest\fR]s evaluated, broken
   720    711   down into those skipped, those passed, and those failed.
   721    712   The summary also notes the number of files evaluated, and the names
   722    713   of any files with failing tests or errors.  A list of
   723    714   the constraints that caused tests to be skipped, and the
   724    715   number of tests skipped for each is also printed.  Also,
   725    716   messages are printed if it appears that evaluation of
   726    717   a test file has caused any temporary files to be left
   727         -behind in \fBconfigure \-tmpdir\fR.
          718  +behind in [\fBconfigure -tmpdir\fR].
   728    719   .PP
   729    720   Having completed and summarized all selected test files,
   730         -\fBrunAllTests\fR then recursively acts on subdirectories
   731         -of \fBconfigure \-testdir\fR.  All subdirectories that
   732         -match any of the patterns in \fBconfigure \-relateddir\fR
          721  +[\fBrunAllTests\fR] then recursively acts on subdirectories
          722  +of [\fBconfigure -testdir\fR].  All subdirectories that
          723  +match any of the patterns in [\fBconfigure -relateddir\fR]
   733    724   and do not match any of the patterns in
   734         -\fBconfigure \-asidefromdir\fR are examined.  If
          725  +[\fBconfigure -asidefromdir\fR] are examined.  If
   735    726   a file named \fBall.tcl\fR is found in such a directory,
   736         -it will be \fBsource\fRd in the caller's context.
          727  +it will be [\fBsource\fR]d in the caller's context.
   737    728   Whether or not an examined directory contains an
   738    729   \fBall.tcl\fR file, its subdirectories are also scanned
   739         -against the \fBconfigure \-relateddir\fR and
   740         -\fBconfigure \-asidefromdir\fR patterns.  In this way,
          730  +against the [\fBconfigure -relateddir\fR] and
          731  +[\fBconfigure -asidefromdir\fR] patterns.  In this way,
   741    732   many directories in a directory tree can have all their
   742         -test files evaluated by a single \fBrunAllTests\fR
          733  +test files evaluated by a single [\fBrunAllTests\fR]
   743    734   command.
   744    735   .SH "CONFIGURABLE OPTIONS"
   745         -The \fBconfigure\fR command is used to set and query the configurable
          736  +The [\fBconfigure\fR] command is used to set and query the configurable
   746    737   options of \fBtcltest\fR.  The valid options are:
   747    738   .TP
   748         -\fB\-singleproc \fIboolean\fR
   749         -Controls whether or not \fBrunAllTests\fR spawns a child process for
          739  +\fB-singleproc \fIboolean\fR
          740  +Controls whether or not [\fBrunAllTests\fR] spawns a child process for
   750    741   each test file.  No spawning when \fIboolean\fR is true.  Default
   751    742   value is false.
   752    743   .TP
   753         -\fB\-debug \fIlevel\fR
          744  +\fB-debug \fIlevel\fR
   754    745   Sets the debug level to \fIlevel\fR, an integer value indicating how
   755    746   much debugging information should be printed to stdout.  Note that
   756    747   debug messages always go to stdout, independent of the value of
   757         -\fBconfigure \-outfile\fR.  Default value is 0.  Levels are defined as:
          748  +[\fBconfigure -outfile\fR].  Default value is 0.  Levels are defined as:
   758    749   .RS
   759    750   .IP 0
   760    751   Do not display any debug information.
   761    752   .IP 1
   762    753   Display information regarding whether a test is skipped because it
   763    754   doesn't match any of the tests that were specified using by
   764         -\fBconfigure \-match\fR (userSpecifiedNonMatch) or matches any of
   765         -the tests specified by \fBconfigure \-skip\fR (userSpecifiedSkip).  Also
          755  +[\fBconfigure -match\fR] (userSpecifiedNonMatch) or matches any of
          756  +the tests specified by [\fBconfigure -skip\fR] (userSpecifiedSkip).  Also
   766    757   print warnings about possible lack of cleanup or balance in test files.
   767    758   Also print warnings about any re-use of test names.
   768    759   .IP 2
   769    760   Display the flag array parsed by the command line processor, the
   770    761   contents of the ::env array, and all user-defined variables that exist
   771    762   in the current namespace as they are used.
   772    763   .IP 3
   773    764   Display information regarding what individual procs in the test
   774    765   harness are doing.
   775    766   .RE
   776    767   .TP
   777         -\fB\-verbose \fIlevel\fR
          768  +\fB-verbose \fIlevel\fR
   778    769   Sets the type of output verbosity desired to \fIlevel\fR,
   779    770   a list of zero or more of the elements \fBbody\fR, \fBpass\fR,
   780    771   \fBskip\fR, \fBstart\fR, \fBerror\fR and \fBline\fR.  Default value
   781    772   is \fB{body error}\fR.
   782    773   Levels are defined as: 
   783    774   .RS
   784    775   .IP "body (b)"
................................................................................
   792    783   .IP "error (e)"
   793    784   Print errorInfo and errorCode, if they exist, when a test return code
   794    785   does not match its expected return code
   795    786   .IP "line (l)"
   796    787   Print source file line information of failed tests
   797    788   .RE
   798    789   The single letter abbreviations noted above are also recognized
   799         -so that
   800         -.QW "\fBconfigure \-verbose pt\fR"
   801         -is the same as
   802         -.QW "\fBconfigure \-verbose {pass start}\fR" .
          790  +so that [\fBconfigure -verbose pt\fR] is the same as
          791  +[\fBconfigure -verbose  {pass start}\fR].
   803    792   .TP
   804         -\fB\-preservecore \fIlevel\fR
          793  +\fB-preservecore \fIlevel\fR
   805    794   Sets the core preservation level to \fIlevel\fR.  This level
   806    795   determines how stringent checks for core files are.  Default
   807    796   value is 0.  Levels are defined as:
   808    797   .RS
   809    798   .IP 0
   810         -No checking \(em do not check for core files at the end of each test
   811         -command, but do check for them in \fBrunAllTests\fR after all
          799  +No checking - do not check for core files at the end of each test
          800  +command, but do check for them in [\fBrunAllTests\fR] after all
   812    801   test files have been evaluated.
   813    802   .IP 1
   814         -Also check for core files at the end of each \fBtest\fR command.
          803  +Also check for core files at the end of each [\fBtest\fR] command.
   815    804   .IP 2
   816    805   Check for core files at all times described above, and save a 
   817         -copy of each core file produced in \fBconfigure \-tmpdir\fR.
          806  +copy of each core file produced in [\fBconfigure -tmpdir\fR].
   818    807   .RE
   819    808   .TP
   820         -\fB\-limitconstraints \fIboolean\fR
   821         -Sets the mode by which \fBtest\fR honors constraints as described
          809  +\fB-limitconstraints \fIboolean\fR
          810  +Sets the mode by which [\fBtest\fR] honors constraints as described
   822    811   in \fBTESTS\fR above.  Default value is false.
   823    812   .TP
   824         -\fB\-constraints \fIlist\fR
          813  +\fB-constraints \fIlist\fR
   825    814   Sets all the constraints in \fIlist\fR to true.  Also used in
   826         -combination with
   827         -.QW "\fBconfigure \-limitconstraints true\fR"
   828         -to control an
          815  +combination with [\fBconfigure -limitconstraints true\fR] to control an
   829    816   alternative constraint mode as described in \fBTESTS\fR above.
   830    817   Default value is an empty list.
   831    818   .TP
   832         -\fB\-tmpdir \fIdirectory\fR
   833         -Sets the temporary directory to be used by \fBmakeFile\fR,
   834         -\fBmakeDirectory\fR, \fBviewFile\fR, \fBremoveFile\fR, 
   835         -and \fBremoveDirectory\fR as the default directory where
          819  +\fB-tmpdir \fIdirectory\fR
          820  +Sets the temporary directory to be used by [\fBmakeFile\fR],
          821  +[\fBmakeDirectory\fR], [\fBviewFile\fR], [\fBremoveFile\fR], 
          822  +and [\fBremoveDirectory\fR] as the default directory where
   836    823   temporary files and directories created by test files should
   837         -be created.  Default value is \fBworkingDirectory\fR.
          824  +be created.  Default value is [\fBworkingDirectory\fR].
   838    825   .TP
   839         -\fB\-testdir \fIdirectory\fR
   840         -Sets the directory searched by \fBrunAllTests\fR for test files
   841         -and subdirectories.  Default value is \fBworkingDirectory\fR.
          826  +\fB-testdir \fIdirectory\fR
          827  +Sets the directory searched by [\fBrunAllTests\fR] for test files
          828  +and subdirectories.  Default value is [\fBworkingDirectory\fR].
   842    829   .TP
   843         -\fB\-file \fIpatternList\fR
   844         -Sets the list of patterns used by \fBrunAllTests\fR to determine
          830  +\fB-file \fIpatternList\fR
          831  +Sets the list of patterns used by [\fBrunAllTests\fR] to determine
   845    832   what test files to evaluate.  Default value is \fB*.test\fR.
   846    833   .TP
   847         -\fB\-notfile \fIpatternList\fR
   848         -Sets the list of patterns used by \fBrunAllTests\fR to determine
   849         -what test files to skip.  Default value is
   850         -.QW \fBl.*.test\fR ,
   851         -so that any SCCS lock files are skipped.
          834  +\fB-notfile \fIpatternList\fR
          835  +Sets the list of patterns used by [\fBrunAllTests\fR] to determine
          836  +what test files to skip.  Default value is \fBl.*.test\fR, so
          837  +that any SCCS lock files are skipped.
   852    838   .TP
   853         -\fB\-relateddir \fIpatternList\fR
   854         -Sets the list of patterns used by \fBrunAllTests\fR to determine
          839  +\fB-relateddir \fIpatternList\fR
          840  +Sets the list of patterns used by [\fBrunAllTests\fR] to determine
   855    841   what subdirectories to search for an \fBall.tcl\fR file.  Default
   856         -value is
   857         -.QW \fB*\fR .
          842  +value is \fB*\fR.
   858    843   .TP
   859         -\fB\-asidefromdir \fIpatternList\fR
   860         -Sets the list of patterns used by \fBrunAllTests\fR to determine
          844  +\fB-asidefromdir \fIpatternList\fR
          845  +Sets the list of patterns used by [\fBrunAllTests\fR] to determine
   861    846   what subdirectories to skip when searching for an \fBall.tcl\fR file.
   862    847   Default value is an empty list.
   863    848   .TP
   864         -\fB\-match \fIpatternList\fR
   865         -Set the list of patterns used by \fBtest\fR to determine whether
   866         -a test should be run.  Default value is
   867         -.QW \fB*\fR .
          849  +\fB-match \fIpatternList\fR
          850  +Set the list of patterns used by [\fBtest\fR] to determine whether
          851  +a test should be run.  Default value is \fB*\fR.
   868    852   .TP
   869         -\fB\-skip \fIpatternList\fR
   870         -Set the list of patterns used by \fBtest\fR to determine whether
          853  +\fB-skip \fIpatternList\fR
          854  +Set the list of patterns used by [\fBtest\fR] to determine whether
   871    855   a test should be skipped.  Default value is an empty list.
   872    856   .TP
   873         -\fB\-load \fIscript\fR
   874         -Sets a script to be evaluated by \fBloadTestedCommands\fR.
          857  +\fB-load \fIscript\fR
          858  +Sets a script to be evaluated by [\fBloadTestedCommands\fR].
   875    859   Default value is an empty script.
   876    860   .TP
   877         -\fB\-loadfile \fIfilename\fR
          861  +\fB-loadfile \fIfilename\fR
   878    862   Sets the filename from which to read a script to be evaluated
   879         -by \fBloadTestedCommands\fR.  This is an alternative to
   880         -\fB\-load\fR.  They cannot be used together.
          863  +by [\fBloadTestedCommands\fR].  This is an alternative to
          864  +\fB-load\fR.  They cannot be used together.
   881    865   .TP
   882         -\fB\-outfile \fIfilename\fR 
          866  +\fB-outfile \fIfilename\fR 
   883    867   Sets the file to which all output produced by tcltest should be
   884         -written.  A file named \fIfilename\fR will be \fBopen\fRed for writing,
   885         -and the resulting channel will be set as the value of \fBoutputChannel\fR.
          868  +written.  A file named \fIfilename\fR will be [\fBopen\fR]ed for writing,
          869  +and the resulting channel will be set as the value of [\fBoutputChannel\fR].
   886    870   .TP
   887         -\fB\-errfile \fIfilename\fR
          871  +\fB-errfile \fIfilename\fR
   888    872   Sets the file to which all error output produced by tcltest
   889         -should be written.  A file named \fIfilename\fR will be \fBopen\fRed
          873  +should be written.  A file named \fIfilename\fR will be [\fBopen\fR]ed
   890    874   for writing, and the resulting channel will be set as the value
   891         -of \fBerrorChannel\fR.
          875  +of [\fBerrorChannel\fR].
   892    876   .SH "CREATING TEST SUITES WITH TCLTEST"
   893    877   .PP
   894         -The fundamental element of a test suite is the individual \fBtest\fR
          878  +The fundamental element of a test suite is the individual [\fBtest\fR]
   895    879   command.  We begin with several examples.
   896    880   .IP [1]
   897    881   Test of a script that returns normally.
   898    882   .RS
   899    883   .PP
   900    884   .CS
   901    885   \fBtest\fR example-1.0 {normal return} {
................................................................................
   941    925       file attributes $file -owner
   942    926   } -cleanup {
   943    927       removeFile test
   944    928   } -result $::tcl_platform(user)
   945    929   .CE
   946    930   .RE
   947    931   .PP
   948         -At the next higher layer of organization, several \fBtest\fR commands
          932  +At the next higher layer of organization, several [\fBtest\fR] commands
   949    933   are gathered together into a single test file.  Test files should have
   950    934   names with the \fB.test\fR extension, because that is the default pattern
   951         -used by \fBrunAllTests\fR to find test files.  It is a good rule of
          935  +used by [\fBrunAllTests\fR] to find test files.  It is a good rule of
   952    936   thumb to have one test file for each source code file of your project.
   953    937   It is good practice to edit the test file and the source code file
   954    938   together, keeping tests synchronized with code changes.
   955    939   .PP 
   956         -Most of the code in the test file should be the \fBtest\fR commands.
          940  +Most of the code in the test file should be the [\fBtest\fR] commands.
   957    941   Use constraints to skip tests, rather than conditional evaluation
   958         -of \fBtest\fR.
          942  +of [\fBtest\fR].
   959    943   .IP [5]
   960    944   Recommended system for writing conditional tests, using constraints to
   961    945   guard:
   962    946   .RS
   963    947   .PP
   964    948   .CS
   965    949   \fBtestConstraint\fR X [expr $myRequirement]
................................................................................
   978    962       test badConditionalTest {} {
   979    963           #body
   980    964       } result
   981    965   }
   982    966   .CE
   983    967   .RE
   984    968   .PP
   985         -Use the \fB\-setup\fR and \fB\-cleanup\fR options to establish and release
          969  +Use the \fB-setup\fR and \fB-cleanup\fR options to establish and release
   986    970   all context requirements of the test body.  Do not make tests depend on
   987    971   prior tests in the file.  Those prior tests might be skipped.  If several
   988    972   consecutive tests require the same context, the appropriate setup
   989    973   and cleanup scripts may be stored in variable for passing to each tests
   990         -\fB\-setup\fR and \fB\-cleanup\fR options.  This is a better solution than
   991         -performing setup outside of \fBtest\fR commands, because the setup will
          974  +\fB-setup\fR and \fB-cleanup\fR options.  This is a better solution than
          975  +performing setup outside of [\fBtest\fR] commands, because the setup will
   992    976   only be done if necessary, and any errors during setup will be reported,
   993    977   and not cause the test file to abort.
   994    978   .PP
   995    979   A test file should be able to be combined with other test files and not
   996         -interfere with them, even when
   997         -.QW "\fBconfigure -singleproc 1\fR"
   998         -causes all files to be evaluated in a common interpreter.  A simple way to
          980  +interfere with them, even when [\fBconfigure -singleproc 1\fR] causes
          981  +all files to be evaluated in a common interpreter.  A simple way to
   999    982   achieve this is to have your tests define all their commands and variables
  1000    983   in a namespace that is deleted when the test file evaluation is complete.
  1001    984   A good namespace to use is a child namespace \fBtest\fR of the namespace
  1002    985   of the module you are testing.
  1003    986   .PP
  1004    987   A test file should also be able to be evaluated directly as a script,
  1005         -not depending on being called by a master \fBrunAllTests\fR.  This
          988  +not depending on being called by a master [\fBrunAllTests\fR].  This
  1006    989   means that each test file should process command line arguments to give
  1007    990   the tester all the configuration control that \fBtcltest\fR provides.
  1008    991   .PP
  1009         -After all \fBtest\fRs in a test file, the command \fBcleanupTests\fR
          992  +After all [\fBtest\fR]s in a test file, the command [\fBcleanupTests\fR]
  1010    993   should be called.
  1011    994   .IP [7]
  1012    995   Here is a sketch of a sample test file illustrating those points:
  1013    996   .RS
  1014    997   .PP
  1015    998   .CS
  1016    999   package require tcltest 2.2
................................................................................
  1034   1017   }
  1035   1018   namespace delete ::example::test
  1036   1019   .CE
  1037   1020   .RE
  1038   1021   .PP
  1039   1022   The next level of organization is a full test suite, made up of several
  1040   1023   test files.  One script is used to control the entire suite.  The
  1041         -basic function of this script is to call \fBrunAllTests\fR after
         1024  +basic function of this script is to call [\fBrunAllTests\fR] after
  1042   1025   doing any necessary setup.  This script is usually named \fBall.tcl\fR
  1043         -because that's the default name used by \fBrunAllTests\fR when combining
         1026  +because that's the default name used by [\fBrunAllTests\fR] when combining
  1044   1027   multiple test suites into one testing run.
  1045   1028   .IP [8]
  1046   1029   Here is a sketch of a sample test suite master script:
  1047   1030   .RS
  1048   1031   .PP
  1049   1032   .CS
  1050   1033   package require Tcl 8.4
  1051   1034   package require tcltest 2.2
  1052   1035   package require example
  1053         -\fB::tcltest::configure\fR -testdir \e
         1036  +\fB::tcltest::configure\fR -testdir \\
  1054   1037           [file dirname [file normalize [info script]]]
  1055   1038   eval \fB::tcltest::configure\fR $argv
  1056   1039   \fB::tcltest::runAllTests\fR
  1057   1040   .CE
  1058   1041   .RE
  1059   1042   .SH COMPATIBILITY
  1060   1043   .PP
................................................................................
  1061   1044   A number of commands and variables in the \fB::tcltest\fR namespace
  1062   1045   provided by earlier releases of \fBtcltest\fR have not been documented
  1063   1046   here.  They are no longer part of the supported public interface of
  1064   1047   \fBtcltest\fR and should not be used in new test suites.  However,
  1065   1048   to continue to support existing test suites written to the older
  1066   1049   interface specifications, many of those deprecated commands and
  1067   1050   variables still work as before.  For example, in many circumstances,
  1068         -\fBconfigure\fR will be automatically called shortly after
  1069         -.QW "\fBpackage require tcltest 2.1\fR"
  1070         -succeeds with arguments
         1051  +[\fBconfigure\fR] will be automatically called shortly after
         1052  +[\fBpackage require tcltest 2.1\fR] succeeds with arguments
  1071   1053   from the variable \fB::argv\fR.  This is to support test suites
  1072   1054   that depend on the old behavior that \fBtcltest\fR was automatically
  1073   1055   configured from command line arguments.  New test files should not
  1074   1056   depend on this, but should explicitly include
  1075   1057   .PP
  1076   1058   .CS
  1077   1059   eval \fB::tcltest::configure\fR $::argv
  1078   1060   .CE
  1079   1061   .PP
  1080   1062   to establish a configuration from command line arguments.
  1081   1063   .SH "KNOWN ISSUES"
  1082         -There are two known issues related to nested evaluations of \fBtest\fR.
         1064  +There are two known issues related to nested evaluations of [\fBtest\fR].  
  1083   1065   The first issue relates to the stack level in which test scripts are
  1084   1066   executed.  Tests nested within other tests may be executed at the same
  1085   1067   stack level as the outermost test.  For example, in the following code: 
  1086   1068   .PP
  1087   1069   .CS
  1088   1070   \fBtest\fR level-1.1 {level 1} {
  1089   1071       -body {
................................................................................
  1092   1074       }
  1093   1075   }
  1094   1076   .CE
  1095   1077   .PP
  1096   1078   any script executed in level-2.1 may be executed at the same stack
  1097   1079   level as the script defined for level-1.1.  
  1098   1080   .PP
  1099         -In addition, while two \fBtest\fRs have been run, results will only
  1100         -be reported by \fBcleanupTests\fR for tests at the same level as
         1081  +In addition, while two [\fBtest\fR]s have been run, results will only
         1082  +be reported by [\fBcleanupTests\fR] for tests at the same level as
  1101   1083   test level-1.1.  However, test results for all tests run prior to
  1102   1084   level-1.1 will be available when test level-2.1 runs.  What this
  1103   1085   means is that if you try to access the test results for test level-2.1,
  1104         -it will may say that
  1105         -.QW m
  1106         -tests have run,
  1107         -.QW n
  1108         -tests have been skipped,
  1109         -.QW o
  1110         -tests have passed and
  1111         -.QW p
  1112         -tests have failed, where
  1113         -.QW m ,
  1114         -.QW n ,
  1115         -.QW o ,
  1116         -and
  1117         -.QW p
  1118         -refer to tests that were run at the same test level as test level-1.1.
         1086  +it will may say that 'm' tests have run, 'n' tests have
         1087  +been skipped, 'o' tests have passed and 'p' tests have failed,
         1088  +where 'm', 'n', 'o', and 'p' refer to tests that were run at the
         1089  +same test level as test level-1.1. 
  1119   1090   .PP
  1120   1091   Implementation of output and error comparison in the test command
  1121   1092   depends on usage of ::puts in your application code.  Output is
  1122   1093   intercepted by redefining the ::puts command while the defined test
  1123   1094   script is being run.  Errors thrown by C procedures or printed
  1124   1095   directly from C applications will not be caught by the test command.
  1125         -Therefore, usage of the \fB\-output\fR and \fB\-errorOutput\fR
  1126         -options to \fBtest\fR is useful only for pure Tcl applications
  1127         -that use \fB::puts\fR to produce output. 
         1096  +Therefore, usage of the \fB-output\fR and \fB-errorOutput\fR
         1097  +options to [\fBtest\fR] is useful only for pure Tcl applications
         1098  +that use [\fB::puts\fR] to produce output. 
  1128   1099   .SH KEYWORDS
  1129   1100   test, test harness, test suite

Changes to doc/tclvars.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\" 
     8         -'\" RCS: @(#) $Id: tclvars.n,v 1.28 2007/10/24 14:29:39 dkf Exp $
            8  +'\" RCS: @(#) $Id: tclvars.n,v 1.29 2007/10/26 20:11:53 dgp Exp $
     9      9   '\" 
    10     10   .so man.macros
    11     11   .TH tclvars n 8.0 Tcl "Tcl Built-In Commands"
    12     12   .BS
    13     13   '\" Note:  do not modify the .SH NAME line immediately below!
    14     14   .SH NAME
    15     15   tclvars \- Variables used by Tcl
................................................................................
    35     35   passed to children by commands like \fBexec\fR.
    36     36   If the entire \fBenv\fR array is unset then Tcl will stop
    37     37   monitoring \fBenv\fR accesses and will not update environment
    38     38   variables.
    39     39   .RS
    40     40   Under Windows, the environment variables PATH and COMSPEC in any
    41     41   capitalization are converted automatically to upper case.  For instance, the
    42         -PATH variable could be exported by the operating system as
    43         -.QW path ,
    44         -.QW Path ,
    45         -.QW PaTh ,
    46         -etc., causing otherwise simple Tcl code to have to
           42  +PATH variable could be exported by the operating system as ``path'',
           43  +``Path'', ``PaTh'', etc., causing otherwise simple Tcl code to have to
    47     44   support many special cases.  All other environment variables inherited by
    48     45   Tcl are left unmodified.  Setting an env array variable to blank is the
    49     46   same as unsetting it as this is the behavior of the underlying Windows OS.
    50     47   It should be noted that relying on an existing and empty environment variable
    51     48   won't work on windows and is discouraged for cross-platform usage.
    52     49   .RE
    53     50   .TP
................................................................................
    77     74   \fBCHILDKILLED\fI pid sigName msg\fR
    78     75   This format is used when a child process has been killed because of
    79     76   a signal.  The \fIpid\fR element will be the process's identifier (in decimal).
    80     77   The \fIsigName\fR element will be the symbolic name of the signal that caused
    81     78   the process to terminate; it will be one of the names from the
    82     79   include file signal.h, such as \fBSIGPIPE\fR.
    83     80   The \fImsg\fR element will be a short human-readable message
    84         -describing the signal, such as
    85         -.QW "write on pipe with no readers"
           81  +describing the signal, such as ``write on pipe with no readers''