Clean up the indentation mess

Use 'indent'. Not perfect, but at least consistent.

Signed-off-by: Steve Bennett <steveb@workware.net.au>

8 files changed, 0 insertions, 4376 deletions

diff --git a/doc/AIO-Extension.txt b/doc/AIO-Extension.txt
deleted file mode 100644
index e69de29..0000000
--- a/doc/AIO-Extension.txt
+++ /dev/null
diff --git a/doc/Embedder-HOWTO.txt b/doc/Embedder-HOWTO.txt
deleted file mode 100644
index e69de29..0000000
--- a/doc/Embedder-HOWTO.txt
+++ /dev/null
diff --git a/doc/Makefile b/doc/Makefile
deleted file mode 100644
index eef7bcb..0000000
--- a/doc/Makefile
+++ /dev/null
@@ -1,9 +0,0 @@
-TCLSH := $(shell which jimsh)
-ifeq ($(TCLSH),)
-TCLSH := $(shell which tclsh)
-endif
-
-all: Tcl.html
-
-Tcl.html: jim_tcl.txt make-index
-	$(TCLSH) make-index < jim_tcl.txt | asciidoc -o $@ -d manpage -
diff --git a/doc/Sqlite-Extension.txt b/doc/Sqlite-Extension.txt
deleted file mode 100644
index 4346d25..0000000
--- a/doc/Sqlite-Extension.txt
+++ /dev/null
@@ -1,177 +0,0 @@
-Jim Sqlite extension documentation.
-Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
-
-
-Overview
-~~~~~~~~
-
-The Sqlite extension makes possible to work with sqlite (http://www.sqlite.org)
-databases from Jim. SQLite is a small C library that implements a
-self-contained, embeddable, zero-configuration SQL database engine. This
-means it is perfect for embedded systems, and for stand-alone applications
-that need the power of SQL without to use an external server like Mysql.
-
-Basic usage
-~~~~~~~~~~~
-
-The Sqlite extension exports an Object Based interface for databases. In order
-to open a database use:
-
-  set f [sqlite.open dbname]
-
-The [sqlite.open] command returns a db handle, that is a command name that
-can be used to perform operations on the database. A real example:
-
-    . set db [sqlite.open test.db]
-    sqlite.handle0
-    . $db query "SELECT * from tbl1" 
-    {one hello! two 10} {one goodbye two 20}
-
-In the second line the handle is used as a command name, followed
-by the 'method' or 'subcommand' ("query" in the example), and the arguments.
-
-The query method
-~~~~~~~~~~~~~~~~
-
-The query method has the following signature:
-
-    $db query SqlQuery ?args?
-
-The sql query may contain occurrences of "%s" that are substituted
-in the actual query with the following arguments, quoted in order
-to make sure that the query is correct even if this arguments contain
-"'" characters. So for example it is possible to write:
-
-    . $db query "SELECT * from tbl1 WHERE one='%s'" hello!
-    {one hello! two 10}
-
-Instead of hello! it is possible to use a string with embedded "'":
-
-    . $db query "SELECT * from tbl1 WHERE one='%s'" a'b
-    (no matches - the empty list is returned)
-
-This does not work instead using the Tcl variable expansion in the string:
-
-    . $db query "SELECT * from tbl1 WHERE one='$foo'"
-    Runtime error, file "?", line 1:
-        near "b": syntax error
-
-In order to obtain an actual '%' character in the query, there is just
-to use two, like in "foo %% bar". This is the same as the [format] argument.
-
-Specification of query results
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In one of the above examples, the following query was used:
-
-    . $db query "SELECT * from tbl1" 
-    {one hello! two 10} {one goodbye two 20}
-
-As you can see the result of a query is a list of lists. Every
-element of the list represents a row, as a list of key/value pairs,
-so actually every row is a Jim dictionary.
-
-The following example and generated output show how to take advantage
-of this representation:
-
-    . set res [$db query "SELECT * from tbl1"]
-    {one hello! two 10} {one goodbye two 20}
-    . foreach row $res {puts "One: $row(one), Two: $row(two)"}
-    One: hello!, Two: 10
-    One: goodbye, Two: 20
-
-To access every row sequentially is very simple, and field of a row
-can be accessed using the $row(field) syntax.
-
-The close method
-~~~~~~~~~~~~~~~~
-
-In order to close the db, use the 'close' method that will have as side effect
-to close the db and to remove the command associated with the db.
-Just use:
-
-    $db close
-
-Handling NULL values
-~~~~~~~~~~~~~~~~~~~~
-
-In the SQL language there is a special value NULL that is not the empty
-string, so how to represent it in a typeless language like Tcl?
-For default this extension will use the empty string, but it is possible
-to specify a different string for the NULL value.
-
-In the above example there were two rows in the 'tbl1' table. Now
-we can add usign the "sqlite" command line client another one with
-a NULL value:
-
-    sqlite> INSERT INTO tbl1 VALUES(NULL,30);
-    sqlite> .exit
-
-That's what the sqlite extension will return for default:
-
-    . $db query "SELECT * from tbl1"
-    {one hello! two 10} {one goodbye two 20} {one {} two 30}
-
-As you can see in the last row, the NULL is represented as {}, that's
-the empty string. Using the -null option of the 'query' command we
-can change this default, and tell the sqlite extension to represent
-the NULL value as a different string:
-
-    . $db query -null <<NULL>> "SELECT * from tbl1"
-    {one hello! two 10} {one goodbye two 20} {one <<NULL>> two 30}
-
-This way if the emtpy string has some semantical value for your
-dataset you can change it.
-
-Finding the ID of the last inserted row
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This is as simple as:
-
-    . $db lastid
-    10
-
-Number of rows changed by the most recent query
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This is also very simple, there is just to use the 'changes' method
-without arugments.
-
-    . $db changes
-    5
-
-Note that if you drop an entire table the number of changes will
-be reported as zero, because of details of the sqlite implementation.
-
-That's all,
-Enjoy!
-Salvatore Sanfilippo
-
-p.s. this extension is just the work of some hour thanks to the cool
-clean C API that sqlite exports. Thanks to the author of sqlite for this
-great work.
-
-In memory databases
-~~~~~~~~~~~~~~~~~~~
-
-SQLite is able to create in-memory databases instead to use files.
-This is of course faster and does not need the ability to write
-to the filesystem. Of course this databases are only useful for
-temp data.
-
-In-memory DBs are used just like regular databases, just the name used to
-open the database is :memory:. That's an example that does not use the
-filesystem at all to create and work with the db.
-
-  package require sqlite
-  set db [sqlite.open :memory:]
-  $db query {CREATE TABLE plays (id, author, title)}
-  $db query {INSERT INTO plays (id, author, title) VALUES (1, 'Goethe', 'Faust');}
-  $db query {INSERT INTO plays (id, author, title) VALUES (2, 'Shakespeare', 'Hamlet');}
-  $db query {INSERT INTO plays (id, author, title) VALUES (3, 'Sophocles', 'Oedipus Rex');}
-  set res [$db query "SELECT * FROM plays"]
-  $db close
-  foreach r $res {puts $r(author)}
-
-Of course once the Jim process is destroyed the database will no longer
-exists.
diff --git a/doc/Tcl.html.supplied b/doc/Tcl.html.supplied
deleted file mode 100644
index e69de29..0000000
--- a/doc/Tcl.html.supplied
+++ /dev/null
diff --git a/doc/jim_man.txt b/doc/jim_man.txt
deleted file mode 100644
index fca664c..0000000
--- a/doc/jim_man.txt
+++ /dev/null
@@ -1,98 +0,0 @@
-Jim(n)
-======
-
-NAME
-----
-Jim - a better Tcl
-
-SYNOPSIS
---------
-
-  cc <source> -ltcl6
-
-or
-
-  jimsh <script>
-
-INTRODUCTION
-------------
-# what: jim commands, description, points to ponder
-
-jim 
-	set var [value]
-
-	dict
-
-	array [get | set ]
-	set $array($elem) $val
-		the array command and array syntax $array($elem) is 
-		an wrapper around dict!
-
-	
-package eventloop
-	after time/ms script
-		the script is mandatory! a blocking wait is not implemented ( good!? )
-		returns event_handle
-		open: after cancel and remaining time query. ( stubs in C exist UK)
-
-	vwait variable
-		work the eventloop until variable is accessed.
-		currently works only on change of variable content!!
-		returns ?variable value?
-
-package aio
-	aio.open 
-		returns handle ?aio.file<nnn>?
-
-	aio.socket <socketspec> <serverspec>|<remotehostspec> 
-		socketspec       may be stream, stream.server ( TODO : dgram , domain, ..... ) 
-		serverspec       may be [ANY|<InterfaceIPorName>]:<port|servicename>
-		remotehostspec   may be <hostIPorName>:<port|servicename>
-		returns handle ?aio.socket<nnn>? | aio.
-
-	$aio.handle
-		close 
-		tell
-		seek
-		gets 
-		read 
-		write 
-		ndelay [1|0]
-		readable [ {} | <readable event script> [ <eof event script> ] ]
-			noargs: return the scripts for readable event, optional eof event script.
-			returns {} on not setup
-			[ list <readable script> <eof script> ]
-			arg {} : remove event
-			arg <readable script> : setup script or read event, fold eof into this script
-			arg <readable script> <eof script> same as above, eof is handled separately.
-
-		writable
-			same for writable, no eof though
-		onexception
-			same for out-of-band data
-
-		accept
-			applys only to server sockets and should be used in a fileevent.
-			returns a new socket handle for the accepted connection.
-
-
-package posix
-	signal <signame> [ <sigaction> ]
-		tell signal action for signal $signame or if given set action to $sigaction
-		$sigaction can be either default, ignore , debug or ( TODO: an action script 
-		that works like a fileevent )
-		in all cases the previous action is returned.
-
-	sleep	<seconds> 
-		sleep number of seconds
-
-	usleep	<delay> [ <units> ]
-		call usleep/nanosleep with given value
-		bare or time as float plus unit ( one of s ms us ns )
-		
-	pit
-		return unix second ( since epoch ) as a float(double)
-	Jpit
-		return Julian Date in days as a float(double)!
-		see http://en.wikipedia.org/wiki/Julian_Date
-
diff --git a/doc/jim_tcl.txt b/doc/jim_tcl.txt
deleted file mode 100644
index 46484fb..0000000
--- a/doc/jim_tcl.txt
+++ /dev/null
@@ -1,4037 +0,0 @@
-Jim Tcl(n)
-==========
-
-NAME
-----
-Jim Tcl v0.62 - overview of the Jim tool command language facilities
-
-SYNOPSIS
---------
-
-  cc <source> -ljim
-
-or
-
-  jimsh <script>
-
-.Quick Index
-* <<CommandIndex,Command Reference>>
-* <<OperatorPrecedence,Operator Precedence>>
-* <<BuiltinVariables, Builtin Variables>>
-* <<BackslashSequences, Backslash Sequences>>
-
-INTRODUCTION
-------------
-Jim is a reimplementation of Tcl, combining some features from
-earlier, smaller versions of Tcl (6.x) as well as more modern
-features from later versions of Tcl (7.x, 8.x). It also has some some
-entirely new features not available in any version of Tcl.
-
-This version is approximately the same size as "tinytcl" (6.8) but
-is faster and has more features.
-
-Note that most of this man page is the original 6.8 Tcl man page, with
-changes made for differences with Jim.
-
-The major differences are:
-
-1. Object-based I/O (aio) with backward compatibility wrapper
-2. I/O: Support for sockets (client and server)
-3. I/O: Support for readable/writable event handlers
-4. Integers are 64bit
-5. Support for references ('ref'/'getref'/'setref') and garbage collection
-6. Builtin dictionary type ('dict')
-7. 'file mkdir', 'file rename', 'file tempfile' (Tcl 7.x, 8.x)
-8. 'env' command to access environment variables
-9. List: 'lmap', 'lset', 'lreverse', 'lassign' (Tcl 8.x)
-10. 'os.fork', 'os.wait', 'rand' 
-11. '\{*\}'/'\{expand\}'
-12. 'string map' (Tcl 7.x)
-13. 'subst' (Tcl 7.x)
-14. 'switch' (Tcl 7.x) (note that 'case' is provided for compatibility)
-15. Must better error reporting. 'info stacktrace' as a replacement for 'errorInfo', 'errorCode'
-16. Support for "static" variables in procedures
-17. Significantly faster for many scripts/operations
-18. Support for tail-call optimisation, 'tailcall'
-19. Command pipelines via open "|..." are not supported (but see 'exec' and 'socket pipe')
-20. Variable traces are not supported
-21. The history command is not supported
-
-CHANGES
--------
-Since v0.61:
-
-1. Add support to 'exec' for '>&', '>>&', '|&', '2>@1'
-2. Fix 'exec' error messages when special token (e.g. '>') is the last token
-3. Fix 'subst' handling of backslash escapes.
-4. Allow abbreviated options for 'subst'
-5. Add support for 'return', 'break', 'continue' in subst
-6. Many 'expr' bug fixes
-7. Add support for functions in 'expr' (e.g. int(), abs()), and also 'in', 'ni' list operations
-8. The variable name argument to 'regsub' is now optional
-9. Add support for 'unset -nocomplain'
-10. Add support for list commands: 'lassign', 'lrepeat'
-11. Fully-functional 'lsearch' is now implemented
-12. Add 'info nameofexecutable' and 'info returncodes'
-13. Allow 'catch' to determine what return codes are caught
-14. Allow 'incr' to increment an unset variable by first setting to 0
-15. Allow 'args' and optional arguments to the left or required arguments in 'proc'
-16. Add 'file copy'
-17. Add 'try ... finally' command
-
-TCL INTRODUCTION
------------------
-Tcl stands for 'tool command language' and is pronounced 'tickle.'
-It is actually two things: a language and a library.
-
-First, Tcl is a simple textual language, intended primarily for
-issuing commands to interactive programs such as text editors,
-debuggers, illustrators, and shells.  It has a simple syntax and is also
-programmable, so Tcl users can write command procedures to provide more
-powerful commands than those in the built-in set.
-
-Second, Tcl is a library package that can be embedded in application
-programs.  The Tcl library consists of a parser for the Tcl language,
-routines to implement the Tcl built-in commands, and procedures that
-allow each application to extend Tcl with additional commands specific
-to that application.  The application program generates Tcl commands and
-passes them to the Tcl parser for execution.  Commands may be generated
-by reading characters from an input source, or by associating command
-strings with elements of the application's user interface, such as menu
-entries, buttons, or keystrokes.
-
-When the Tcl library receives commands it parses them into component
-fields and executes built-in commands directly.  For commands implemented
-by the application, Tcl calls back to the application to execute the
-commands.  In many cases commands will invoke recursive invocations of the
-Tcl interpreter by passing in additional strings to execute (procedures,
-looping commands, and conditional commands all work in this way).
-
-An application program gains three advantages by using Tcl for its command
-language.  First, Tcl provides a standard syntax:  once users know Tcl,
-they will be able to issue commands easily to any Tcl-based application.
-Second, Tcl provides programmability.  All a Tcl application needs
-to do is to implement a few application-specific low-level commands.
-Tcl provides many utility commands plus a general programming interface
-for building up complex command procedures.  By using Tcl, applications
-need not re-implement these features.
-
-Third, Tcl can be used as a common language for communicating between
-applications.  Inter-application communication is not built into the
-Tcl core described here, but various add-on libraries, such as the Tk
-toolkit, allow applications to issue commands to each other.  This makes
-it possible for applications to work together in much more powerful ways
-than was previously possible.
-
-This manual page focuses primarily on the Tcl language.  It describes
-the language syntax and the built-in commands that will be available
-in any application based on Tcl.  The individual library procedures are
-described in more detail in separate manual pages, one per procedure.
-
-INTERPRETERS
-------------
-The central data structure in Tcl is an interpreter (C type 'Jim_Interp').
-An interpreter consists of a set of command bindings, a set of variable
-values, and a few other miscellaneous pieces of state.  Each Tcl command
-is interpreted in the context of a particular interpreter.
-
-Some Tcl-based applications will maintain multiple interpreters
-simultaneously, each associated with a different widget or portion of
-the application.  Interpreters are relatively lightweight structures.
-They can be created and deleted quickly, so application programmers should
-feel free to use multiple interpreters if that simplifies the application.
-
-DATA TYPES
-----------
-Tcl supports only one type of data:  strings.  All commands, all arguments
-to commands, all command results, and all variable values are strings.
-
-Where commands require numeric arguments or return numeric results,
-the arguments and results are passed as strings.  Many commands expect
-their string arguments to have certain formats, but this interpretation
-is up to the individual commands.  For example, arguments often contain
-Tcl command strings, which may get executed as part of the commands.
-The easiest way to understand the Tcl interpreter is to remember that
-everything is just an operation on a string.  In many cases Tcl constructs
-will look similar to more structured constructs from other languages.
-However, the Tcl constructs are not structured at all; they are just
-strings of characters, and this gives them a different behavior than
-the structures they may look like.
-
-Although the exact interpretation of a Tcl string depends on who is doing
-the interpretation, there are three common forms that strings take:
-commands, expressions, and lists.  The major sections below discuss
-these three forms in more detail.
-
-BASIC COMMAND SYNTAX
---------------------
-The Tcl language has syntactic similarities to both the Unix shells
-and Lisp.  However, the interpretation of commands is different
-in Tcl than in either of those other two systems.
-A Tcl command string consists of one or more commands separated
-by newline characters or semi-colons.
-Each command consists of a collection of fields separated by
-white space (spaces or tabs).
-The first field must be the name of a command, and the
-additional fields, if any, are arguments that will be passed to
-that command.  For example, the command:
-
-    set a 22
-
-has three fields:  the first, 'set', is the name of a Tcl command, and
-the last two, 'a' and '22', will be passed as arguments to
-the 'set' command.  The command name may refer either to a built-in
-Tcl command, an application-specific command bound in with the library
-procedure 'Jim_CreateCommand', or a command procedure defined with the
-'proc' built-in command.
-
-Arguments are passed literally as text strings.  Individual commands may
-interpret those strings in any fashion they wish.  The 'set' command,
-for example, will treat its first argument as the name of a variable
-and its second argument as a string value to assign to that variable.
-For other commands arguments may be interpreted as integers, lists,
-file names, or Tcl commands.
-
-Command names should normally be typed completely (e.g. no abbreviations).
-However, if the Tcl interpreter cannot locate a command it invokes a
-special command named 'unknown' which attempts to find or create the
-command.
-
-For example, at many sites 'unknown' will search through library
-directories for the desired command and create it as a Tcl procedure if
-it is found.  The 'unknown' command often provides automatic completion
-of abbreviated commands, but usually only for commands that were typed
-interactively.
-
-It's probably a bad idea to use abbreviations in command scripts and
-other forms that will be re-used over time:  changes to the command set
-may cause abbreviations to become ambiguous, resulting in scripts that
-no longer work.
-
-COMMENTS
---------
-If the first non-blank character in a command is '\#', then everything
-from the '\#' up through the next newline character is treated as
-a comment and ignored.  When comments are embedded inside nested
-commands (e.g. fields enclosed in braces) they must have properly-matched
-braces (this is necessary because when Tcl parses the top-level command
-it doesn't yet know that the nested field will be used as a command so
-it cannot process the nested comment character as a comment).
-
-GROUPING ARGUMENTS WITH DOUBLE-QUOTES
--------------------------------------
-Normally each argument field ends at the next white space, but
-double-quotes may be used to create arguments with embedded space.
-
-If an argument field begins with a double-quote, then the argument isn't
-terminated by white space (including newlines) or a semi-colon (see below
-for information on semi-colons); instead it ends at the next double-quote
-character.  The double-quotes are not included in the resulting argument.
-For example, the command
-
-    set a "This is a single argument"
-
-will pass two arguments to 'set':  'a' and 'This is a single argument'.
-
-Within double-quotes, command substitutions, variable substitutions,
-and backslash substitutions still occur, as described below.  If the
-first character of a command field is not a quote, then quotes receive
-no special interpretation in the parsing of that field.
-
-GROUPING ARGUMENTS WITH BRACES
-------------------------------
-Curly braces may also be used for grouping arguments.  They are similar
-to quotes except for two differences.  First, they nest; this makes them
-easier to use for complicated arguments like nested Tcl command strings.
-Second, the substitutions described below for commands, variables, and
-backslashes do *not* occur in arguments enclosed in braces, so braces
-can be used to prevent substitutions where they are undesirable.
-
-If an argument field begins with a left brace, then the argument ends
-at the matching right brace.  Tcl will strip off the outermost layer
-of braces and pass the information between the braces to the command
-without any further modification.  For example, in the command
-
-    set a {xyz a {b c d}}
-
-the 'set' command will receive two arguments: 'a'
-and 'xyz a {b c d}'.
-
-When braces or quotes are in effect, the matching brace or quote need
-not be on the same line as the starting quote or brace; in this case
-the newline will be included in the argument field along with any other
-characters up to the matching brace or quote.  For example, the 'eval'
-command takes one argument, which is a command string; 'eval' invokes
-the Tcl interpreter to execute the command string.  The command
-
-    eval {
-      set a 22
-      set b 33
-    }
-
-will assign the value '22' to 'a' and '33' to 'b'.
-
-If the first character of a command field is not a left
-brace, then neither left nor right
-braces in the field will be treated specially (except as part of
-variable substitution; see below).
-
-COMMAND SUBSTITUTION WITH BRACKETS
-----------------------------------
-If an open bracket occurs in a field of a command, then command
-substitution occurs (except for fields enclosed in braces).  All of the
-text up to the matching close bracket is treated as a Tcl command and
-executed immediately.  Then the result of that command is substituted
-for the bracketed text.  For example, consider the command
-
-    set a [set b]
-
-When the 'set' command has only a single argument, it is the name of a
-variable and 'set' returns the contents of that variable.  In this case,
-if variable 'b' has the value 'foo', then the command above is equivalent
-to the command
-
-    set a foo
-
-Brackets can be used in more complex ways.  For example, if the variable
-'b' has the value 'foo' and the variable 'c' has the value 'gorp',
-then the command
-
-    set a xyz[set b].[set c]
-
-is equivalent to the command
-
-    set a xyzfoo.gorp
-
-
-A bracketed command may contain multiple commands separated by newlines
-or semi-colons in the usual fashion.  In this case the value of the last
-command is used for substitution.  For example, the command
-
-    set a x[set b 22
-    expr $b+2]x
-
-is equivalent to the command
-
-    set a x24x
-
-
-If a field is enclosed in braces then the brackets and the characters
-between them are not interpreted specially; they are passed through to
-the argument verbatim.
-
-VARIABLE SUBSTITUTION WITH $
-----------------------------
-The dollar sign ('$') may be used as a special shorthand form for
-substituting variable values.  If '$' appears in an argument that isn't
-enclosed in braces then variable substitution will occur.  The characters
-after the '$', up to the first character that isn't a number, letter,
-or underscore, are taken as a variable name and the string value of that
-variable is substituted for the name.
-
-For example, if variable 'foo' has the value 'test', then the command
-
-    set a $foo.c
-
-is equivalent to the command
-
-    set a test.c
-
-There are two special forms for variable substitution.  If the next
-character after the name of the variable is an open parenthesis, then
-the variable is assumed to be an array name, and all of the characters
-between the open parenthesis and the next close parenthesis are taken as
-an index into the array.  Command substitutions and variable substitutions
-are performed on the information between the parentheses before it is
-used as an index.
-
-For example, if the variable 'x' is an array with one element named
-'first' and value '87' and another element named '14' and value 'more',
-then the command
-
-    set a xyz$x(first)zyx
-
-is equivalent to the command
-
-    set a xyz87zyx
-
-If the variable 'index' has the value '14', then the command
-
-    set a xyz$x($index)zyx
-
-is equivalent to the command
-
-    set a xyzmorezyx
-
-For more information on arrays, see VARIABLES AND ARRAYS below.
-
-The second special form for variables occurs when the dollar sign is
-followed by an open curly brace.  In this case the variable name consists
-of all the characters up to the next curly brace.
-
-Array references are not possible in this form:  the name between braces
-is assumed to refer to a scalar variable.  For example, if variable
-'foo' has the value 'test', then the command
-
-    set a abc${foo}bar
-
-is equivalent to the command
-
-    set a abctestbar
-
-
-Variable substitution does not occur in arguments that are enclosed in
-braces:  the dollar sign and variable name are passed through to the
-argument verbatim.
-
-The dollar sign abbreviation is simply a shorthand form.  '$a' is
-completely equivalent to '[set a]'; it is provided as a convenience
-to reduce typing.
-
-SEPARATING COMMANDS WITH SEMI-COLONS
-------------------------------------
-Normally, each command occupies one line (the command is terminated by a
-newline character).  However, semi-colon (';') is treated as a command
-separator character; multiple commands may be placed on one line by
-separating them with a semi-colon.  Semi-colons are not treated as
-command separators if they appear within curly braces or double-quotes.
-
-BACKSLASH SUBSTITUTION
-----------------------
-Backslashes may be used to insert non-printing characters into command
-fields and also to insert special characters like braces and brackets
-into fields without them being interpreted specially as described above.
-
-The backslash sequences understood by the Tcl interpreter are
-listed below.  In each case, the backslash
-sequence is replaced by the given character:
-[[BackslashSequences]]
-+{backslash}b+::
-    Backspace (0x8)
-
-+{backslash}f+::
-    Form feed (0xc)
-
-+{backslash}n+::
-    Newline (0xa)
-
-+{backslash}r+::
-    Carriage-return (0xd).
-
-+{backslash}t+::
-    Tab (0x9).
-
-+{backslash}v+::
-    Vertical tab (0xb).
-
-+{backslash}{+::
-    Left brace ({).
-
-+{backslash}}+::
-    Right brace (}).
-
-+{backslash}[+::
-    Open bracket ([).
-
-+{backslash}]+::
-    Close bracket (]).
-
-+{backslash}$+::
-    Dollar sign ($).
-
-+{backslash}<space>+::
-    Space ( ): doesn't terminate argument.
-
-+{backslash};+::
-    Semi-colon: doesn't terminate command.
-
-+{backslash}"+::
-    Double-quote.
-
-+{backslash}<newline>+::
-    Nothing:  this joins two lines together
-    into a single line.  This backslash feature is unique in that
-    it will be applied even when the sequence occurs within braces.
-
-+{backslash}{backslash}+::
-    Backslash ('{backslash}').
-
-+{backslash}*ddd*+::
-    The digits *ddd* (one, two, or three of them) give the octal value of
-    the character.  Note that Jim supports null characters in strings.
-
-For example, in the command
-
-    set a \{x\[\ yz\141
-
-the second argument to 'set' will be '{x[ yza'.
-
-If a backslash is followed by something other than one of the options
-described above, then the backslash is transmitted to the argument
-field without any special processing, and the Tcl scanner continues
-normal processing with the next character.  For example, in the
-command
-
-    set \*a \\\{foo
-
-The first argument to 'set' will be '{backslash}*a' and the second
-argument will be '{backslash}{foo'.
-
-If an argument is enclosed in braces, then backslash sequences inside
-the argument are parsed but no substitution occurs (except for
-backslash-newline):  the backslash
-sequence is passed through to the argument as is, without making
-any special interpretation of the characters in the backslash sequence.
-In particular, backslashed braces are not counted in locating the
-matching right brace that terminates the argument.
-For example, in the
-command
-
-    set a {\{abc}
-
-the second argument to 'set' will be '{backslash}{abc'.
-
-This backslash mechanism is not sufficient to generate absolutely
-any argument structure; it only covers the
-most common cases.  To produce particularly complicated arguments
-it is probably easiest to use the 'format' command along with
-command substitution.
-
-STRING AND LIST INDEX SPECIFICATIONS
-------------------------------------
-
-Many string and list commands take one or more 'index' parameters which
-specify a position in the string relative to the start or end of the string/list.
-
-The index may be one of the following forms:
-
-`integer`::
-    A simple integer, where '0' refers to the first element of the string
-    or list.
-
-`integer+integer` or::
-`integer-integer`::
-    The sum or difference of the two integers. e.g. +2+3+ refers to the 5th element.
-    This is useful when used with (e.g.) +$i+1+ rather than the more verbose
-    +[expr {$i+1\}]+
-
-`end`::
-    The last element of the string or list.
-
-`end-integer`::
-    The 'nth-from-last' element of the string or list.
-
-COMMAND SUMMARY
----------------
-1. A command is just a string.
-2. Within a string commands are separated by newlines or semi-colons
-   (unless the newline or semi-colon is within braces or brackets
-   or is backslashed).
-3. A command consists of fields.  The first field is the name of the command.
-   The other fields are strings that are passed to that command as arguments.
-4. Fields are normally separated by white space.
-5. Double-quotes allow white space and semi-colons to appear within
-   a single argument.
-   Command substitution, variable substitution, and backslash substitution
-   still occur inside quotes.
-6. Braces defer interpretation of special characters.
-   If a field begins with a left brace, then it consists of everything
-   between the left brace and the matching right brace. The
-   braces themselves are not included in the argument.
-   No further processing is done on the information between the braces
-   except that backslash-newline sequences are eliminated.
-7. If a field doesn't begin with a brace then backslash,
-   variable, and command substitution are done on the field.  Only a
-   single level of processing is done:  the results of one substitution
-   are not scanned again for further substitutions or any other
-   special treatment.  Substitution can
-   occur on any field of a command, including the command name
-   as well as the arguments.
-8. If the first non-blank character of a command is a '\#', everything
-   from the '\#' up through the next newline is treated as a comment
-   and ignored.
-
-EXPRESSIONS
------------
-The second major interpretation applied to strings in Tcl is
-as expressions.  Several commands, such as 'expr', 'for',
-and 'if', treat one or more of their arguments as expressions
-and call the Tcl expression processors ('Jim_ExprLong',
-'Jim_ExprBoolean', etc.) to evaluate them.
-
-The operators permitted in Tcl expressions are a subset of
-the operators permitted in C expressions, and they have the
-same meaning and precedence as the corresponding C operators.
-Expressions almost always yield numeric results
-(integer or floating-point values).
-For example, the expression
-
-    8.2 + 6
-
-evaluates to 14.2.
-
-Tcl expressions differ from C expressions in the way that
-operands are specified, and in that Tcl expressions support
-non-numeric operands and string comparisons.
-
-A Tcl expression consists of a combination of operands, operators,
-and parentheses.
-
-White space may be used between the operands and operators and
-parentheses; it is ignored by the expression processor.
-Where possible, operands are interpreted as integer values.
-
-Integer values may be specified in decimal (the normal case), in octal (if the
-first character of the operand is '0'), or in hexadecimal (if the first
-two characters of the operand are '0x').
-
-If an operand does not have one of the integer formats given
-above, then it is treated as a floating-point number if that is
-possible.  Floating-point numbers may be specified in any of the
-ways accepted by an ANSI-compliant C compiler (except that the
-'f', 'F', 'l', and 'L' suffixes will not be permitted in
-most installations).  For example, all of the
-following are valid floating-point numbers:  2.1, 3., 6e4, 7.91e+16.
-
-If no numeric interpretation is possible, then an operand is left
-as a string (and only a limited set of operators may be applied to
-it).
-
-1. Operands may be specified in any of the following ways:
-
-2. As a numeric value, either integer or floating-point.
-
-3. As a Tcl variable, using standard '$' notation.
-The variable's value will be used as the operand.
-
-4. As a string enclosed in double-quotes.
-The expression parser will perform backslash, variable, and
-command substitutions on the information between the quotes,
-and use the resulting value as the operand
-
-5. As a string enclosed in braces.
-The characters between the open brace and matching close brace
-will be used as the operand without any substitutions.
-
-6. As a Tcl command enclosed in brackets.
-The command will be executed and its result will be used as
-the operand.
-
-Where substitutions occur above (e.g. inside quoted strings), they
-are performed by the expression processor.
-However, an additional layer of substitution may already have
-been performed by the command parser before the expression
-processor was called.
-
-As discussed below, it is usually best to enclose expressions
-in braces to prevent the command parser from performing substitutions
-on the contents.
-
-For some examples of simple expressions, suppose the variable 'a' has
-the value 3 and the variable 'b' has the value 6.  Then the expression
-on the left side of each of the lines below will evaluate to the value
-on the right side of the line:
-
-    $a + 3.1                6.1
-    2 + "$a.$b"             5.6
-    4*[llength "6 2"]       8
-    {word one} < "word $a"  0
-
-The valid operators are listed below, grouped in decreasing order
-of precedence:
-[[OperatorPrecedence]]
-`int() double() round() abs()`::
-    Unary functions.
-    int() converts the numeric argument to an integer by truncating down.
-    double() converts the numeric argument to floating point.
-    round() converts the numeric argument to the closest integer value.
-    abs() takes the absolute value of the numeric argument.
-
-`sin() cos() tan() asin() acos() atan() sinh() cosh() tanh() ceil() floor() exp() log() log10() sqrt()`::
-    Unary math functions.
-    If Jim is compiled with math support, these functions are available.
-
-`- + ~ !`::
-    Unary minus, unary plus, bit-wise NOT, logical NOT.  None of these operands
-    may be applied to string operands, and bit-wise NOT may be
-    applied only to integers.
-
-`**`::
-    Power. e.g. pow(). If Jim is compiled with math support, supports doubles and
-    integers. Otherwise supports integers only.
-
-`* / %`::
-    Multiply, divide, remainder.  None of these operands may be
-    applied to string operands, and remainder may be applied only
-    to integers.
-
-`+ -`::
-    Add and subtract.  Valid for any numeric operands.
-
-`<<  >> <<< >>>`::
-    Left and right shift, left and right rotate.  Valid for integer operands only.
-
-`<  >  \<=  >=`::
-    Boolean less, greater, less than or equal, and greater than or equal.
-    Each operator produces 1 if the condition is true, 0 otherwise.
-    These operators may be applied to strings as well as numeric operands,
-    in which case string comparison is used.
-
-`==  !=`::
-    Boolean equal and not equal.  Each operator produces a zero/one result.
-    Valid for all operand types. *Note* that values will be converted to integers
-    if possible, then floating point types, and finally strings will be compared.
-    It is recommended that 'eq' and 'ne' should be used for string comparison.
-
-`eq ne`::
-    String equal and not equal.  Uses the string value directly without
-    attempting to convert to a number first.
-
-`in ni`::
-    String in list and not in list. For 'in', result is 1 if the left operand (as a string)
-    is contained in the right operand (as a list), or 0 otherwise. The result for
-    '{$a ni $list}' is equivalent to '{!($a in $list)}'.
-
-`&`::
-    Bit-wise AND.  Valid for integer operands only.
-
-`|`::
-    Bit-wise OR.  Valid for integer operands only.
-
-`^`::
-    Bit-wise exclusive OR.  Valid for integer operands only.
-
-`&&`::
-    Logical AND.  Produces a 1 result if both operands are non-zero, 0 otherwise.
-    Valid for numeric operands only (integers or floating-point).
-
-`||`::
-    Logical OR.  Produces a 0 result if both operands are zero, 1 otherwise.
-    Valid for numeric operands only (integers or floating-point).
-
-`x ? y : z`::
-    If-then-else, as in C.  If *x*
-    evaluates to non-zero, then the result is the value of *y*.
-    Otherwise the result is the value of *z*.
-    The *x* operand must have a numeric value, while *y* and *z* can
-    be of any type.
-
-See the C manual for more details on the results
-produced by each operator.
-All of the binary operators group left-to-right within the same
-precedence level.  For example, the expression
-
-    4*2 < 7
-
-evaluates to 0.
-
-The '&&', '||', and '?:' operators have 'lazy
-evaluation', just as in C, 
-which means that operands are not evaluated if they are
-not needed to determine the outcome.  For example, in
-
-    $v ? [a] : [b]
-
-only one of '[a]' or '[b]' will actually be evaluated,
-depending on the value of '$v'.
-
-All internal computations involving integers are done with the C
-type 'long long' if available, or 'long' otherwise, and all internal
-computations involving floating-point are done with the C type
-'double'.
-
-When converting a string to floating-point, exponent overflow is
-detected and results in a Tcl error.
-For conversion to integer from string, detection of overflow depends
-on the behavior of some routines in the local C library, so it should
-be regarded as unreliable.
-In any case, overflow and underflow are generally not detected
-reliably for intermediate results.
-
-Conversion among internal representations for integer, floating-point,
-and string operands is done automatically as needed.
-For arithmetic computations, integers are used until some
-floating-point number is introduced, after which floating-point is used.
-For example,
-
-    5 / 4
-
-yields the result 1, while
-
-    5 / 4.0
-    5 / ( [string length "abcd"] + 0.0 )
-
-both yield the result 1.25.
-
-String values may be used as operands of the comparison operators,
-although the expression evaluator tries to do comparisons as integer
-or floating-point when it can.
-If one of the operands of a comparison is a string and the other
-has a numeric value, the numeric operand is converted back to
-a string using the C 'sprintf' format specifier
-'%d' for integers and '%g' for floating-point values.
-For example, the expressions
-
-    "0x03" > "2"
-    "0y" < "0x12"
-
-both evaluate to 1.  The first comparison is done using integer
-comparison, and the second is done using string comparison after
-the second operand is converted to the string '18'.
-
-In general it is safest to enclose an expression in braces when
-entering it in a command:  otherwise, if the expression contains
-any white space then the Tcl interpreter will split it
-among several arguments.  For example, the command
-
-    expr $a + $b
-
-results in three arguments being passed to 'expr':  '$a',
-'+', and '$b'.  In addition, if the expression isn't in braces
-then the Tcl interpreter will perform variable and command substitution
-immediately (it will happen in the command parser rather than in
-the expression parser).  In many cases the expression is being
-passed to a command that will evaluate the expression later (or
-even many times if, for example, the expression is to be used to
-decide when to exit a loop).  Usually the desired goal is to re-do
-the variable or command substitutions each time the expression is
-evaluated, rather than once and for all at the beginning.  For example,
-the command
-
-    for {set i 1} $i<=10 {incr i} {...}        *** WRONG ***
-
-is probably intended to iterate over all values of `i` from 1 to 10.
-After each iteration of the body of the loop, 'for' will pass
-its second argument to the expression evaluator to see whether or not
-to continue processing.  Unfortunately, in this case the value of `i`
-in the second argument will be substituted once and for all when the
-'for' command is parsed.  If `i` was 0 before the 'for'
-command was invoked then for's second argument will be `0\<=10`
-which will always evaluate to 1, even though `i` eventually
-becomes greater than 10.  In the above case the loop will never
-terminate.  Instead, the expression should be placed in braces:
-
-    for {set i 1} {$i<=10} {incr i} {...}      *** RIGHT ***
-
-This causes the substitution of 'i'
-to be delayed; it will be re-done each time the expression is
-evaluated, which is the desired result.
-
-LISTS
------
-The third major way that strings are interpreted in Tcl is as lists.
-A list is just a string with a list-like structure
-consisting of fields separated by white space.  For example, the
-string
-
-    Al Sue Anne John
-
-is a list with four elements or fields.
-Lists have the same basic structure as command strings, except
-that a newline character in a list is treated as a field separator
-just like space or tab.  Conventions for braces and quotes
-and backslashes are the same for lists as for commands.  For example,
-the string
-
-    a b\ c {d e {f g h}}
-
-is a list with three elements:  'a', 'b c', and 'd e {f g h}'.
-
-Whenever an element is extracted from a list, the same rules about
-braces and quotes and backslashes are applied as for commands.  Thus in
-the example above when the third element is extracted from the list,
-the result is
-
-    d e {f g h}
-
-(when the field was extracted, all that happened was to strip off
-the outermost layer of braces).  Command substitution and
-variable substitution are never
-made on a list (at least, not by the list-processing commands; the
-list can always be passed to the Tcl interpreter for evaluation).
-
-The Tcl commands 'concat', 'foreach', 'lappend', 'lindex', 'linsert',
-'list', 'llength', 'lrange', 'lreplace', 'lsearch', and 'lsort' allow
-you to build lists, extract elements from them, search them, and perform
-other list-related functions.
-
-Advanced list commands include 'lrepeat', 'lreverse', 'lmap', 'lassign', 'lset'.
-
-LIST EXPANSION
---------------
-
-A new addition to Tcl 8.5 is the ability to expand a list into separate
-arguments. Support for this feature is also available in Jim.
-
-Consider the following attempt to exec a list:
-
-    set cmd {ls -l}
-    exec $cmd
-
-This will attempt to exec the a command named "ls -l", which will clearly not
-work. Typically eval and concat are required to solve this problem, however
-it can be solved much more easily with '\{*\}'.
-
-    exec {*}$cmd
-
-This will expand the following argument into individual elements and then evaluate
-the resulting command.
-
-Note that the official Tcl syntax is '\{*\}', however '\{expand\}' is retained
-for backward compatibility with experimental versions of this feature.
-
-REGULAR EXPRESSIONS
--------------------
-Tcl provides two commands that support string matching using
-'egrep'-style regular expressions: 'regexp' and 'regsub'.
-
-Regular expressions are implemented using the system's C library as
-Extended Regular Expressions (EREs) rather than Basic Regular Expressions (BREs).
-
-See regex(3) and regex(7) for full details.
-
-*NOTE* Tcl 7.x and 8.x use perl-style Advanced Regular Expressions (AREs).
-
-COMMAND RESULTS
----------------
-Each command produces two results:  a code and a string.  The
-code indicates whether the command completed successfully or not,
-and the string gives additional information.  The valid codes are
-defined in jim.h, and are:
-
-+JIM_OK(0)+::
-    This is the normal return code, and indicates that the command completed
-    successfully.  The string gives the command's return value.
-
-+JIM_ERR(1)+::
-    Indicates that an error occurred; the string gives a message describing
-    the error.
-
-+JIM_RETURN(2)+::
-    Indicates that the 'return' command has been invoked, and that the
-    current procedure (or top-level command or 'source' command)
-    should return immediately.  The
-    string gives the return value for the procedure or command.
-
-+JIM_BREAK(3)+::
-    Indicates that the 'break' command has been invoked, so the
-    innermost loop should abort immediately.  The string should always
-    be empty.
-
-+JIM_CONTINUE(4)+::
-    Indicates that the 'continue' command has been invoked, so the
-    innermost loop should go on to the next iteration.  The string
-    should always be empty.
-
-+JIM_SIGNAL(5)+::
-    Indicates that a signal was caught while executing a commands.
-    The string contains the name of the signal caught.
-    See the 'signal' and 'catch' commands.
-
-+JIM_EXIT(6)+::
-    Indicates that the command called the 'exit' command.
-    The string contains the exit code.
-
-Tcl programmers do not normally need to think about return codes,
-since +JIM_OK+ is almost always returned.  If anything else is returned
-by a command, then the Tcl interpreter immediately stops processing
-commands and returns to its caller.  If there are several nested
-invocations of the Tcl interpreter in progress, then each nested
-command will usually return the error to its caller, until eventually
-the error is reported to the top-level application code.  The
-application will then display the error message for the user.
-
-In a few cases, some commands will handle certain 'error' conditions
-themselves and not return them upwards.  For example, the 'for'
-command checks for the +JIM_BREAK+ code; if it occurs, then 'for'
-stops executing the body of the loop and returns +JIM_OK+ to its
-caller.  The 'for' command also handles +JIM_CONTINUE+ codes and the
-procedure interpreter handles +JIM_RETURN+ codes.  The 'catch'
-command allows Tcl programs to catch errors and handle them without
-aborting command interpretation any further.
-
-The 'info returncodes' command may be used to programmatically map between
-return codes and names.
-
-PROCEDURES
-----------
-Tcl allows you to extend the command interface by defining
-procedures.  A Tcl procedure can be invoked just like any other Tcl
-command (it has a name and it receives one or more arguments).
-The only difference is that its body isn't a piece of C code linked
-into the program; it is a string containing one or more other
-Tcl commands.
-
-The 'proc' command is used to create a new Tcl command procedure:
-
-+*proc* 'name args ?statics? body'+
-
-The new command is name *name*, and it replaces any existing command
-there may have been by that name. Whenever the new command is
-invoked, the contents of *body* will be executed by the Tcl
-interpreter.
-
-*args* specifies the formal arguments to the procedure.
-It consists of a list, possibly empty, of the following
-argument specifiers:
-
-+name+::
-    Required Argument - A simple argument name.
-
-+name default+::
-    Optional Argument - A two-element list consisting of the
-    argument name, followed by the default value, which will
-    be used if the corresponding argument is not supplied.
-
-+*args*+::
-    Variable Argument - The special name 'args', which is
-    assigned all remaining arguments (including none). The
-    variable argument may only be specified once.
-
-Arguments must be provided in the following order, any of which
-may be omitted:
-
-1. Required Arguments (Left)
-2. Optional Arguments
-3. Variable Argument
-4. Required Arguments (Right)
-
-When the command is invoked, a local variable will be created for each of
-the formal arguments to the procedure; its value will be the value
-of corresponding argument in the invoking command or the argument's
-default value.
-
-Arguments with default values need not be specified in a procedure
-invocation.  However, there must be enough actual arguments for all
-required arguments, and there must not be any extra actual arguments
-(unless the Variable Argument is specified).
-
-Actual arguments are assigned to formal arguments as follows:
-
-1. Left Required Arguments are assigned from the left
-2. Right Required Arguments are assigned from the right
-3. Default Arguments are assigned from the left, following the Left Required Arguments.
-4. A list is formed from any remaining arguments, which are then
-   are assigned to the 'args' Variable Argument (if specified). The list will be empty
-   if there are no remaining arguments.
-
-When *body* is being executed, variable names normally refer to local
-variables, which are created automatically when referenced and deleted
-when the procedure returns.  One local variable is automatically created
-for each of the procedure's arguments.  Global variables can be
-accessed by invoking the 'global' command or via the '::' prefix.
-
-*New in Jim*
-
-In addition to procedure arguments, Jim procedures may declare static variables.
-These variables scoped to the procedure and initialised at procedure definition.
-Either from the static variable definition, or from the enclosing scope.
-
-Consider the following example:
-
-    jim> set a 1
-    jim> proc a {} {a {b 2}} {
-        set c 1
-        puts "$a $b $c"
-        incr a
-        incr b
-        incr c
-    }
-    jim> a
-    1 2 1
-    jim> a
-    2 3 1
-
-The static variable *a* has no initialiser, so it is initialised from
-the enclosing scope with the value 1. (Note that it is an error if there
-is no variable with the same name in the enclosing scope). However *b*
-has an initialiser, so it is initialised to 2.
-
-Unlike a local variable, the value of a static variable is retained across
-invocations of the procedure.
-    
-See the 'proc' command for information on
-how to define procedures and what happens when they are invoked.
-
-VARIABLES - SCALARS AND ARRAYS
-------------------------------
-Tcl allows the definition of variables and the use of their values
-either through '$'-style variable substitution, the 'set'
-command, or a few other mechanisms.
-
-Variables need not be declared:  a new variable will automatically
-be created each time a new variable name is used.
-
-Tcl supports two types of variables:  scalars and arrays.
-A scalar variable has a single value, whereas an array variable
-can have any number of elements, each with a name (called
-its 'index') and a value.
-
-Array indexes may be arbitrary strings; they need not be numeric.
-Parentheses are used refer to array elements in Tcl commands.
-For example, the command
-
-    set x(first) 44
-
-will modify the element of 'x' whose index is 'first'
-so that its new value is '44'.
-
-Two-dimensional arrays can be simulated in Tcl by using indexes
-that contain multiple concatenated values.
-For example, the commands
-
-    set a(2,3) 1
-    set a(3,6) 2
-
-set the elements of 'a' whose indexes are '2,3' and '3,6'.
-
-In general, array elements may be used anywhere in Tcl that scalar
-variables may be used.
-
-If an array is defined with a particular name, then there may
-not be a scalar variable with the same name.
-
-Similarly, if there is a scalar variable with a particular
-name then it is not possible to make array references to the
-variable.
-
-To convert a scalar variable to an array or vice versa, remove
-the existing variable with the 'unset' command.
-
-The 'array' command provides several features for dealing
-with arrays, such as querying the names of all the elements of
-the array and converting between an array and a list.
-
-Variables may be either global or local.  If a variable
-name is used when a procedure isn't being executed, then it
-automatically refers to a global variable.  Variable names used
-within a procedure normally refer to local variables associated with that
-invocation of the procedure.  Local variables are deleted whenever
-a procedure exits.  Either 'global' command may be used to request
-that a name refer to a global variable for the duration of the current
-procedure (this is somewhat analogous to 'extern' in C), or the variable
-may be explicitly scoped with the '::' prefix. For example
-
-    set a 1
-    set b 2
-    proc p {} {
-        set c 3
-        global a
-
-        puts "$a $::b $c"
-    }
-    p
-
-will output:
-
-    1 2 3
-
-ARRAYS AS LISTS IN JIM
-----------------------
-Unlike Tcl, Jim can automatically convert between a list (with an even
-number of elements) and an array value. This is similar to the way Tcl
-can convert between a string and a list.
-
-For example:
-
-  set a {1 one 2 two}
-  puts $a(2)
-
-will output:
-
-  two
-
-Thus 'array set' is equivalent to 'set' when the variable does not
-exist or is empty.
-
-The reverse is also true where an array will be converted into
-a list.
-
-  set a(1) one; set a(2) two
-  puts $a
-
-will output:
-
-  1 one 2 two
-
-DICTIONARY VALUES
------------------
-Tcl 8.5 introduced the dict command, and Jim Tcl has added a version
-of this command. Dictionaries provide efficient access to key-value
-pairs, just like arrays, but dictionaries are pure values. This
-means that you can pass them to a procedure just as a list or a
-string. Tcl dictionaries are therefore much more like Tcl lists,
-except that they represent a mapping from keys to values, rather
-than an ordered sequence.
-
-You can nest dictionaries, so that the value for a particular key
-consists of another dictionary. That way you can elegantly build
-complicated data structures, such as hierarchical databases. You
-can also combine dictionaries with other Tcl data structures. For
-instance, you can build a list of dictionaries that themselves
-contain lists.
-
-Dictionaries are values that contain an efficient, order-preserving
-mapping from arbitrary keys to arbitrary values. Each key in the
-dictionary maps to a single value. They have a textual format that
-is exactly that of any list with an even number of elements, with
-each mapping in the dictionary being represented as two items in
-the list. When a command takes a dictionary and produces a new
-dictionary based on it (either returning it or writing it back into
-the variable that the starting dictionary was read from) the new
-dictionary will have the same order of keys, modulo any deleted
-keys and with new keys added on to the end. When a string is
-interpreted as a dictionary and it would otherwise have duplicate
-keys, only the last value for a particular key is used; the others
-are ignored, meaning that, "apple banana" and "apple carrot apple
-banana" are equivalent dictionaries (with different string
-representations).
-
-Note that in Jim, arrays are implemented as dictionaries.
-Thus automatic conversion between lists and dictionaries applies
-as it does for arrays.
-
-  jim> dict set a 1 one
-  1 one
-  jim> dict set a 2 two
-  1 one 2 two
-  jim> puts $a
-  1 one 2 two
-  jim> puts $a(2)
-  two
-  jim> dict set a 3 T three
-  1 one 2 two 3 {T three}
-
-See the 'dict' command for more details.
-
-GARBAGE COLLECTION, REFERENCES, LAMBDA
---------------------------------------
-Unlike Tcl, Jim has some sophistocated support for functional programming.
-These are described briefly below.
-
-More information may be found at http://wiki.tcl.tk/13847
-
-References
-~~~~~~~~~~
-A reference can be thought of as holding a value with one level of indirection,
-where the value may be garbage collected when unreferenced.
-Consider the following example:
-
-    jim> set r [ref "One String" test]
-    <reference.<test___>.00000000000000000000>
-    jim> getref $r
-    One String
-
-The operation 'ref' creates a references to the value specfied by the
-first argument. (The second argument is a "type" used for documentation purposes).
-
-The operation 'getref' is the dereferencing operation which retrieves the value
-stored in the reference.
-
-    jim> setref $r "New String"
-    New String
-    jim> getref $r
-    New String
-
-The operation 'setref' replaces the value stored by the reference. If the old value
-is no longer accessible by any reference, it will eventually be automatically be garbage
-collected.
-
-Garbage Collection
-~~~~~~~~~~~~~~~~~~
-Normally, all values in Tcl are passed by value. As such values are copied and released
-automatically as necessary.
-
-With the introduction of references, it is possible to create values whose lifetime
-transcend their scope. To support this, case, the Jim system will periodically identify
-and discard objects which are no longer accessible by any reference.
-
-The 'collect' command may be used to force garbage collection.  Consider a reference created
-with a finalizer:
-
-    jim> proc f {ref value} { puts "Finaliser called for $ref,$value" }
-    jim> set r [ref "One String" test f]
-    <reference.<test___>.00000000000
-    jim> collect
-    0
-    jim> set r ""
-    jim> collect
-    Finaliser called for <reference.<test___>.00000000000,One String
-    1
-
-Note that once the reference, 'r', was modified so that it no longer
-contained a reference to the value, the garbage collector discarded
-the value (after calling the finalizer).
-
-The finalizer for a reference may be examined or changed with the 'finalize' command
-
-    jim> finalize $r
-    f
-    jim> finalize $r newf
-    newf
-
-Lambda
-~~~~~~
-Jim provides a garbage collected lambda function. This is a procedure
-which is able to create an anonymous procedure.  Consider:
-
-    jim> set f [lambda {a} {{x 0}} { incr x $a }]
-    jim> $f 1
-    1
-    jim> $f 2
-    3
-    jim> set f ""
-
-This create an anonymous procedure (with the name stored in 'f'), with a static variable
-which is incremented by the supplied value and the result returned.
-
-Once the procedure name is no longer accessible, it will automatically be deleted
-when the garbage collector runs.
-
-The procedure may also be delete immediately by renaming it "". e.g.
-
-    jim> rename $f ""
-
-BUILT-IN COMMANDS
------------------
-The Tcl library provides the following built-in commands, which will
-be available in any application using Tcl.  In addition to these
-built-in commands, there may be additional commands defined by each
-application, plus commands defined as Tcl procedures.
-
-In the command syntax descriptions below, words in +*boldface*+ are
-literals that you type verbatim to Tcl.
-
-Words in +'italics'+ are meta-symbols; they serve as names for any of
-a range of values that you can type.
-
-Optional arguments or groups of arguments are indicated by enclosing them
-in +?question-marks?+.
-
-Ellipses (+...+) indicate that any number of additional
-arguments or groups of arguments may appear, in the same format
-as the preceding argument(s).
-
-[[CommandIndex]]
-Command Index
-~~~~~~~~~~~~~
-@INSERTINDEX@
-
-alarm
-~~~~~
-+*alarm* 'seconds'+
-
-Delivers the 'SIGALRM' signal to the process after the given
-number of seconds. If the platform supports 'ularm(3)' then
-the argument may be a floating point value. Otherwise it must
-be an integer.
-
-Note that unless a signal handler for 'SIGALRM' has been installed
-(see 'signal'), the process will exit on this signal.
-
-append
-~~~~~~
-+*append* 'varName value ?value value ...?'+
-
-Append all of the *value* arguments to the current value
-of variable *varName*.  If *varName* doesn't exist,
-it is given a value equal to the concatenation of all the
-*value* arguments.
-
-This command provides an efficient way to build up long
-variables incrementally.
-For example, 'append a $b' is much more efficient than
-'set a $a$b' if '$a' is long.
-
-array
-~~~~~
-+*array* 'option arrayName ?arg arg ...?'+
-
-This command performs one of several operations on the
-variable given by *arrayName*.
-
-Note that in general, if the named array does not exist, the *array* command behaves
-as though the array exists but is empty.
-
-The *option* argument determines what action is carried out by the
-command.  The legal *options* (which may be abbreviated) are:
-
-+*array exists* 'arrayName'+::
-    Returns 1 if arrayName is an array variable, 0 if there is
-    no variable by that name.  This command is essentially
-    identical to 'info exists'
-
-+*array get* 'arrayName ?pattern?'+::
-    Returns a list containing pairs of elements. The first
-    element in each pair is the name of an element in arrayName
-    and the second element of each pair is the value of the
-    array element. The order of the pairs is undefined. If
-    pattern is not specified, then all of the elements of the
-    array are included in the result. If pattern is specified,
-    then only those elements whose names match pattern (using
-    the matching rules of string match) are included. If arrayName
-    isn't the name of an array variable, or if the array contains
-    no elements, then an empty list is returned.
-
-+*array names* 'arrayName ?pattern?'+::
-    Returns a list containing the names of all of the elements
-    in the array that match pattern. If pattern is omitted then
-    the command returns all of the element names in the array.
-    If pattern is specified, then only those elements whose
-    names match pattern (using the matching rules of string
-    match) are included. If there are no (matching) elements
-    in the array, or if arrayName isn't the name of an array
-    variable, then an empty string is returned.
-
-+*array set* 'arrayName list'+::
-    Sets the values of one or more elements in arrayName. list
-    must have a form like that returned by array get, consisting
-    of an even number of elements. Each odd-numbered element
-    in list is treated as an element name within arrayName, and
-    the following element in list is used as a new value for
-    that array element. If the variable arrayName does not
-    already exist and list is empty, arrayName is created with
-    an empty array value.
-
-+*array size* 'arrayName'+::
-    Returns the number of elements in the array. If arrayName
-    isn't the name of an array then 0 is returned.
-
-+*array unset* 'arrayName ?pattern?'+::
-    Unsets all of the elements in the array that match pattern
-    (using the matching rules of string match). If arrayName
-    isn't the name of an array variable or there are no matching
-    elements in the array, no error will be raised. If pattern
-    is omitted and arrayName is an array variable, then the
-    command unsets the entire array. The command always returns
-    an empty string.
-
-break
-~~~~~
-+*break*+
-
-This command may be invoked only inside the body of a loop command
-such as 'for' or 'foreach' or 'while'.  It returns a +JIM_BREAK+ code
-to signal the innermost containing loop command to return immediately.
-
-case
-~~~~
-+*case* 'string' ?*in*? 'patList body ?patList body ...?'+
-
-+*case* 'string' ?*in*? {'patList body ?patList body ...?'}+
-
-*Note* that the switch command should generally be preferred unless compatibility
-with Tcl 6.x is desired.
-
-Match *string* against each of the *patList* arguments
-in order.  If one matches, then evaluate the following *body* argument
-by passing it recursively to the Tcl interpreter, and return the result
-of that evaluation.  Each *patList* argument consists of a single
-pattern or list of patterns.  Each pattern may contain any of the wild-cards
-described under 'string match'.
-
-If a *patList* argument is 'default', the corresponding body will be
-evaluated if no *patList* matches *string*.  If no *patList* argument
-matches *string* and no default is given, then the 'case' command returns
-an empty string.
-
-Two syntaxes are provided.
-
-The first uses a separate argument for each of the patterns and commands;
-this form is convenient if substitutions are desired on some of the
-patterns or commands.
-
-The second form places all of the patterns and commands together into
-a single argument; the argument must have proper list structure, with
-the elements of the list being the patterns and commands.
-
-The second form makes it easy to construct multi-line case commands,
-since the braces around the whole list make it unnecessary to include a
-backslash at the end of each line.
-
-Since the *patList* arguments are in braces in the second form,
-no command or variable substitutions are performed on them;  this makes
-the behavior of the second form different than the first form in some
-cases.
-
-Below are some examples of 'case' commands:
-
-    case abc in {a b} {format 1} default {format 2} a* {format 3}
-
-will return '3', 
-
-    case a in {
-        {a b} {format 1}
-        default {format 2}
-        a* {format 3}
-    }
-
-will return '1', and
-
-    case xyz {
-        {a b}
-            {format 1}
-        default
-            {format 2}
-        a*
-            {format 3}
-    }
-
-will return '2'.
-
-catch
-~~~~~
-+*catch* '?-?no?code ...?' *?--?* 'command ?resultVarName? ?optionsVarName?'+
-
-The 'catch' command may be used to prevent errors from aborting
-command interpretation.  'Catch' evalues *command*, and returns a
-+JIM_OK+ code, regardless of any errors that might occur while
-executing *command* (with the possible exception of +JIM_SIGNAL+ -
-see below).
-
-The return value from 'catch' is a decimal string giving the code
-returned by the Tcl interpreter after executing *command*.  This
-will be '0' (+JIM_OK+) if there were no errors in *command*; otherwise
-it will have a non-zero value corresponding to one of the exceptional
-return codes (see jim.h for the definitions of code values, or the
-'info returncodes' command).
-
-If the *resultVarName* argument is given, then it gives the name
-of a variable; 'catch' will set the value of the variable to the
-string returned from *command* (either a result or an error message).
-
-If the *optionsVarName* argument is given, then it gives the name
-of a variable; 'catch' will set the value of the variable to a
-dictionary. For any return code other than +JIM_RETURN+, the value
-for the key +-code+ will be set to the return code. For +JIM_RETURN+
-it will be set to the code given in 'return -code'. Additionally,
-for the return code +JIM_ERR+, the value of the key +-errorinfo+
-will contain the current stack trace (the same result as 'info
-stacktrace').  This can be useful to rethrow an error:
-
-    if {[catch {...} msg opts]} {
-        ...maybe do something with the error...
-        return {*}$opts $msg
-    }
-
-Normally 'catch' will *not* catch any of the codes +JIM_EXIT+, +JIM_EVAL+ or +JIM_SIGNAL+.
-The set of codes which will be caught may be modified by specifying the one more codes before
-*command*.
-
-e.g. To catch +JIM_EXIT+ but not +JIM_BREAK+ or +JIM_CONTINUE+
-
-    catch -exit -nobreak -nocontinue -- { ... }
-
-The use of +--+ is optional. It signifies that no more return code options follow.
-
-Note that if a signal marked as 'signal handle' is caught with 'catch -signal', the return value
-(stored in *resultVarName*) is name of the signal caught.
-
-cd
-~~
-+*cd* 'dirName'+
-
-Change the current working directory to *dirName*.
-
-Returns an empty string.
-
-This command can potentially be disruptive to an application, so it may
-be removed in some applications.
-
-clock
-~~~~~
-+*clock seconds*+::
-    Returns the current time as seconds since the epoch.
-
-+*clock format* 'seconds' ?*-format* 'format?'+::
-    Format the given time (seconds since the epoch) according to the given
-    format. See strftime(3) for supported formats.
-    If no format is supplied, "%c" is used.
-
-+*clock scan* 'str' *-format* 'format'+::
-    Scan the given time string using the given format string.
-    See strptime(3) for supported formats.
-
-close
-~~~~~
-+*close* 'fileId'+
-
-+'fileId' *close*+
-
-Closes the file given by *fileId*.
-*fileId* must be the return value from a previous invocation
-of the 'open' command; after this command, it should not be
-used anymore.
-
-collect
-~~~~~~~
-+*collect*+
-
-Normally reference garbage collection is automatically performed periodically.
-However it may be run immediately with the 'collect' command.
-
-See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
-
-concat
-~~~~~~
-+*concat* 'arg ?arg ...?'+
-
-This command treats each argument as a list and concatenates them
-into a single list.  It permits any number of arguments.  For example,
-the command
-
-    concat a b {c d e} {f {g h}}
-
-will return
-
-    a b c d e f {g h}
-
-as its result.
-
-continue
-~~~~~~~~
-+*continue*+
-
-This command may be invoked only inside the body of a loop command such
-as 'for' or 'foreach' or 'while'.  It returns a  +JIM_CONTINUE+ code to
-signal the innermost containing loop command to skip the remainder of
-the loop's body but continue with the next iteration of the loop.
-
-dict
-~~~~
-+*dict* 'option ?arg arg ...?'+
-
-Performs one of several operations on dictionary values.
-
-The *option* argument determines what action is carried out by the
-command.  The legal *options* are:
-
-*dict create* '?key value ...?'+::
-    Create and return a new dictionary value that contains each of
-    the key/value mappings listed as  arguments (keys and values
-    alternating, with each key being followed by its associated
-    value.)
-
-*dict exists* 'dictionary key ?key ...?'+::
-    Returns a boolean value indicating whether the given key (or path
-    of keys through a set of nested dictionaries) exists in the given
-    dictionary value.  This returns a true value exactly when 'dict get'
-    on that path will succeed.
-
-*dict get* 'dictionary ?key ...?'+::
-    Given a dictionary value (first argument) and a key (second argument),
-    this will retrieve the value for that key. Where several keys are
-    supplied, the behaviour of the command shall be as if the result
-    of 'dict get $dictVal $key' was passed as the first argument to
-    dict get with the remaining arguments as second (and possibly
-    subsequent) arguments. This facilitates lookups in nested dictionaries.
-    If no keys are provided, dict would return a list containing pairs
-    of elements in a man- ner similar to array get. That is, the first
-    element of each pair would be the key and the second element would
-    be the value for that key.  It is an error to attempt to retrieve
-    a value for a key that is not present in the dictionary.
-
-*dict set* 'dictionaryName key ?key ...? value'+::
-    This operation takes the *name* of a variable containing a dictionary
-    value and places an updated dictionary value in that variable
-    containing a mapping from the given key to the given value. When
-    multiple keys are present, this operation creates or updates a chain
-    of nested dictionaries.
-
-*dict unset* 'dictionaryName key ?key ...? value'+::
-    This operation (the companion to 'dict set') takes the name of a
-    variable containing a dictionary value and places an updated
-    dictionary value in that variable that does not contain a mapping
-    for the given key. Where multiple keys are present, this describes
-    a path through nested dictionaries to the mapping to remove. At
-    least one key must be specified, but the last key on the key-path
-    need not exist. All other components on the path must exist.
-
-env
-~~~
-+*env* '?name? ?default?'+
-
-If *name* is supplied, returns the value of *name* from the initial
-environment (see getenv(3)). An error is returned if *name* does not
-exist in the environment, unless *default* is supplied - in which case
-that value is returned instead.
-
-If no arguments are supplied, returns a list of all environment variables
-and their values as +{name value ...}+
-
-See also the global variable '::env'
-
-eof
-~~~
-+*eof* 'fileId'+
-
-+'fileId' *eof*+
-
-Returns 1 if an end-of-file condition has occurred on *fileId*,
-0 otherwise.
-
-*fileId* must have been the return value from a previous call to 'open',
-or it may be 'stdin', 'stdout', or 'stderr' to refer to one of the
-standard I/O channels.
-
-error
-~~~~~
-+*error* 'message ?stacktrace?'+
-
-Returns a +JIM_ERR+ code, which causes command interpretation to be
-unwound.  *message* is a string that is returned to the application
-to indicate what went wrong.
-
-If the *stacktrace* argument is provided and is non-empty,
-it is used to initialize the stacktrace.
-
-This feature is most useful in conjunction with the 'catch' command:
-if a caught error cannot be handled successfully, *stacktrace* can be used
-to return a stack trace reflecting the original point of occurrence
-of the error:
-
-    catch {...} errMsg
-    ...
-    error $errMsg [info stacktrace]
-
-See also 'errorInfo', 'info stacktrace', 'catch' and 'return'
-
-errorInfo
-~~~~~~~~~
-+*errorInfo* 'error ?stacktrace?'+
-
-Returns a human-readable representation of the given error message and stack trace.
-Typical usage is:
-
-    if {[catch {...} error]} {
-        puts stderr [errorInfo $error [info stacktrace]]
-        exit 1
-    }
-
-See also 'error'.
-
-eval
-~~~~
-+*eval* 'arg ?arg ...?'+
-
-'eval' takes one or more arguments, which together comprise a Tcl
-command (or collection of Tcl commands separated by newlines in the
-usual way).  'eval' concatenates all its arguments in the same
-fashion as the 'concat' command, passes the concatenated string to the
-Tcl interpreter recursively, and returns the result of that
-evaluation (or any error generated by it).
-
-exec
-~~~~
-+*exec* 'arg ?arg ...?'+
-
-This command treats its arguments as the specification
-of one or more UNIX commands to execute as subprocesses.
-The commands take the form of a standard shell pipeline;
-'|' arguments separate commands in the
-pipeline and cause standard output of the preceding command
-to be piped into standard input of the next command (or '|&' for
-both standard output and standard error).
-
-Under normal conditions the result of the 'exec' command
-consists of the standard output produced by the last command
-in the pipeline.
-
-If any of the commands in the pipeline exit abnormally or
-are killed or suspended, then 'exec' will return an error
-and the error message will include the pipeline's output followed by
-error messages describing the abnormal terminations.
-
-If any of the commands writes to its standard error file,
-then 'exec' will return an error, and the error message
-will include the pipeline's output, followed by messages
-about abnormal terminations (if any), followed by the standard error
-output.
-
-If the last character of the result or error message
-is a newline then that character is deleted from the result
-or error message for consistency with normal
-Tcl return values.
-
-An *arg* may have one of the following special forms:
-
-+>filename+::
-    The standard output of the last command in the pipeline
-    is redirected to the file.  In this situation 'exec'
-    will normally return an empty string.
-
-+>>filename+::
-    As above, but append to the file.
-
-+>@fileId+::
-    The standard output of the last command in the pipeline is
-    redirected to the given (writable) file descriptor (e.g. stdout,
-    stderr, or the result of 'open'). In this situation 'exec'
-    will normally return an empty string.
-
-+2>filename+::
-    The standard error of the last command in the pipeline
-    is redirected to the file.
-
-+2>>filename+::
-    As above, but append to the file.
-
-+2>@fileId+::
-    The standard error of the last command in the pipeline is
-    redirected to the given (writable) file descriptor.
-
-+2>@1+::
-    The standard error of the last command in the pipeline is
-    redirected to the same file descriptor as the standard output.
-
-+>&filename+::
-    Both the standard output and standard error of the last command
-    in the pipeline is redirected to the file.
-
-+>>&filename+::
-    As above, but append to the file.
-
-+<filename+::
-    The standard input of the first command in the pipeline
-    is taken from the file.
-
-+<<string+::
-    The standard input of the first command is taken as the
-    given immediate value.
-
-+<@fileId+::
-    The standard input of the first command in the pipeline
-    is taken from the given (readable) file descriptor.
-
-If there is no redirection of standard input, standard error
-or standard output, these are connected to the corresponding
-input or output of the application.
-
-If the last *arg* is '&' then the command will be
-executed in background.
-In this case the standard output from the last command
-in the pipeline will
-go to the application's standard output unless
-redirected in the command, and error output from all
-the commands in the pipeline will go to the application's
-standard error file. The return value of exec in this case
-is a list of process ids (pids) in the pipeline.
-
-Each *arg* becomes one word for a command, except for
-'|', '<', '<<', '>', and '&' arguments, and the
-arguments that follow '<', '<<', and '>'.
-
-The first word in each command is taken as the command name;
-the directories in the PATH environment variable are searched for
-an executable by the given name.
-
-No 'glob' expansion or other shell-like substitutions
-are performed on the arguments to commands.
-
-exit
-~~~~
-+*exit* '?returnCode?'+
-
-Terminate the process, returning *returnCode* to the
-parent as the exit status.
-
-If *returnCode* isn't specified then it defaults
-to 0.
-
-Note that exit can be caught with *catch*.
-
-expr
-~~~~
-+*expr* 'arg'+
-
-Calls the expression processor to evaluate *arg*, and returns
-the result as a string.  See the section EXPRESSIONS above.
-
-file
-~~~~
-+*file* 'option name ?arg arg ...?'+
-
-Operate on a file or a file name.  *name* is the name of a file.
-
-*Option* indicates what to do with the file name.  Any unique
-abbreviation for *option* is acceptable.  The valid options are:
-
-+*file atime* 'name'+::
-    Return a decimal string giving the time at which file *name*
-    was last accessed.  The time is measured in the standard UNIX
-    fashion as seconds from a fixed starting time (often January 1, 1970).
-    If the file doesn't exist or its access time cannot be queried then an
-    error is generated.
-
-+*file copy ?-force?* 'source target'+::
-    Copies file *source* to file *target*. The source file must exist.
-    The target file must not exist, unless *-force* is specified.
-
-+*file delete* 'name ...'+::
-    Deletes file or directory *name*. If the file or directory doesn't exist, nothing happens.
-    If it can't be deleted, an error is generated. Non-empty directories will not be deleted.
-
-+*file dirname* 'name'+::
-    Return all of the characters in *name* up to but not including
-    the last slash character.  If there are no slashes in *name*
-    then return '.' (a single dot).  If the last slash in *name* is its first
-    character, then return '/'.
-
-+*file executable* 'name'+::
-    Return '1' if file *name* is executable by
-    the current user, '0' otherwise.
-
-+*file exists* 'name'+::
-    Return '1' if file *name* exists and the current user has
-    search privileges for the directories leading to it, '0' otherwise.
-
-+*file extension* 'name'+::
-    Return all of the characters in *name* after and including the
-    last dot in *name*.  If there is no dot in *name* then return
-    the empty string.
-
-+*file isdirectory* 'name'+::
-    Return '1' if file *name* is a directory,
-    '0' otherwise.
-
-+*file isfile* 'name'+::
-    Return '1' if file *name* is a regular file,
-    '0' otherwise.
-
-+*file join* 'arg arg ...'+::
-    Joins multiple path components. Note that if any components is
-    an absolute path, the preceding components are ignored.
-    Thus 'file join /tmp /root' returns '/root'.
-
-+*file lstat* 'name varName'+::
-    Same as 'stat' option (see below) except uses the *lstat*
-    kernel call instead of *stat*.  This means that if *name*
-    refers to a symbolic link the information returned in *varName*
-    is for the link rather than the file it refers to.  On systems that
-    don't support symbolic links this option behaves exactly the same
-    as the 'stat' option.
-
-+*file mkdir* 'dir1 ?dir2? ...'+::
-	Creates each directory specified. For each pathname *dir* specified,
-	this command will create all non-existing parent directories
-	as well as *dir* itself. If an existing directory is specified,
-	then no action is taken and no error is returned. Trying to
-	overwrite an existing file with a directory will result in an
-	error.  Arguments are processed in the order specified, halting
-	at the first error, if any.
-
-+*file mtime* 'name'+::
-    Return a decimal string giving the time at which file *name*
-    was last modified.  The time is measured in the standard UNIX
-    fashion as seconds from a fixed starting time (often January 1, 1970).
-    If the file doesn't exist or its modified time cannot be queried then an
-    error is generated.
-
-+*file normalize* 'name'+::
-    Return the normalized path of *name*. See realpath(3).
-
-+*file owned* 'name'+::
-    Return '1' if file *name* is owned by the current user,
-    '0' otherwise.
-
-+*file readable* 'name'+::
-    Return '1' if file *name* is readable by
-    the current user, '0' otherwise.
-
-+*file readlink* 'name'+::
-    Returns the value of the symbolic link given by *name* (i.e. the
-    name of the file it points to).  If
-    *name* isn't a symbolic link or its value cannot be read, then
-    an error is returned.  On systems that don't support symbolic links
-    this option is undefined.
-
-+*file rename* 'oldname' 'newname'+::
-    Renames the file from the old name to the new name.
-
-+*file rootname* 'name'+::
-    Return all of the characters in *name* up to but not including
-    the last '.' character in the name.  If *name* doesn't contain
-    a dot, then return *name*.
-
-+*file size* 'name'+::
-    Return a decimal string giving the size of file *name* in bytes.
-    If the file doesn't exist or its size cannot be queried then an
-    error is generated.
-
-+*file stat* 'name varName'+::
-    Invoke the 'stat' kernel call on *name*, and use the
-    variable given by *varName* to hold information returned from
-    the kernel call.
-    *VarName* is treated as an array variable,
-    and the following elements of that variable are set: 'atime',
-    'ctime', 'dev', 'gid', 'ino', 'mode', 'mtime',
-    'nlink', 'size', 'type', 'uid'.
-    Each element except 'type' is a decimal string with the value of
-    the corresponding field from the 'stat' return structure; see the
-    manual entry for 'stat' for details on the meanings of the values.
-    The 'type' element gives the type of the file in the same form
-    returned by the command 'file type'.
-    This command returns an empty string.
-
-+*file tail* 'name'+::
-    Return all of the characters in *name* after the last slash.
-    If *name* contains no slashes then return *name*.
-
-+*file tempfile* '?template?'+::
-    Creates and returns the name of a unique temporary file. If *template* is omitted, a
-    default template will be used to place the file in /tmp. See mkstemp(3) for
-    the format of the template and security concerns.
-
-+*file type* 'name'+::
-    Returns a string giving the type of file *name*, which will be
-    one of 'file', 'directory', 'characterSpecial',
-    'blockSpecial', 'fifo', 'link', or 'socket'.
-
-+*file writable* 'name'+::
-    Return '1' if file *name* is writable by
-    the current user, '0' otherwise.
-
-The 'file' commands that return 0/1 results are often used in
-conditional or looping commands, for example:
-
-    if {![file exists foo]} then {error {bad file name}} else {...}
-
-finalize
-~~~~~~~~
-+*finalize* 'reference ?command?'+
-
-If *command* is omitted, returns the finalizer command for the given reference.
-
-Otherwise, sets a new finalizer command for the given reference. *command* may be
-the empty string to remove the current finalizer.
-
-The reference must be a valid reference create with the 'ref'
-command.
-
-See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
-
-flush
-~~~~~
-+*flush* 'fileId'+
-
-+'fileId' *flush*+
-
-Flushes any output that has been buffered for *fileId*.  *fileId* must
-have been the return value from a previous call to 'open', or it may be
-'stdout' or 'stderr' to access one of the standard I/O streams; it must
-refer to a file that was opened for writing.  This command returns an
-empty string.
-
-for
-~~~
-+*for* 'start test next body'+
-
-'For' is a looping command, similar in structure to the C 'for' statement.
-The *start*, *next*, and *body* arguments must be Tcl command strings,
-and *test* is an expression string.
-
-The 'for' command first invokes the Tcl interpreter to execute *start*.
-Then it repeatedly evaluates *test* as an expression; if the result is
-non-zero it invokes the Tcl interpreter on *body*, then invokes the Tcl
-interpreter on *next*, then repeats the loop.  The command terminates
-when *test* evaluates to 0.
-
-If a 'continue' command is invoked within *body* then any remaining
-commands in the current execution of *body* are skipped; processing
-continues by invoking the Tcl interpreter on *next*, then evaluating
-*test*, and so on.
-
-If a 'break' command is invoked within *body* or *next*, then the 'for'
-command will return immediately.
-
-The operation of 'break' and 'continue' are similar to the corresponding
-statements in C.
-
-'For' returns an empty string.
-
-foreach
-~~~~~~~
-+*foreach* 'varName list body'+
-
-+*foreach* 'varList list ?varList2 list2 ...? body'+
-
-In this command, *varName* is the name of a variable, *list*
-is a list of values to assign to *varName*, and *body* is a
-collection of Tcl commands. 
-
-For each field in *list* (in order from left to right),'foreach' assigns
-the contents of the field to *varName* (as if the 'lindex' command
-had been used to extract the field), then calls the Tcl interpreter to
-execute *body*.
-
-If instead of being a simple name, *varList* is used, multiple assignments
-are made each time through the loop, one for each element of *varList*.
-
-For example, if there are two elements in *varList* and six elements in
-the list, the loop will be executed three times.
-
-If the length of the list doesn't evenly divide by the number of elements
-in *varList*, the value of the remaining variables in the last iteration
-of the loop are undefined.
-
-The 'break' and 'continue' statements may be invoked inside *body*,
-with the same effect as in the 'for' command.
-
-'foreach' returns an empty string.
-
-format
-~~~~~~
-+*format* 'formatString ?arg arg ...?'+
-
-This command generates a formatted string in the same way as the
-C 'sprintf' procedure (it uses 'sprintf' in its
-implementation).  *FormatString* indicates how to format
-the result, using '%' fields as in 'sprintf', and the additional
-arguments, if any, provide values to be substituted into the result.
-
-All of the 'sprintf' options are valid; see the 'sprintf'
-man page for details.  Each *arg* must match the expected type
-from the '%' field in *formatString*; the 'format' command
-converts each argument to the correct type (floating, integer, etc.)
-before passing it to 'sprintf' for formatting.
-
-The only unusual conversion is for '%c'; in this case the argument
-must be a decimal string, which will then be converted to the corresponding
-ASCII character value.
-
-'Format' does backslash substitution on its *formatString*
-argument, so backslash sequences in *formatString* will be handled
-correctly even if the argument is in braces.
-
-The return value from 'format' is the formatted string.
-
-getref
-~~~~~~
-+*getref* 'reference'+
-
-Returns the string associated with *reference*. The reference must
-be a valid reference create with the 'ref' command.
-
-See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
-
-gets
-~~~~
-+*gets* 'fileId ?varName?'+
-
-+'fileId' *gets* '?varName?'+
-
-Reads the next line from the file given by *fileId* and discards
-the terminating newline character.
-
-If *varName* is specified, then the line is placed in the variable
-by that name and the return value is a count of the number of characters
-read (not including the newline).
-
-If the end of the file is reached before reading
-any characters then -1 is returned and *varName* is set to an
-empty string.
-
-If *varName* is not specified then the return value will be
-the line (minus the newline character) or an empty string if
-the end of the file is reached before reading any characters.
-
-An empty string will also be returned if a line contains no characters
-except the newline, so 'eof' may have to be used to determine
-what really happened.
-
-If the last character in the file is not a newline character, then
-'gets' behaves as if there were an additional newline character
-at the end of the file.
-
-*fileId* must be 'stdin' or the return value from a previous
-call to 'open'; it must refer to a file that was opened
-for reading.
-
-glob
-~~~~
-+*glob* ?*-nocomplain*? 'pattern ?pattern ...?'+
-
-This command performs filename globbing, using csh rules.  The returned
-value from 'glob' is the list of expanded filenames.
-
-If '-nocomplain' is specified as the first argument then an empty
-list may be returned;  otherwise an error is returned if the expanded
-list is empty.  The '-nocomplain' argument must be provided
-exactly: an abbreviation will not be accepted.
-
-global
-~~~~~~
-
-+*global* 'varName ?varName ...?'+
-
-This command is ignored unless a Tcl procedure is being interpreted.
-If so, then it declares each given *varName* to be a global variable
-rather than a local one.  For the duration of the current procedure
-(and only while executing in the current procedure), any reference to
-*varName* will be bound to a global variable instead
-of a local one.
-
-An alternative to using 'global' is to use the '::' prefix
-to explicitly name a variable in the global scope.
-
-if
-~~
-+*if* 'expr1' ?*then*? 'body1' *elseif* 'expr2' ?*then*? 'body2' *elseif* ... ?*else*? ?'bodyN'?+
-
-The 'if' command evaluates *expr1* as an expression (in the same way
-that 'expr' evaluates its argument).  The value of the expression must
-be numeric; if it is non-zero then *body1* is executed by passing it to
-the Tcl interpreter.
-
-Otherwise *expr2* is evaluated as an expression and if it is non-zero
-then *body2* is executed, and so on.
-
-If none of the expressions evaluates to non-zero then *bodyN* is executed.
-
-The 'then' and 'else' arguments are optional 'noise words' to make the
-command easier to read.
-
-There may be any number of 'elseif' clauses, including zero.  *bodyN*
-may also be omitted as long as 'else' is omitted too.
-
-The return value from the command is the result of the body script that
-was executed, or an empty string if none of the expressions was non-zero
-and there was no *bodyN*.
-
-incr
-~~~~
-+*incr* 'varName ?increment?'+
-
-Increment the value stored in the variable whose name is *varName*.
-The value of the variable must be integral.
-
-If *increment* is supplied then its value (which must be an
-integer) is added to the value of variable *varName*;  otherwise
-1 is added to *varName*.
-
-The new value is stored as a decimal string in variable *varName*
-and also returned as result.
-
-If the variable does not exist, the variable is implicitly created
-and set to +0+ first.
-
-info
-~~~~
-
-+*info* 'option ?arg arg ...?'+::
-
-Provide information about various internals to the Tcl interpreter.
-The legal *option*'s (which may be abbreviated) are:
-
-+*info args* 'procname'+::
-    Returns a list containing the names of the arguments to procedure
-    *procname*, in order.  *Procname* must be the name of a
-    Tcl command procedure.
-
-+*info body* 'procname'+::
-    Returns the body of procedure *procname*.  *Procname* must be
-    the name of a Tcl command procedure.
-
-+*info commands* ?'pattern'?+::
-    If *pattern* isn't specified, returns a list of names of all the
-    Tcl commands, including both the built-in commands written in C and
-    the command procedures defined using the 'proc' command.
-    If *pattern* is specified, only those names matching *pattern*
-    are returned.  Matching is determined using the same rules as for
-    'string match'.
-
-+*info complete* 'command'+::
-    Returns 1 if *command* is a complete Tcl command in the sense of
-    having no unclosed quotes, braces, brackets or array element names,
-    If the command doesn't appear to be complete then 0 is returned.
-    This command is typically used in line-oriented input environments
-    to allow users to type in commands that span multiple lines;  if the
-    command isn't complete, the script can delay evaluating it until additional
-    lines have been typed to complete the command.
-
-+*info exists* 'varName'+::
-    Returns '1' if the variable named *varName* exists in the
-    current context (either as a global or local variable), returns '0'
-    otherwise.
-
-+*info globals* ?'pattern'?+::
-    If *pattern* isn't specified, returns a list of all the names
-    of currently-defined global variables.
-    If *pattern* is specified, only those names matching *pattern*
-    are returned.  Matching is determined using the same rules as for
-    'string match'.
-
-+*info hostname*+::
-    An alias for 'os.gethostname' for compatibility with Tcl 6.x
-
-+*info level* ?'number'?+::
-    If *number* is not specified, this command returns a number
-    giving the stack level of the invoking procedure, or 0 if the
-    command is invoked at top-level.  If *number* is specified,
-    then the result is a list consisting of the name and arguments for the
-    procedure call at level *number* on the stack.  If *number*
-    is positive then it selects a particular stack level (1 refers
-    to the top-most active procedure, 2 to the procedure it called, and
-    so on); otherwise it gives a level relative to the current level
-    (0 refers to the current procedure, -1 to its caller, and so on).
-    See the 'uplevel' command for more information on what stack
-    levels mean.
-
-+*info locals* ?'pattern'?+::
-    If *pattern* isn't specified, returns a list of all the names
-    of currently-defined local variables, including arguments to the
-    current procedure, if any.  Variables defined with the 'global'
-    and 'upvar' commands will not be returned.  If *pattern* is
-    specified, only those names matching *pattern* are returned.
-    Matching is determined using the same rules as for 'string match'.
-
-+*info nameofexecutable*+::
-    Returns the name of the binary file from which the application
-    was invoked, either
-    as a path relative to the current directory or as a full
-    path. If the path can't be determined, returns the empty
-    string.
-
-+*info procs* ?'pattern'?+::
-    If *pattern* isn't specified, returns a list of all the
-    names of Tcl command procedures.
-    If *pattern* is specified, only those names matching *pattern*
-    are returned.  Matching is determined using the same rules as for
-    'string match'.
-
-+*info returncodes* ?'code'?+::
-    Returns a list representing the mapping of standard return codes
-    to names. e.g. +{0 ok 1 error 2 return ...}+. If a code is given,
-    instead returns the name for the given code.
-
-+*info script*+::
-    If a Tcl script file is currently being evaluated (i.e. there is a
-    call to 'Jim_EvalFile' active or there is an active invocation
-    of the 'source' command), then this command returns the name
-    of the innermost file being processed.  Otherwise the command returns an
-    empty string.
-
-+*info source* 'script'+::
-    Returns the original source location of the given script as a list of
-    +{filename linenumber}+. If the source location can't be determined, the
-    list +{{} 0}+ is returned.
-
-+*info stacktrace*+::
-    After an error is caught with 'catch', returns the stack trace as a list
-    of +{procedure filename line ...}+.
-
-+*info version*+::
-    Returns the version number for this version of Jim in the form *x.yy*.
-
-+*info vars* ?'pattern'?+::
-    If *pattern* isn't specified,
-    returns a list of all the names of currently-visible variables, including
-    both locals and currently-visible globals.
-    If *pattern* is specified, only those names matching *pattern*
-    are returned.  Matching is determined using the same rules as for
-    'string match'.
-
-join
-~~~~
-+*join* 'list ?joinString?'+
-
-The *list* argument must be a valid Tcl list.  This command returns the
-string formed by joining all of the elements of *list* together with
-*joinString* separating each adjacent pair of elements.
-
-The *joinString* argument defaults to a space character.
-
-kill
-~~~~
-+*kill* ?'SIG'|*-0*? 'pid'+
-
-Sends the given signal to the process identified by *pid*.
-
-The signal may be specified by name or number in one of the following forms:
-
-* +TERM+
-* +SIGTERM+
-* +-TERM+
-* +15+
-* +-15+
-
-The signal name may be in either upper or lower case.
-
-The special signal name '-0' simply checks that a signal *could* be sent.
-
-If no signal is specified, SIGTERM is used.
-
-An error is raised if the signal could not be delivered.
-
-lambda
-~~~~~~
-+*lambda* 'args ?statics? body'+
-
-The 'lambda' command is identical to 'proc', except rather than
-creating a named procedure, it creates an anonymous procedure and returns
-the name of the procedure.
-
-See 'proc' and GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
-
-lappend
-~~~~~~~
-+*lappend* 'varName value ?value value ...?'+
-
-Treat the variable given by *varName* as a list and append each of
-the *value* arguments to that list as a separate element, with spaces
-between elements.
-
-If *varName* doesn't exist, it is created as a list with elements given
-by the *value* arguments. 'lappend' is similar to 'append' except that
-each *value* is appended as a list element rather than raw text.
-
-This command provides a relatively efficient way to build up large lists.
-For example, 'lappend a $b' is much more efficient than
-
-    set a [concat $a [list $b]]
-    
-when '$a' is long.
-
-lassign
-~~~~~~~
-+*lassign* 'list varName ?varName? ...'+
-
-This command treats the value *list* as a list and assigns successive elements from that list to
-the variables given by the *varName* arguments in order. If there are more variable names than
-list elements, the remaining variables are set to the empty string. If there are more list ele-
-ments than variables, a list of unassigned elements is returned.
-
-    jim> lassign {1 2 3} a b; puts a=$a,b=$b
-    3
-    a=1,b=2
-
-lindex
-~~~~~~
-+*lindex* 'list index'+
-
-Treats *list* as a Tcl list and returns element *index* from it
-(0 refers to the first element of the list).
-See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *index*.
-
-In extracting the element, *lindex* observes the same rules concerning
-braces and quotes and backslashes as the Tcl command interpreter; however,
-variable substitution and command substitution do not occur.
-
-If *index* is negative or greater than or equal to the number of elements
-in *value*, then an empty string is returned.
-
-linsert
-~~~~~~~
-+*linsert* 'list index element ?element element ...?'+
-
-This command produces a new list from *list* by inserting all
-of the *element* arguments just before the element *index*
-of *list*. Each *element* argument will become
-a separate element of the new list. If *index* is less than
-or equal to zero, then the new elements are inserted at the
-beginning of the list. If *index* is greater than or equal
-to the number of elements in the list, then the new elements are
-appended to the list.
-
-See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *index*.
-
-list
-~~~~
-
-+*list* 'arg ?arg ...?'+
-
-This command returns a list comprised of all the arguments, *arg*. Braces
-and backslashes get added as necessary, so that the 'index' command
-may be used on the result to re-extract the original arguments, and also
-so that 'eval' may be used to execute the resulting list, with
-*arg1* comprising the command's name and the other args comprising
-its arguments. 'List' produces slightly different results than
-'concat':  'concat' removes one level of grouping before forming
-the list, while 'list' works directly from the original arguments.
-For example, the command
-
-    list a b {c d e} {f {g h}}
-
-will return
-
-    a b {c d e} {f {g h}}
-
-while 'concat' with the same arguments will return
-
-    a b c d e f {g h}
-
-llength
-~~~~~~~
-+*llength* 'list'+
-
-Treats *list* as a list and returns a decimal string giving
-the number of elements in it.
-
-lset
-~~~~
-+*lset* 'varName ?index ..? newValue'+
-
-Sets an element in a list.
-
-The 'lset' command accepts a parameter, *varName*, which it interprets
-as the name of a variable containing a Tcl list. It also accepts
-zero or more indices into the list. Finally, it accepts a new value
-for an element of varName. If no indices are presented, the command
-takes the form:
-
-    lset varName newValue
-
-In this case, newValue replaces the old value of the variable
-varName.
-
-When presented with a single index, the 'lset' command
-treats the content of the varName variable as a Tcl list. It addresses
-the index'th element in it (0 refers to the first element of the
-list). When interpreting the list, 'lset' observes the same rules
-concerning braces and quotes and backslashes as the Tcl command
-interpreter; however, variable substitution and command substitution
-do not occur. The command constructs a new list in which the
-designated element is replaced with newValue. This new list is
-stored in the variable varName, and is also the return value from
-the 'lset' command.
-
-If index is negative or greater than or equal to the number of
-elements in $varName, then an error occurs.
-
-See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *index*.
-
-If additional index arguments are supplied, then each argument is
-used in turn to address an element within a sublist designated by
-the previous indexing operation, allowing the script to alter
-elements in sublists. The command,
-
-    lset a 1 2 newValue
-
-replaces element 2 of sublist 1 with *newValue*.
-
-The integer appearing in each index argument must be greater than
-or equal to zero. The integer appearing in each index argument must
-be strictly less than the length of the corresponding list. In other
-words, the 'lset' command cannot change the size of a list. If an
-index is outside the permitted range, an error is reported.
-
-lmap
-~~~~
-
-+*lmap* 'varName list body'+
-
-+*lmap* 'varList list ?varList2 list2 ...? body'+
-
-'lmap' is a "collecting 'foreach'" which returns a list of its results.
-
-For example:
-
-    jim> lmap i {1 2 3 4 5} {expr $i*$i}
-    1 4 9 16 25
-    jim> lmap a {1 2 3} b {A B C} {list $a $b}
-    {1 A} {2 B} {3 C}
-
-If the body invokes 'continue', no value is added for this iteration.
-If the body invokes 'break', the loop ends and no more values are added.
-
-lrange
-~~~~~~
-+*lrange* 'list first last'+
-
-*List* must be a valid Tcl list. This command will return a new
-list consisting of elements *first* through *last*, inclusive.
-
-See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*.
-
-If *last* is greater than or equal to the number of elements
-in the list, then it is treated as if it were 'end'.
-
-If *first* is greater than *last* then an empty string
-is returned.
-
-Note: 'lrange *list first first*' does not always produce the
-same result as 'lindex *list first*' (although it often does
-for simple fields that aren't enclosed in braces); it does, however,
-produce exactly the same results as 'list [lindex *list first*]'
-
-lreplace
-~~~~~~~~
-
-+*lreplace* 'list first last ?element element ...?'+
-
-Returns a new list formed by replacing one or more elements of
-*list* with the *element* arguments.
-
-*First* gives the index in *list* of the first element
-to be replaced.
-
-If *first* is less than zero then it refers to the first
-element of *list*;  the element indicated by *first*
-must exist in the list.
-
-*Last* gives the index in *list* of the last element
-to be replaced;  it must be greater than or equal to *first*.
-
-See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*.
-
-The *element* arguments specify zero or more new arguments to
-be added to the list in place of those that were deleted.
-
-Each *element* argument will become a separate element of
-the list.
-
-If no *element* arguments are specified, then the elements
-between *first* and *last* are simply deleted.
-
-lrepeat
-~~~~~~~~
-+*lrepeat* 'number element1 ?element2 ...?'+
-
-Build a list by repeating elements *number* times (which must be
-a positive integer).
-
-    jim> lrepeat 3 a b
-    a b a b a b
-
-lreverse
-~~~~~~~~
-+*lreverse* 'list'+
-
-Returns the list in reverse order.
-
-    jim> lreverse {1 2 3}
-    3 2 1
-
-lsearch
-~~~~~~~
-+*lsearch* '?options? list pattern'+
-
-This command searches the elements *list* to see if one of them matches *pattern*. If so, the
-command returns the index of the first matching element (unless the options -all, -inline or -bool are
-specified.) If not, the command returns -1. The option arguments indicates how the elements of
-the list are to be matched against pattern and must have one of the values below:
-
-*Note* that this command is different from Tcl in that default match type is '-exact' rather than '-glob'.
-
-+'-exact'+::
-    *pattern* is a literal string that is compared for exact equality against each list element.
-    This is the default.
-
-+'-glob'+::
-    *pattern* is a glob-style pattern which is matched against each list element using the same
-    rules as the string match command.
-
-+'-regexp'+::
-    *pattern* is treated as a regular expression and matched against each list element using
-    the rules described by 'regexp'.
-
-+'-all'+::
-    Changes the result to be the list of all matching indices (or all matching values if
-    '-inline' is specified as well). If indices are returned, the indices will be in numeric
-    order. If values are returned, the order of the values will be the order of those values
-    within the input list.
-
-+'-inline'+::
-    The matching value is returned instead of its index (or an empty string if no value
-    matches). If '-all' is also specified, then the result of the command is the list of all
-    values that matched. The '-inline' and '-bool' options are mutually exclusive.
-
-+'-bool'+::
-    Changes the result to '1' if a match was found, or '0' otherwise. If '-all' is also specified,
-    the result will be a list of '0' and '1' for each element of the list depending upon whether
-    the corresponding element matches. The '-inline' and '-bool' options are mutually exclusive.
-
-+'-not'+::
-    This negates the sense of the match, returning the index (or value
-    if '-inline' is specified) of the first non-matching value in the
-    list. If '-bool' is also specified, the '0' will be returned if a
-    match is found, or '1' otherwise. If '-all' is also specified,
-    non-matches will be returned rather than matches.
-
-+'-nocase'+::
-    Causes comparisons to be handled in a case-insensitive manner.
-
-lsort
-~~~~~
-+*lsort* ?*-integer*|*-command* 'cmdname'? ?*-decreasing*|*-increasing*? 'list'+
-
-Sort the elements of *list*, returning a new list in sorted order.
-By default, ASCII sorting is used, with the result in increasing order.
-
-If *-integer* is specified, numeric sorting is used.
-
-If *-command cmdname* is specified, *cmdname* is treated as a
-command name. For each comparison, *cmdname $value1 $value2* is called
-which should return '-1' if *$value1* is less than *$value2*, '0' if
-they are equal, or '1' otherwise.
-
-If *-decreasing* is specified, the resulting list is in the opposite
-order to what it would be otherwise. *-increasing* is the default.
-
-open
-~~~~
-+*open* 'fileName ?access?'+
-
-Opens a file and returns an identifier
-that may be used in future invocations
-of commands like 'read', 'puts', and 'close'.
-*fileName* gives the name of the file to open.
-
-The *access* argument indicates the way in which the file is to be accessed.
-It may have any of the following values:
-
-+r+::
-    Open the file for reading only; the file must already exist.
-
-+r++::
-    Open the file for both reading and writing; the file must
-    already exist.
-
-+w+::
-    Open the file for writing only. Truncate it if it exists. If it doesn't
-    exist, create a new file.
-
-+w++::
-    Open the file for reading and writing. Truncate it if it exists.
-    If it doesn't exist, create a new file.
-
-+a+::
-    Open the file for writing only. The file must already exist, and the file
-    is positioned so that new data is appended to the file.
-
-+a++::
-    Open the file for reading and writing. If the file doesn't
-    exist, create a new empty file. Set the initial access position
-    to the end of the file.
-
-*Access* defaults to 'r'.
-
-If a file is opened for both reading and writing, then 'seek'
-must be invoked between a read and a write, or vice versa.
-
-See also 'socket'
-
-package
-~~~~~~~
-+*package provide* 'name ?version?'+
-
-Indicates that the current script provides the package named *name*.
-If no version is specified, '1.0' is used.
-
-Any script which provides a package may include this statement
-as the first statement, although it is not required.
-
-+*package require* 'name ?version?'*+
-
-Searches for the package with the given *name* by examining each path
-in '$::auto_path' and trying to load '$path/$name.tcl'.
-
-If either file exists, it is loaded with 'source'.
-
-Typically '$::auto_path' contains the paths '.' and '/lib/jim'.
-
-pid
-~~~
-+*pid*+
-
-Returns the process identifier of the current process.
-
-proc
-~~~~
-+*proc* 'name args ?statics? body'+
-
-The 'proc' command creates a new Tcl command procedure, *name*.
-When the new command is invoked, the contents of *body* will be executed.
-Tcl interpreter. *args* specifies the formal arguments to the procedure.
-If specified, *static*, declares static variables which are bound to the
-procedure.
-
-See PROCEDURES for detailed information about Tcl procedures.
-
-The 'proc' command returns the null string. When a procedure is invoked,
-the procedure's return value is the value specified in a 'return' command.
-If the procedure doesn't execute an explicit 'return', then its return
-value is the value of the last command executed in the procedure's body.
-
-If an error occurs while executing the procedure body, then the
-procedure-as-a-whole will return that same error.
-
-puts
-~~~~
-+*puts* ?*-nonewline*? '?fileId? string'+
-
-+'fileId' *puts* ?*-nonewline*? 'string'+
-
-Writes the characters given by *string* to the file given
-by *fileId*. *fileId* must have been the return
-value from a previous call to 'open', or it may be
-'stdout' or 'stderr' to refer to one of the standard I/O
-channels; it must refer to a file that was opened for
-writing.
-
-In the first form, if no *fileId* is specified then it defaults to 'stdout'.
-'puts' normally outputs a newline character after *string*,
-but this feature may be suppressed by specifying the '-nonewline'
-switch.
-
-Output to files is buffered internally by Tcl; the 'flush'
-command may be used to force buffered characters to be output.
-
-pwd
-~~~
-+*pwd*+
-
-Returns the path name of the current working directory.
-
-rand
-~~~~
-+*rand* '?min? ?max?'+
-
-Returns a random integer between *min* (defaults to 0) and *max*
-(defaults to the maximum integer).
-
-If only one argument is given, it is interpreted as *max*.
-
-range
-~~~~
-+*range* '?start? end ?step?'+
-
-Returns a list of integers starting at *start* (defaults to 0)
-and ranging up to but not including *end* in steps of *step* defaults to 1).
-
-    jim> range 5
-    0 1 2 3 4
-    jim> range 2 5
-    2 3 4
-    jim> range 2 10 4
-    2 6
-    jim> range 7 4 -2
-    7 5
-
-read
-~~~~
-+*read* ?*-nonewline*? 'fileId'+
-
-+'fileId' *read* ?*-nonewline*?+
-
-+*read* 'fileId numBytes'+
-
-+'fileId' *read* 'numBytes'+
-
-
-In the first form, all of the remaining bytes are read from the file
-given by *fileId*; they are returned as the result of the command.
-If the '-nonewline' switch is specified then the last
-character of the file is discarded if it is a newline.
-
-In the second form, the extra argument specifies how many bytes to read;
-exactly this many bytes will be read and returned, unless there are fewer than
-*numBytes* bytes left in the file; in this case, all the remaining
-bytes are returned.
-
-*fileId* must be 'stdin' or the return value from a previous call
-to 'open'; it must refer to a file that was opened for reading.
-
-regexp
-~~~~~~
-+*regexp ?-nocase? ?-line? ?-indices? ?-start* 'offset'? *?-all? ?-inline? ?--?* 'exp string ?matchVar? ?subMatchVar subMatchVar ...?'+
-
-Determines whether the regular expression *exp* matches part or
-all of *string* and returns 1 if it does, 0 if it doesn't.
-
-See REGULAR EXPRESSIONS above for complete information on the
-syntax of *exp* and how it is matched against *string*.
-
-If additional arguments are specified after *string* then they
-are treated as the names of variables to use to return
-information about which part(s) of *string* matched *exp*.
-*matchVar* will be set to the range of *string* that
-matched all of *exp*. The first *subMatchVar* will contain
-the characters in *string* that matched the leftmost parenthesized
-subexpression within *exp*, the next *subMatchVar* will
-contain the characters that matched the next parenthesized
-subexpression to the right in *exp*, and so on.
-
-Normally, *matchVar* and the each *subMatchVar* are set to hold the
-matching characters from 'string', however see '-indices' and
-'-inline' below.
-
-If there are more values for *subMatchVar* than parenthesized subexpressions
-within *exp*, or if a particular subexpression in *exp* doesn't
-match the string (e.g. because it was in a portion of the expression
-that wasn't matched), then the corresponding *subMatchVar* will be
-set to '"-1 -1"' if '-indices' has been specified or to an empty
-string otherwise.
-
-The following switches modify the behaviour of *regexp*
-
-+*-nocase*+::
-    Causes upper-case and lower-case characters to be treated as
-    identical during the matching process.
-
-+*-line*+::
-    Use newline-sensitive matching. By default, newline
-    is a completely ordinary character with no special meaning in
-    either REs or strings. With this flag, '[^' bracket expressions
-    and '.' never match newline, a '^' anchor matches the null
-    string after any newline in the string in addition to its normal
-    function, and the '$' anchor matches the null string before any
-    newline in the string in addition to its normal function.
-
-+*-indices*+::
-    Changes what is stored in the subMatchVars. Instead of
-    storing the matching characters from string, each variable
-    will contain a list of two decimal strings giving the indices
-    in string of the first and last characters in the matching
-    range of characters.
-
-+*-start* 'offset'+::
-    Specifies a character index offset into the string at which to start
-    matching the regular expression. If '-indices' is
-    specified, the indices will be indexed starting from the
-    absolute beginning of the input string. *offset* will be
-    constrained to the bounds of the input string.
-
-+*-all*+::
-    Causes the regular expression to be matched as many times as possible
-    in the string, returning the total number of matches found. If this
-    is specified with match variables, they will contain information
-    for the last match only.
-
-+*-inline*+::
-    Causes the command to return, as a list, the data that would otherwise
-    be placed in match variables. When using '-inline', match variables
-    may not be specified. If used with '-all', the list will be concatenated
-    at each iteration, such that a flat list is always returned. For
-    each match iteration, the command will append the overall match
-    data, plus one element for each subexpression in the regular
-    expression.
-
-+*--*+::
-    Marks the end of switches. The argument following this one will be
-    treated as *exp* even if it starts with a +-+.
-
-regsub
-~~~~~~
-+*regsub ?-nocase? ?-all? ?-line? ?-start* 'offset'? ?*--*? 'exp string subSpec ?varName?'+
-
-This command matches the regular expression *exp* against
-*string* using the rules described in REGULAR EXPRESSIONS
-above.
-
-If *varName* is specified, the commands stores *string* to *varName*
-with the susbstitutions detailed below, and returns the number of
-substitutions made (normally 1 unless '-all' is specified).
-This is 0 if there were no matches.
-
-If *varName* is not specified, the substituted string will be returned
-instead.
-
-When copying *string*, the portion of *string* that
-matched *exp* is replaced with *subSpec*.
-If *subSpec* contains a '&' or '{backslash}0', then it is replaced
-in the substitution with the portion of *string* that
-matched *exp*.
-
-If *subSpec* contains a '{backslash}*n*', where *n* is a digit
-between 1 and 9, then it is replaced in the substitution with
-the portion of *string* that matched the **n**-th
-parenthesized subexpression of *exp*.
-Additional backslashes may be used in *subSpec* to prevent special
-interpretation of '&' or '{backslash}0' or '{backslash}*n*' or
-backslash.
-
-The use of backslashes in *subSpec* tends to interact badly
-with the Tcl parser's use of backslashes, so it's generally
-safest to enclose *subSpec* in braces if it includes
-backslashes.
-
-The following switches modify the behaviour of *regsub*
-
-+*-nocase*+::
-    Upper-case characters in *string* are converted to lower-case
-    before matching against *exp*;  however, substitutions
-    specified by *subSpec* use the original unconverted form
-    of *string*. 
-
-+*-all*+::
-    All ranges in *string* that match *exp* are found and substitution
-    is performed for each of these ranges, rather than only the
-    first. The '&' and '{backslash}*n*' sequences are handled for
-    each substitution using the information from the corresponding
-    match.
-
-+*-line*+::
-    Use newline-sensitive matching. By default, newline
-    is a completely ordinary character with no special meaning in
-    either REs or strings.  With this flag, '[^' bracket expressions
-    and '.' never match newline, a '^' anchor matches the null
-    string after any newline in the string in addition to its normal
-    function, and the '$' anchor matches the null string before any
-    newline in the string in addition to its normal function.
-
-+*-start* 'offset'+::
-    Specifies a character index offset into the string at which to
-    start matching the regular expression. *offset* will be
-    constrained to the bounds of the input string.
-
-+*--*+::
-    Marks the end of switches. The argument following this one will be
-    treated as *exp* even if it starts with a +-+.
-
-ref
-~~~
-+*ref* 'string tag ?finalizer?'+
-
-Create a new reference containing *string* of type *tag*.
-If *finalizer* is specified, it is a command which will be invoked
-when the a garbage collection cycle runs and this reference is
-no longer accessible.
-
-The finalizer is invoked as:
-
-  +finalizer 'reference string'+
-
-See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
-
-rename
-~~~~~~
-+*rename* 'oldName newName'+
-
-Rename the command that used to be called *oldName* so that it
-is now called *newName*.  If *newName* is an empty string
-(e.g. {}) then *oldName* is deleted.  The 'rename' command
-returns an empty string as result.
-
-return
-~~~~~~
-+*return* ?*-code* 'code'? ?*-errorinfo* 'stacktrace'? ?'value'?+
-
-Return immediately from the current procedure (or top-level command
-or 'source' command), with *value* as the return value.  If *value*
-is not specified, an empty string will be returned as result.
-
-If *-code* is specified (as either a number or ok, error, break,
-continue, signal, return or exit), this code will be used instead
-of +JIM_OK+. This is generally useful when implementing flow of control
-commands.
-
-If *-errorinfo* is specified (as returned from 'info stacktrace')
-it is used to initialize the stacktrace.
-
-scan
-~~~~
-+*scan* 'string format varName1 ?varName2 ...?'+
-
-This command parses fields from an input string in the same fashion
-as the C 'sscanf' procedure.  *String* gives the input to be parsed
-and *format* indicates how to parse it, using '%' fields as in
-'sscanf'.  All of the 'sscanf' options are valid; see the 'sscanf'
-man page for details.  Each *varName* gives the name of a variable;
-when a field is scanned from *string*, the result is converted back
-into a string and assigned to the corresponding *varName*.  The
-only unusual conversion is for '%c'.  For '%c' conversions a single
-character value is converted to a decimal string, which is then
-assigned to the corresponding *varName*; no field width may be
-specified for this conversion.
-
-seek
-~~~~
-+*seek* 'fileId offset ?origin?'+
-
-+'fileId' *seek* 'offset ?origin?'+
-
-Change the current access position for *fileId*.
-The *offset* and *origin* arguments specify the position at
-which the next read or write will occur for *fileId*.
-*offset* must be a number (which may be negative) and *origin*
-must be one of the following:
-
-+*start*+::
-    The new access position will be *offset* bytes from the start
-    of the file.
-
-+*current*+::
-    The new access position will be *offset* bytes from the current
-    access position; a negative *offset* moves the access position
-    backwards in the file.
-
-+*end*+::
-    The new access position will be *offset* bytes from the end of
-    the file.  A negative *offset* places the access position before
-    the end-of-file, and a positive *offset* places the access position
-    after the end-of-file.
-
-The *origin* argument defaults to 'start'.
-
-*fileId* must have been the return value from a previous call to
-'open', or it may be 'stdin', 'stdout', or 'stderr' to refer to one
-of the standard I/O channels.
-
-This command returns an empty string.
-
-set
-~~~
-+*set* 'varName ?value?'+
-
-Returns the value of variable *varName*.
-
-If *value* is specified, then set the value of *varName* to *value*,
-creating a new variable if one doesn't already exist, and return
-its value.
-
-If *varName* contains an open parenthesis and ends with a
-close parenthesis, then it refers to an array element:  the characters
-before the open parenthesis are the name of the array, and the characters
-between the parentheses are the index within the array.
-Otherwise *varName* refers to a scalar variable.
-
-If no procedure is active, then *varName* refers to a global
-variable.
-
-If a procedure is active, then *varName* refers to a parameter
-or local variable of the procedure, unless the *global* command
-has been invoked to declare *varName* to be global.
-
-The '::' prefix may also be used to explicitly reference a variable
-in the global scope.
-
-setref
-~~~~~~
-+*setref* 'reference string'+
-
-Store a new string in *reference*, replacing the existing string.
-The reference must be a valid reference create with the 'ref'
-command.
-
-See GARBAGE COLLECTION, REFERENCES, LAMBDA for more detail.
-
-signal
-~~~~~~
-Command for signal handling.
-
-See 'kill' for the different forms which may be used to specify signals.
-
-Commands which return a list of signal names do so using the canonical form:
-"+SIGINT SIGTERM+".
-
-+*signal handle* ?'signals ...'?+::
-    If no signals are given, returns a list of all signals which are currently
-    being handled.
-    If signals are specified, these are added to the list of signals currently
-    being handled.
-
-+*signal ignore* ?'signals ...'?+::
-    If no signals are given, returns a lists all signals which are currently being
-    ignored.
-    If signals are specified, these are added to the list of signals currently
-    being ignored. These signals are still delivered, but are not considered by
-	'catch -signal' or 'try -signal'. Use 'signal check' to signals which have
-	occurred but been ignored.
-
-+*signal default* ?'signals ...'?+::
-    If no signals are given, returns a lists all signals which are currently have
-    the default behaviour.
-    If signals are specified, these are added to the list of signals which have
-    the default behaviour.
-
-+*signal check ?-clear?* ?'signals ...'?+::
-    Returns a list of signals which have been delivered to the process
-	but are 'ignored'. If signals are specified, only that set of signals will
-	be checked, otherwise all signals will be checked.
-	If '-clear' is specified, any signals returned are removed and will not be
-	returned by subsequent calls to 'signal check' unless delivered again.
-
-+*signal throw* ?'signal'?+::
-    Raises the given signal, which defaults to +SIGINT+ if not specified.
-    The behaviour is identical to:
-
-        kill signal [pid]
-
-Note that 'signal handle' and 'signal ignore' represent two forms of signal
-handling. 'signal handle' is used in conjunction with 'catch -signal' or 'try -signal'
-to immediately abort execution when the signal is delivered. Alternatively, 'signal ignore'
-is used in conjunction with 'signal check' to handle signal synchronously. Consider the
-two examples below.
-
-Prevent a processing from taking too long
-
-    signal handle SIGALRM
-	alarm 20
-	try -signal {
-		.. possibly long running process ..
-		alarm 0
-	} on signal {sig} {
-		puts stderr "Process took too long"
-	}
-
-Handle SIGHUP to reconfigure:
-
-	signal ignore SIGHUP
-    while {1} {
-		... handle configuration/reconfiguration ...
-		while {[signal check -clear SIGHUP] eq ""} {
-			... do processing ..
-		}
-		# Received SIGHUP, so reconfigure
-	}
-
-sleep
-~~~~~
-+*sleep* 'seconds'+
-
-Pauses for the given number of seconds, which may be a floating
-point value less than one to sleep for less than a second, or an
-integer to sleep for one or more seconds.
-
-source
-~~~~~~
-+*source* 'fileName'+
-
-Read file *fileName* and pass the contents to the Tcl interpreter
-as a sequence of commands to execute in the normal fashion.  The return
-value of 'source' is the return value of the last command executed
-from the file.  If an error occurs in executing the contents of the
-file, then the 'source' command will return that error.
-
-If a 'return' command is invoked from within the file, the remainder of
-the file will be skipped and the 'source' command will return
-normally with the result from the 'return' command.
-
-split
-~~~~~
-+*split* 'string ?splitChars?'+
-
-Returns a list created by splitting *string* at each character
-that is in the *splitChars* argument.
-
-Each element of the result list will consist of the
-characters from *string* between instances of the
-characters in *splitChars*.
-
-Empty list elements will be generated if *string* contains
-adjacent characters in *splitChars*, or if the first or last
-character of *string* is in *splitChars*.
-
-If *splitChars* is an empty string then each character of
-*string* becomes a separate element of the result list.
-
-*SplitChars* defaults to the standard white-space characters.
-For example,
-
-    split "comp.unix.misc" .
-
-returns +'"comp unix misc"'+ and
-
-    split "Hello world" {}
-
-returns +'"H e l l o { } w o r l d"'+.
-
-string
-~~~~~~
-
-+*string* 'option arg ?arg ...?'+
-
-Perform one of several string operations, depending on *option*.
-The legal options (which may be abbreviated) are:
-
-+*string compare ?-nocase?* 'string1 string2'+::
-    Perform a character-by-character comparison of strings *string1* and
-    *string2* in the same way as the C 'strcmp' procedure.  Return
-    -1, 0, or 1, depending on whether *string1* is lexicographically
-    less than, equal to, or greater than *string2*.
-    Performs a case-insensitive comparison if '-nocase' is specified.
-
-+*string equal ?-nocase?* 'string1 string2'+::
-    Returns 1 if the strings are equal, or 0 otherwise.
-    Performs a case-insensitive comparison if '-nocase' is specified.
-
-+*string first* 'string1 string2 ?firstIndex?'+::
-    Search *string2* for a sequence of characters that exactly match
-    the characters in *string1*.  If found, return the index of the
-    first character in the first such match within *string2*.  If not
-    found, return -1. If *firstIndex* is specified, matching will start
-    from *firstIndex* of *string1*.
- ::
-    See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *firstIndex*.
-
-+*string index* 'string charIndex'+::
-    Returns the *charIndex*'th character of the *string*
-    argument.  A *charIndex* of 0 corresponds to the first
-    character of the string.
-    If *charIndex* is less than 0 or greater than
-    or equal to the length of the string then an empty string is
-    returned.
- ::
-    See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *charIndex*.
-
-+*string last* 'string1 string2 ?lastIndex?'+::
-    Search *string2* for a sequence of characters that exactly match
-    the characters in *string1*.  If found, return the index of the
-    first character in the last such match within *string2*.  If there
-    is no match, then return -1. If *lastIndex* is specified, only characters
-    up to *lastIndex* of *string2* will be considered in the match.
- ::
-    See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *lastIndex*.
-
-+*string length* 'string'+::
-    Returns a decimal string giving the number of characters in *string*.
-
-+*string match ?-nocase?* 'pattern string'+::
-    See if *pattern* matches *string*; return 1 if it does, 0
-    if it doesn't.  Matching is done in a fashion similar to that
-    used by the C-shell.  For the two strings to match, their contents
-    must be identical except that the following special sequences
-    may appear in *pattern*:
-
-    +*+;;
-        Matches any sequence of characters in *string*,
-        including a null string.
-
-    +?+;;
-        Matches any single character in *string*.
-
-    +[*chars*]+;;
-        Matches any character in the set given by *chars*.
-        If a sequence of the form *x*-*y* appears in *chars*,
-        then any character between *x* and *y*, inclusive,
-        will match.
-
-    +\x+;;
-        Matches the single character *x*.  This provides a way of
-        avoiding the special interpretation of the characters \`\*?[]\`
-        in **pattern**.
- ::
-    Performs a case-insensitive comparison if '-nocase' is specified.
-
-+*string range* 'string first last'+::
-    Returns a range of consecutive characters from *string*, starting
-    with the character whose index is *first* and ending with the
-    character whose index is *last*.  An index of 0 refers to the
-    first character of the string.
- ::
-    See STRING AND LIST INDEX SPECIFICATIONS for all allowed forms for *first* and *last*.
- ::
-    If *first* is less than zero then it is treated as if it were zero, and
-    if *last* is greater than or equal to the length of the string then
-    it is treated as if it were 'end'.  If *first* is greater than
-    *last* then an empty string is returned.
-
-+*string repeat* 'string count'+::
-    Returns a new string consisting of *string* repeated *count* times.
-
-+*string reverse* 'string'+::
-    Returns a string that is the same length as *string* but
-    with its characters in the reverse order.
-
-+*string tolower* 'string'+::
-    Returns a value equal to *string* except that all upper case
-    letters have been converted to lower case.
-
-+*string toupper* 'string'+::
-    Returns a value equal to *string* except that all lower case
-    letters have been converted to upper case.
-
-+*string trim* 'string ?chars?'+::
-    Returns a value equal to *string* except that any leading
-    or trailing characters from the set given by *chars* are
-    removed.
-    If *chars* is not specified then white space is removed
-    (spaces, tabs, newlines, and carriage returns).
-
-+*string trimleft* 'string ?chars?'+::
-    Returns a value equal to *string* except that any
-    leading characters from the set given by *chars* are
-    removed.
-    If *chars* is not specified then white space is removed
-    (spaces, tabs, newlines, and carriage returns).
-
-+*string trimright* 'string ?chars?'+::
-    Returns a value equal to *string* except that any
-    trailing characters from the set given by *chars* are
-    removed.
-    If *chars* is not specified then white space is removed
-    (spaces, tabs, newlines, and carriage returns).
-
-subst
-~~~~~
-+*subst ?-nobackslashes? ?-nocommands? ?-novariables?* 'string'+
-
-This command performs variable substitutions, command substitutions,
-and backslash substitutions on its string argument and returns the
-fully-substituted result. The substitutions are performed in exactly
-the same way as for Tcl commands. As a result, the string argument
-is actually substituted twice, once by the Tcl parser in the usual
-fashion for Tcl commands, and again by the subst command.
-
-If any of the *-nobackslashes*, *-nocommands*, or *-novariables* are
-specified, then the corresponding substitutions are not performed.
-For example, if *-nocommands* is specified, no command substitution
-is performed: open and close brackets are treated as ordinary
-characters with no special interpretation.
-
-*Note*: when it performs its substitutions, subst does not give any
-special treatment to double quotes or curly braces. For example,
-the following script returns 'xyz \{44\}', not 'xyz \{$a\}'.
-
-    set a 44
-    subst {xyz {$a}}
-
-
-switch
-~~~~~~
-+*switch* '?options? string pattern body ?pattern body ...?'+
-
-+*switch* '?options? string {pattern body ?pattern body ...?}'+
-
-The 'switch' command matches its string argument against each of
-the pattern arguments in order. As soon as it finds a pattern that
-matches string it evaluates the following body and returns the
-result of that evaluation. If the last pattern argument is default
-then it matches anything. If no pattern argument matches string and
-no default is given, then the switch command returns an empty string.
-If the initial arguments to switch start with - then they are treated
-as options. The following options are currently supported:
-
-    +-exact+::
-        Use exact matching when comparing string to a
-        pattern. This is the default.
-
-    +-glob+::
-        When matching string to the patterns, use glob-style
-        matching (i.e. the same as implemented by the string
-        match command).
-
-    +-regexp+::
-        When matching string to the patterns, use regular
-        expression matching (i.e. the same as implemented
-        by the regexp command).
-
-    +-command 'commandname'+::
-        When matching string to the patterns, use the given command, which
-        must be a single word. The command is invoked as
-        'commandname pattern string', or 'commandname -nocase pattern string'
-        and must return 1 if matched, or 0 if not.
-
-    +--+::
-        Marks the end of options. The argument following
-        this one will be treated as string even if it starts
-        with a -.
-
-Two syntaxes are provided for the pattern and body arguments. The
-first uses a separate argument for each of the patterns and commands;
-this form is convenient if substitutions are desired on some of the
-patterns or commands. The second form places all of the patterns
-and commands together into a single argument; the argument must
-have proper list structure, with the elements of the list being the
-patterns and commands. The second form makes it easy to construct
-multi-line switch commands, since the braces around the whole list
-make it unnecessary to include a backslash at the end of each line.
-Since the pattern arguments are in braces in the second form, no
-command or variable substitutions are performed on them; this makes
-the behavior of the second form different than the first form in
-some cases.
-
-If a body is specified as '-' it means that the body for the next
-pattern should also be used as the body for this pattern (if the
-next pattern also has a body of ``-'' then the body after that is
-used, and so on). This feature makes it possible to share a single
-body among several patterns.
-
-Below are some examples of switch commands:
-
-    switch abc a - b {format 1} abc {format 2} default {format 3}
-
-will return 2,
-
-    switch -regexp aaab {
-           ^a.*b$ -
-           b {format 1}
-           a* {format 2}
-           default {format 3}
-    }
-
-will return 1, and
-
-    switch xyz {
-           a -
-           b {format 1}
-           a* {format 2}
-           default {format 3}
-    }
-
-will return 3.
-
-tailcall
-~~~~~~~~
-+*tailcall* 'cmd ?arg...?'+
-
-The 'tailcall' command provides an optimised way of invoking a command whilst replacing
-the current call frame. This is similar to 'exec' in Bourne Shell.
-
-The following are identical except the first immediately replaces the current call frame.
-
-  tailcall a b c
-
-  return [uplevel 1 a b c]
-
-'tailcall' is useful for a dispatch mechanism:
-
-  proc a {cmd args} {
-	tailcall sub_$cmd {*}$args
-  }
-  proc sub_cmd1 ...
-  proc sub_cmd2 ...
-
-tell
-~~~~
-+*tell* 'fileId'+
-
-+'fileId' *tell*+
-
-Returns a decimal string giving the current access position in
-*fileId*.
-
-*fileId* must have been the return value from a previous call to
-'open', or it may be 'stdin', 'stdout', or 'stderr' to refer to one
-of the standard I/O channels.
-
-throw
-~~~~~
-+*throw* 'code ?msg?'+
-
-This command throws an exception (return) code along with an optional message.
-This command is mostly for convenient usage with 'try'.
-
-The command +throw break+ is equivalent to +break+.
-The command +throw 20 message+ can be caught with an +on 20 ...+ clause to 'try'.
-
-time
-~~~~
-+*time* 'command ?count?'+
-
-This command will call the Tcl interpreter *count*
-times to execute *command* (or once if *count* isn't
-specified).  It will then return a string of the form
-
-    503 microseconds per iteration
-
-which indicates the average amount of time required per iteration,
-in microseconds.
-
-Time is measured in elapsed time, not CPU time.
-
-try
-~~~
-+*try* '?catchopts? tryscript' ?*on* 'returncodes {?resultvar? ?optsvar?} handlerscript ...'? ?*finally* 'finalscript'?+
-
-The 'try' command is provided as a convenience for exception handling.
-
-This interpeter first evaluates *tryscript* under the effect of the catch
-options *catchopts* (e.g. +-signal -noexit --+, see 'catch').
-
-It then evaluates the script for the first matching 'on' handler
-(there many be zero or more) based on the return code from the 'try'
-section. For example a normal +JIM_ERR+ error will be matched by
-an 'on error' handler.
-
-Finally, any *finalscript* is evaluated.
-
-The result of this command is the result of *tryscript*, except in the
-case where an exception occurs in a matching 'on' handler script or the 'finally' script,
-in which case the result is this new exception.
-
-The specified *returncodes* is a list of return codes either as names ('ok', 'error', 'break', etc.)
-or as integers.
-
-If *resultvar* and *optsvar* are specified, they are set as for 'catch' before evaluating
-the matching handler.
-
-For example:
-
-    set f [open input]
-    try -signal {
-        process $f
-    } on {continue break} {} {
-        error "Unexpected break/continue"
-    } on error {msg opts} {
-        puts "Dealing with error"
-        return {*}$opts $msg
-    } on signal sig {
-        puts "Got signal: $sig"
-    } finally {
-        $f close
-    }
-
-If break, continue or error are raised, they are dealt with by the matching
-handler.
-
-In any case, the file will be closed via the 'finally' clause.
-
-See also 'throw', 'catch', 'return', 'error'.
-
-unknown
-~~~~~~~
-+*unknown* 'cmdName ?arg arg ...?'+
-
-This command doesn't actually exist as part of Tcl, but Tcl will
-invoke it if it does exist.
-
-If the Tcl interpreter encounters a command name for which there
-is not a defined command, then Tcl checks for the existence of
-a command named 'unknown'.
-
-If there is no such command, then the interpeter returns an
-error.
-
-If the 'unknown' command exists, then it is invoked with
-arguments consisting of the fully-substituted name and arguments
-for the original non-existent command.
-
-The 'unknown' command typically does things like searching
-through library directories for a command procedure with the name
-*cmdName*, or expanding abbreviated command names to full-length,
-or automatically executing unknown commands as UNIX sub-processes.
-
-In some cases (such as expanding abbreviations) 'unknown' will
-change the original command slightly and then (re-)execute it.
-The result of the 'unknown' command is used as the result for
-the original non-existent command.
-
-unset
-~~~~~
-+*unset ?-nocomplain? ?--?* '?name name ...?'+
-
-Remove variables.
-Each *name* is a variable name, specified in any of the
-ways acceptable to the 'set' command.
-
-If a *name* refers to an element of an array, then that
-element is removed without affecting the rest of the array.
-
-If a *name* consists of an array name with no parenthesized
-index, then the entire array is deleted.
-
-The 'unset' command returns an empty string as result.
-
-An error occurs if any of the variables doesn't exist, unless '-nocomplain'
-is specified. The '--' argument may be specified to stop option processing
-in case the variable name may be '-nocomplain'.
-
-uplevel
-~~~~~~~
-+*uplevel* '?level? command ?command ...?'+
-
-All of the *command* arguments are concatenated as if they had
-been passed to 'concat'; the result is then evaluated in the
-variable context indicated by *level*.  'Uplevel' returns
-the result of that evaluation.  If *level* is an integer, then
-it gives a distance (up the procedure calling stack) to move before
-executing the command.  If *level* consists of '\#' followed by
-a number then the number gives an absolute level number.  If *level*
-is omitted then it defaults to '1'.  *Level* cannot be
-defaulted if the first *command* argument starts with a digit or '\#'.
-
-For example, suppose that procedure 'a' was invoked
-from top-level, and that it called 'b', and that 'b' called 'c'.
-Suppose that 'c' invokes the 'uplevel' command.  If *level*
-is '1' or '\#2'  or omitted, then the command will be executed
-in the variable context of 'b'.  If *level* is '2' or '\#1'
-then the command will be executed in the variable context of 'a'.
-
-If *level* is '3' or '\#0' then the command will be executed
-at top-level (only global variables will be visible).
-The 'uplevel' command causes the invoking procedure to disappear
-from the procedure calling stack while the command is being executed.
-In the above example, suppose 'c' invokes the command
-
-    uplevel 1 {set x 43; d}
-
-where 'd' is another Tcl procedure.  The 'set' command will
-modify the variable 'x' in 'b's context, and 'd' will execute
-at level 3, as if called from 'b'.  If it in turn executes
-the command
-
-    uplevel {set x 42}
-
-then the 'set' command will modify the same variable 'x' in 'b's
-context:  the procedure 'c' does not appear to be on the call stack
-when 'd' is executing.  The command 'info level' may
-be used to obtain the level of the current procedure.
-
-'Uplevel' makes it possible to implement new control
-constructs as Tcl procedures (for example, 'uplevel' could
-be used to implement the 'while' construct as a Tcl procedure).
-
-upvar
-~~~~~
-+*upvar* '?level? otherVar myVar ?otherVar myVar ...?'+
-
-This command arranges for one or more local variables in the current
-procedure to refer to variables in an enclosing procedure call or
-to global variables.
-
-*Level* may have any of the forms permitted for the 'uplevel'
-command, and may be omitted if the first letter of the first *otherVar*
-isn't '\#' or a digit (it defaults to '1').
-
-For each *otherVar* argument, 'upvar' makes the variable
-by that name in the procedure frame given by *level* (or at
-global level, if *level* is '\#0') accessible
-in the current procedure by the name given in the corresponding
-*myVar* argument.
-
-The variable named by *otherVar* need not exist at the time of the
-call;  it will be created the first time *myVar* is referenced, just like
-an ordinary variable.
-
-'Upvar' may only be invoked from within procedures.
-
-'Upvar' returns an empty string.
-
-The 'upvar' command simplifies the implementation of call-by-name
-procedure calling and also makes it easier to build new control constructs
-as Tcl procedures.
-For example, consider the following procedure:
-
-    proc add2 name {
-        upvar $name x
-        set x [expr $x+2]
-    }
-
-'Add2' is invoked with an argument giving the name of a variable,
-and it adds two to the value of that variable.
-Although 'add2' could have been implemented using 'uplevel'
-instead of 'upvar', 'upvar' makes it simpler for 'add2'
-to access the variable in the caller's procedure frame.
-
-while
-~~~~~
-+*while* 'test body'+
-
-The *while* command evaluates *test* as an expression
-(in the same way that 'expr' evaluates its argument).
-The value of the expression must be numeric; if it is non-zero
-then *body* is executed by passing it to the Tcl interpreter.
-
-Once *body* has been executed then *test* is evaluated
-again, and the process repeats until eventually *test*
-evaluates to a zero numeric value.  'Continue'
-commands may be executed inside *body* to terminate the current
-iteration of the loop, and 'break'
-commands may be executed inside *body* to cause immediate
-termination of the 'while' command.
-
-The 'while' command always returns an empty string.
-
-OPTIONAL-EXTENSIONS
--------------------
-
-The following extensions may or may not be available depending upon
-what options were selected when Jim Tcl was built.
-
-bio
-~~~
-The bio command provides a way to read and write binary files
-from within Tcl. Note that since Jim supports binary strings, the
-main use of this command is 'bio copy' to easily copy between file
-descriptors.
-
-+*bio read ?-hex?* 'fd var numbytes'+::
-    Read bytes from a file descriptor. By default the data is not encoded.
-    Using *-hex* encodes the data as ascii hex instead. Returns
-    the number of bytes actually read.
-
-+*bio write ?-hex?* 'fd buf'+::
-    Write a string to a file descriptor. If *-hex* is specified, the
-    string is expected to be in ascii hexx format. Returns the number
-    of bytes actually written.
-
-+*bio copy* 'fromfd tofd ?numbytes?'+::
-    Copy binary data from the file descriptor *fromfd* to the
-    file descriptor *tofd*. If *numbytes* is specified, at most that many
-    bytes will be copied. Otherwise copying continues until the end
-    of the input file. Returns the number of bytes actually copied.
-
-posix: os.fork, os.wait, os.gethostname, os.getids, os.uptime
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-+*os.fork*+::
-    Invokes 'fork(2)' and returns the result.
-
-+*os.wait -nohang* 'pid'+::
-    Invokes waitpid(2), with WNOHANG if *-nohang* is specified.
-    Returns a list of 3 elements.
-
-   {0 none 0} if -nohang is specified, and the process is still alive.
- 
-   {-1 error <error-description>} if the process does not exist or has already been waited for.
- 
-   {<pid> exit <exit-status>} if the process exited normally.
- 
-   {<pid> signal <signal-number>} if the process terminated on a signal.
- 
-   {<pid> other 0} otherwise (core dump, stopped, continued, etc.)
-
-+*os.gethostname*+::
-    Invokes 'gethostname(3)' and returns the result.
-
-+*os.getids*+::
-    Returns the various user/group ids for the current process.
-
-    jim> os.getids
-    uid 1000 euid 1000 gid 100 egid 100
-
-+*os.uptime*+::
-    Returns the number of seconds since system boot. See description of 'uptime' in 'sysinfo(2)'.
-
-ANSI I/O (aio) and EVENTLOOP API
---------------------------------
-Jim provides an alternative object-based API for I/O.
-
-See '<<_open,open>>' and '<<_socket,socket>>' for commands which return an I/O handle.
-
-aio
-~~~
-+$handle *read ?-nonewline?* '?len?'+::
-    Read and return bytes from the stream. To eof if no len.
-
-+$handle *gets* '?var?'+::
-    Read one line and return it or store it in the var
-
-+$handle *puts ?-nonewline?* 'str'+::
-    Write the string, with newline unless -nonewline
-
-+$handle *flush*+::
-    Flush the stream
-
-+$handle *eof*+::
-    Returns 1 if stream is at eof
-
-+$handle *close*+::
-    Closes the stream
-
-+$handle *seek* 'offset' *?start|current|end?*+::
-    Seeks in the stream (default 'current')
-
-+$handle *tell*+::
-    Returns the current seek position
-
-+$handle *ndelay ?0|1?*+::
-    Set O_NDELAY (if arg). Returns current/new setting.
-    Note that in general ANSI I/O interacts badly with non-blocking I/O.
-    Use with care.
-
-+$handle *accept*+::
-    Server socket only: Accept a connection and return stream
-
-+$handle *sendto* 'str ?hostname:?port'+::
-    Sends the string, *str*, to the given address via the socket using sendto(2).
-    This is intended for udp sockets and may give an error or behave in unintended
-    ways for other handle types.
-    Returns the number of bytes written.
-
-+$handle *recvfrom* 'maxlen ?addrvar?'+::
-    Receives a message from the handle via recvfrom(2) and returns it.
-    At most *maxlen* bytes are read.
-    If *addrvar* is specified, the sending address of the message is stored in
-    the named variable in the form 'hostname:port'.
-
-eventloop: after, vwait
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The following commands allow a script to be invoked when the given condition occurs.
-
-+$handle *readable* '?readable-script ?eof-script??'+::
-    Returns script, or invoke readable-script when readable, eof-script on eof, {} to remove
-
-+$handle *writable* '?writable-script?'+::
-    Returns script, or invoke writable-script when writable, {} to remove
-
-+$handle *onexception* '?exception-script?'+::
-    Returns script, or invoke exception-script when oob data, {} to remove
-
-Time-based execution is also available via the eventloop API.
-
-+*after* 'time script'+::
-        The script is executed after the given number of milliseconds have elapsed.
-        Returns an event id.
-
-+*after cancel* 'id'+::
-        Cancels an after event with the given event id.
-
-+*vwait* 'variable'+::
-        A call to vwait is required to enter the eventloop. 'vwait' processes events until
-        the named variabled changes. The variable need not exist beforehand.
-
-socket
-~~~~~~
-Various socket types may be created.
-
-+*socket unix* 'path'+::
-    A unix domain socket client.
-
-+*socket unix.server* 'path'+::
-    A unix domain socket server.
-
-+*socket stream* 'hostname:port'+::
-    A TCP socket client.
-
-+*socket stream.server* '?hostname:?port'+::
-    A TCP socket server (*hostname* defaults to 0.0.0.0).
-
-+*socket dgram* ?'hostname:port'?+::
-    A UDP socket client. If the address is not specified,
-    the client socket will be unbound and 'sendto' must be used
-    to indicated the destination.
-
-+*socket dgram.server* 'hostname:port'+::
-    A UDP socket server.
-
-+*socket pipe*+::
-    A pipe. Note that unlike all other socket types, this command returns
-    a list of two channels: {read write}
-
-This command creates a socket connected (client) or bound (server) to the given
-address.
-
-The returned value is channel and may generally be used with the various file I/O
-commands (gets, puts, read, etc.), either as object-based syntax or Tcl-compatible syntax.
-
-    set f [socket stream www.google.com:80]
-    aio.sockstream1
-    $f puts -nonewline "GET / HTTP/1.0\r\n\r\n"
-    $f gets
-    HTTP/1.0 302 Found
-    $f close
-
-Server sockets, however support only 'accept', which is most useful in conjunction with
-the EVENTLOOP API.
-
-    set f [socket stream.server 80]
-    $f readable {
-        set client [$f accept]
-        $client gets $buf
-        ...
-        $client puts -nonewline "HTTP/1.1 404 Not found\r\n"
-        $client close
-    }
-    vwait done
-
-The special type 'pipe' isn't really a socket.
-
-    lassign [socket pipe] r w
-
-    # Must close $w after exec
-    exec ps >@$w &
-    $w close
-
-    $r readable ...
-
-syslog
-~~~~~~
-+*syslog* '?options? ?priority? message'+
-
-This  command sends message to system syslog facility with given
-priority. Valid priorities are:
-
-    emerg, alert, crit, err, error, warning, notice, info, debug
-
-If a message is specified, but no priority is specified, then a
-priority of info is used.
-
-By default, facility user is used and the value of global tcl variable
-argv0 is used as ident string. However, any of the following options
-may be specified before priority to control these parameters:
-
-+*-facility* 'value'+::
-    Use specified facility instead of user. The following
-    values for facility are recognized:
-
-    authpriv, cron, daemon, kernel, lpr, mail, news, syslog, user,
-    uucp, local0-local7
-
-+*-ident* 'string'+::
-    Use given string instead of argv0 variable for ident string.
-
-+*-options* 'integer'+::
-    Set syslog options such as LOG_CONS, LOG_NDELAY You should
-    use numeric values of those from your system syslog.h file,
-    because I haven't got time to implement yet another hash
-    table.
-
-[[BuiltinVariables]]
-BUILT-IN VARIABLES
-------------------
-
-The following global variables are created automatically
-by the Tcl library.
-
-+*env*+::
-    This variable is set by Jim as an array
-    whose elements are the environment variables for the process.
-    Reading an element will return the value of the corresponding
-    environment variable.
-    This array is initialised at startup from the 'env' command.
-
-+*auto_path*+::
-    This variable contains a list of paths to search for packages.
-    It contains {. /lib/jim} by default.
-
-The following global variables are set by jimsh.
-
-+*tcl_interactive*+::
-    This variable is set to 1 if jimsh is started in interactive mode
-    or 0 otherwise.
-
-+*argv0*+::
-    If jimsh is invoked to run a script, this variable contains the name
-    of the script.
-
-+*argv*+::
-    If jimsh is invoked to run a script, this variable contains a list
-    of any arguments supplied to the script.
-
-+*jim_argv0*+::
-    The value of argv[0] when jimsh was invoked.
-
-LICENCE
--------
-
- Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
- Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
- Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net> 
- Copyright 2008 oharboe - Oyvind Harboe - oyvind.harboe@zylin.com
- Copyright 2008 Andrew Lunn <andrew@lunn.ch>
- Copyright 2008 Duane Ellis <openocd@duaneellis.com>
- Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
- Copyright 2009 Steve Bennett <steveb@workware.net.au>
- 
- The FreeBSD license
- 
-[literal] 
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- 1. Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
- 2. Redistributions in binary form must reproduce the above
-    copyright notice, this list of conditions and the following
-    disclaimer in the documentation and/or other materials
-    provided with the distribution.
- 
- THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY
- EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
- THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
- PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
- JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
- INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
- (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
- STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
- ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- 
- The views and conclusions contained in the software and documentation
- are those of the authors and should not be interpreted as representing
- official policies, either expressed or implied, of the Jim Tcl Project.
diff --git a/doc/make-index b/doc/make-index
deleted file mode 100755
index 1f216a0..0000000
--- a/doc/make-index
+++ /dev/null
@@ -1,55 +0,0 @@
-# vim:se syn=tcl:
-
-while {[gets stdin buf] >= 0} {
-	if {$buf eq "@INSERTINDEX@"} {
-		break
-	}
-	puts $buf
-}
-
-# Collect lines and commands
-set lines {}
-set commands {}
-set c 0
-
-while {[gets stdin buf] >= 0} {
-	if {[string match "~~*" $buf]} {
-		if {[string match "*:*" $prev]} {
-			incr c
-			set target cmd_$c
-			set lines [linsert $lines end-1 "\[\[$target\]\]"]
-		} else {
-			set target _$prev
-		}
-		foreach cmd [split $prev ":,"] {
-			set cmd [string trim $cmd]
-			if {$cmd ne ""} {
-				lappend commands [list $cmd $target]
-			}
-		}
-	}
-	lappend lines $buf
-	set prev $buf
-}
-
-# Output the index
-puts {[frame="none",grid="none"]}
-puts {|=========================}
-set i 0
-foreach command [lsort $commands] {
-	foreach {cmd target} $command break
-
-	puts -nonewline "|<<$target,$cmd>> "
-	incr i
-	if {$i % 8 == 0} {
-		puts ""
-	}
-}
-while {$i % 8 != 0} {
-	incr i
-	puts -nonewline "| "
-}
-puts ""
-puts {|=========================}
-
-puts [join $lines \n]