Update documentation for recent features

In preparation for the 0.73 release

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

2 files changed, 174 insertions, 42 deletions

diff --git a/jim_tcl.txt b/jim_tcl.txt
index 1d1d816..234e328 100644
--- a/jim_tcl.txt
+++ b/jim_tcl.txt
@@ -3,7 +3,7 @@ Jim Tcl(n)
 
 NAME
 ----
-Jim Tcl v0.73 - overview of the Jim tool command language facilities
+Jim Tcl v0.73 - reference manual for the Jim Tcl scripting language
 
 SYNOPSIS
 --------
@@ -25,18 +25,12 @@ or
 
 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.
+Jim Tcl is a small footprint reimplementation of the Tcl scripting language.
+The core language engine is compatible with Tcl 8.5+, while implementing
+a significant subset of the Tcl 8.6 command set, plus additional features
+available only in Jim Tcl.
 
-This version is about double the size of "tinytcl" (6.8), depending upon
-the features selected, but is significantly faster and has many new 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 with Tcl 8.5/8.6 are:
+Some notable differences with Tcl 8.5/8.6 are:
 
 1. Object-based I/O (aio), but with a Tcl-compatibility layer
 2. I/O: Support for sockets and pipes including udp, unix domain sockets and IPv6
@@ -44,13 +38,16 @@ The major differences with Tcl 8.5/8.6 are:
 4. Support for references (`ref`/`getref`/`setref`) and garbage collection
 5. Builtin dictionary type (`dict`) with some limitations compared to Tcl 8.6
 6. `env` command to access environment variables
-7. `os.fork`, `os.wait`, `os.uptime`, `rand`
+7. Operating system features: `os.fork`, `os.wait`, `os.uptime`, `signal`, `alarm`, `sleep`
 8. Much better error reporting. `info stacktrace` as a replacement for '$errorInfo', '$errorCode'
 9. Support for "static" variables in procedures
-10. Namespaces, threads and coroutines are not support
+10. Threads and coroutines are not supported
 11. Command and variable traces are not supported
-12. Direct command line editing rather than the `history` command
+12. Built-in command line editing
 13. Expression shorthand syntax: +$(...)+
+14. Modular build allows many features to be omitted or built as dynamic, loadable modules
+15. Highly suitable for use in an embedded environment
+16. Support for UDP, IPv6, Unix-Domain sockets in addition to TCP sockets
 
 RECENT CHANGES
 --------------
@@ -64,6 +61,12 @@ Changes between 0.72 and 0.73
 5. Add +build-jim-ext+ for easy separate building of loadable modules (extensions)
 6. `local` now works with any command, not just procs
 7. Add `info alias` to access the target of an alias
+8. UTF-8 encoding past the basic multilingual plane (BMP) is supported
+9. Add `tcl::prefix`
+10. Add `history`
+11. Most extensions are now enabled by default
+12. Add support for namespaces and the `namespace` command
+13. Add `apply`
 
 Changes between 0.71 and 0.72
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -180,9 +183,9 @@ Interactive mode reads Tcl commands from standard input, evaluates
 those commands and prints the results.
 
   $ jimsh
-  Welcome to Jim version 0.71, Copyright (c) 2005-8 Salvatore Sanfilippo
+  Welcome to Jim version 0.73, Copyright (c) 2005-8 Salvatore Sanfilippo
   . info version
-  0.71
+  0.73
   . lsort [info commands p*]
   package parray pid popen proc puts pwd
   . foreach i {a b c} {
@@ -534,13 +537,18 @@ sequence is replaced by the given character:
 +{backslash}{backslash}+::
     Backslash ('{backslash}').
 
-+{backslash}'ddd'+::
++{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.
 
-+{backslash}'unnnn'+::
-    The hex digits +'nnnn'+ (between one and four of them) give a unicode codepoint.
-    The UTF-8 encoding of the codepoint is inserted.
++{backslash}unnnn+::
++{backslash}u\{nnn\}+::
++{backslash}Unnnnnnnn+::
+    The UTF-8 encoding of the unicode codepoint represented by the hex digits, +'nnnn'+, is inserted.
+    The 'u' form allows for one to four hex digits.
+    The 'U' form allows for one to eight hex digits.
+    The 'u\{nnn\}' form allows for one to eight hex digits, but makes it easier to insert
+    characters UTF-8 characters which are followed by a hex digit.
 
 For example, in the command
 
@@ -1181,8 +1189,8 @@ 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.
+See the `proc` command for information on how to define procedures
+and what happens when they are invoked. See also NAMESPACES.
 
 VARIABLES - SCALARS AND ARRAYS
 ------------------------------
@@ -1335,6 +1343,17 @@ as it does for arrays.
 
 See the `dict` command for more details.
 
+NAMESPACES
+----------
+Tcl added namespaces as a mechanism avoiding name clashes, especially in applications
+including a number of 3rd party components. While there is less need for namespaces
+in Jim Tcl (which does not strive to support large applications), it is convenient to
+provide a subset of the support for namespaces to easy porting code from Tcl.
+
+Jim Tcl currently supports "light-weight" namespaces which should be adequate for most
+purposes. This feature is currently experimental. See README.namespaces for more information
+and the documentation of the `namespace` command.
+
 GARBAGE COLLECTION, REFERENCES, LAMBDA
 --------------------------------------
 Unlike Tcl, Jim has some sophisticated support for functional programming.
@@ -1438,9 +1457,11 @@ while `string length` returns the number of characters.
 If UTF-8 support is not enabled, all commands treat bytes as characters
 and `string bytelength` returns the same value as `string length`.
 
-Note that even if UTF-8 support is not enabled, the +{backslash}uNNNN+ syntax
+Note that even if UTF-8 support is not enabled, the +{backslash}uNNNN+ and related syntax
 is still available to embed UTF-8 sequences.
 
+Jim Tcl supports all currently defined unicode codepoints. That is 21 bits, up to +'U+1FFFFF'.
+
 String Matching
 ~~~~~~~~~~~~~~~
 Commands such as `string match`, `lsearch -glob`, `array names` and others use string
@@ -1480,10 +1501,11 @@ Case Mapping and Conversion
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Jim provides a simplified unicode case mapping. This means that case conversion
 and comparison will not increase or decrease the number of characters in a string.
+(Although it may change the number of bytes).
 
 `string toupper` will convert any lowercase letters to their uppercase equivalent.
 Any character which is not a letter or has no uppercase equivalent is left unchanged.
-Similarly for `string tolower`.
+Similarly for `string tolower` and `string totitle`.
 
 Commands which perform case insensitive matches, such as `string compare -nocase`
 and `lsearch -nocase` fold both strings to uppercase before comparison.
@@ -1557,7 +1579,7 @@ the following creates an alias for the command `info exists`.
 
 `alias` returns +'name'+, allowing it to be used with `local`.
 
-See also `proc`, `curry`, `lambda`, `local`, `info alias`
+See also `proc`, `curry`, `lambda`, `local`, `info alias`, `exists -alias`
 
 append
 ~~~~~~
@@ -1573,6 +1595,17 @@ variables incrementally.
 For example, "`append a $b`" is much more efficient than
 "`set a $a$b`" if +$a+ is long.
 
+apply
+~~~~~~
++*apply* 'lambdaExpr ?arg1 arg2 \...?'+
+
+The command `apply` provides for anonymous procedure calls,
+similar to `lambda`, but without command name being created, even temporarily.
+
+The function  +'lambdaExpr'+ is a two element list +{args body}+
+or a three element list +{args body namespace}+. The first element
+args specifies the formal arguments, in the same form as the `proc` and `lambda` commands.
+
 array
 ~~~~~
 +*array* 'option arrayName ?arg\...?'+
@@ -2149,10 +2182,10 @@ this variable is unset, in which case the original environment is used).
 
 exists
 ~~~~~~
-+*exists ?-var|-proc|-command?* 'name'+
++*exists ?-var|-proc|-command|-alias?* 'name'+
 
-Checks the existence of the given variable, procedure or command
-respectively and returns 1 if it exists or 0 if not.  This command
+Checks the existence of the given variable, procedure, command
+or alias respectively and returns 1 if it exists or 0 if not.  This command
 provides a more simplified/convenient version of `info exists`,
 `info procs` and `info commands`.
 
@@ -2573,7 +2606,7 @@ The legal +'option'+'s (which may be abbreviated) are:
 
 +*info alias* 'command'+::
     +'command'+ must be an alias created with `alias`. In which case the target
-    command and arguments, as passed to `alias` are returned.
+    command and arguments, as passed to `alias` are returned. See `exists -alias`
 
 +*info body* 'procname'+::
     Returns the body of procedure +'procname'+.  +'procname'+ must be
@@ -3052,42 +3085,47 @@ 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'+::
++*-exact*+::
     +'pattern'+ is a literal string that is compared for exact equality against each list element.
     This is the default.
 
-+'-glob'+::
++*-glob*+::
     +'pattern'+ is a glob-style pattern which is matched against each list element using the same
     rules as the string match command.
 
-+'-regexp'+::
++*-regexp*+::
     +'pattern'+ is treated as a regular expression and matched against each list element using
     the rules described by `regexp`.
 
-+'-all'+::
++*-command* 'cmdname'+::
+    +'cmdname'+ is a command which is used to match the pattern against each element of the
+    list. It is invoked as +'cmdname' ?*-nocase*? 'pattern listvalue'+ and should return 1
+    for a match, or 0 for no match.
+
++*-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'+::
++*-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'+::
++*-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'+::
++*-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'+::
++*-nocase*+::
     Causes comparisons to be handled in a case-insensitive manner.
 
 lsort
@@ -4723,6 +4761,98 @@ and zero or more child nodes (ordered), as well as zero or more attribute/value
 +$tree *dump*+::
     Dumps the tree contents to stdout
 
+tcl::prefix
+~~~~~~~~~~~
+The optional tclprefix extension provides the Tcl8.6-compatible 'tcl::prefix' command
+(http://www.tcl.tk/man/tcl8.6/TclCmd/prefix.htm) for matching strings against a table
+of possible values (typically commands or options).
+
++*tcl::prefix all* 'table string'+::
+    Returns a list of all elements in +'table'+ that begin with the prefix +'string'+.
+
++*tcl::prefix longest* 'table string'+::
+    Returns the longest common prefix of all elements in +'table'+ that begin with the prefix +'string'+.
+
++*tcl::prefix match* '?options? table string'+::
+    If +'string'+ equals one element in +'table'+ or is a prefix to
+    exactly one element, the matched element is returned. If not, the
+    result depends on the +-error+ option.
+
+    +-exact+::
+        Accept only exact matches.
+
+    +-message 'string'+::
+        Use +'string'+ in the error message at a mismatch. Default is "option".
+
+    +-error 'options'+::
+        The options are used when no match is found. If +'options'+ is
+        empty, no error is generated and an empty string is returned.
+        Otherwise the options are used as return options when
+        generating the error message. The default corresponds to
+        setting +-level 0+.
+
+history
+~~~~~~~
+The optional history extension provides script access to the command line editing
+and history support available in 'jimsh'. See 'examples/jtclsh.tcl' for an example.
+Note: if line editing support is not available, `history getline` acts like `gets` and
+the remaining subcommands do nothing.
+
++*history load* 'filename'+::
+    Load history from a (text) file. If the file does not exist or is not readable,
+    it is ignored.
+
++*history getline* 'prompt ?varname?'+::
+    Displays the given prompt and allows a line to be entered. Similarly to `gets`,
+    if +'varname'+ is given, it receives the line and the length of the line is returned,
+    or -1 on EOF. If +'varname'+ is not given, the line is returned directly.
+
++*history add* 'line'+::
+    Adds the given line to the history buffer.
+
++*history save* 'filename'+::
+    Saves the current history buffer to the given file.
+
++*history show*+::
+    Displays the current history buffer to standard output.
+
+namespace
+~~~~~~~~~
+Provides namespace-related functions. See also: http://www.tcl.tk/man/tcl8.6/TclCmd/namespace.htm
+
++*namespace code* 'script'+::
+    Captures the current namespace context for later execution of
+    the script +'script'+. It returns a new script in which script has
+    been wrapped in a +*namespace inscope*+ command.
+
++*namespace current*+::
+    Returns the fully-qualified name for the current namespace.
+
++*namespace delete* '?namespace ...?'+::
+    Deletes all commands and variables with the given namespace prefixes.
+
++*namespace eval* 'namespace arg ?arg...?'+::
+    Activates a namespace called +'namespace'+ and evaluates some code in that context.
+
++*namespace origin* 'command'+::
+    Returns the fully-qualified name of the original command to which the imported command +'command'+ refers.
+
++*namespace parent* ?namespace?::
+    Returns the fully-qualified name of the parent namespace for namespace +'namespace'+, if given, otherwise
+    for the current namespace.
+
++*namespace qualifiers* 'string'+::
+    Returns any leading namespace qualifiers for +'string'+
+
++*namespace tail* 'string'+::
+    Returns the simple name at the end of a qualified string.
+
++*namespace upvar* 'namespace ?arg...?'+::
+    This command arranges for zero or more local variables in the current procedure to refer to variables in +'namespace'+
+
++*namespace which* '?-command|-variable? name'+::
+    Looks up +'name'+ as either a command (the default) or variable and returns its fully-qualified name.
+
 [[BuiltinVariables]]
 BUILT-IN VARIABLES
 ------------------
diff --git a/make-index b/make-index
index 8dba920..e743cd8 100755
--- a/make-index
+++ b/make-index
@@ -12,16 +12,18 @@ set c 0
 
 while {[gets $f buf] >= 0} {
 	if {[string match "~~*" $buf]} {
-		if {[string match "*:*" $prev]} {
+		if {[string match "*: *" $prev]} {
 			incr c
 			set target cmd_$c
 			set lines [linsert $lines end-1 "\[\[$target\]\]"]
+			set prevlist [split $prev ":, "]
 		} else {
-			set target _$prev
+			set target _[string map {:: _} $prev]
+			set prevlist [list $prev]
 		}
-		foreach cmd [split $prev ":,"] {
+		foreach cmd $prevlist {
 			set cmd [string trim $cmd]
-			if {[regexp {^[a-z.]+$} $cmd]} {
+			if {[regexp {^[a-z.:]+$} $cmd]} {
 				lappend commands [list $cmd $target]
 				set cdict($cmd) $target
 			}