added lset.n lset docs with xref and updated lindex of TIPs#22,33,45 by Kenny

10 files changed, 219 insertions, 27 deletions

diff --git a/doc/lappend.n b/doc/lappend.n
index d9a3375..c95fdcf 100644
--- a/doc/lappend.n
+++ b/doc/lappend.n
@@ -1,11 +1,12 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lappend.n,v 1.4 2000/09/07 14:27:48 poenitz Exp $
+'\" RCS: @(#) $Id: lappend.n,v 1.5 2001/11/14 23:15:33 hobbs Exp $
 '\" 
 .so man.macros
 .TH lappend n "" Tcl "Tcl Built-In Commands"
@@ -32,7 +33,11 @@ more efficient than ``\fBset a [concat $a [list $b]]\fR'' when
 \fB$a\fR is long.
 
 .SH "SEE ALSO"
-list(n), lindex(n), linsert(n), llength(n), lsort(n), lrange(n)
+list(n), lindex(n), linsert(n), llength(n), 
+.VS 8.4
+lset(n)
+.VE
+lsort(n), lrange(n)
 
 .SH KEYWORDS
 append, element, list, variable
diff --git a/doc/lindex.n b/doc/lindex.n
index 904952e..81e8bd0 100644
--- a/doc/lindex.n
+++ b/doc/lindex.n
@@ -1,27 +1,47 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 2001 by Kevin B. Kenny.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lindex.n,v 1.6 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: lindex.n,v 1.7 2001/11/14 23:15:33 hobbs Exp $
 '\" 
 .so man.macros
-.TH lindex n 8.2 Tcl "Tcl Built-In Commands"
+.TH lindex n 8.4 Tcl "Tcl Built-In Commands"
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
 lindex \- Retrieve an element from a list
 .SH SYNOPSIS
-\fBlindex \fIlist index\fR
+\fBlindex \fIlist ?index...?\fR
 .BE
-
 .SH DESCRIPTION
 .PP
-This command treats \fIlist\fR as a Tcl list and returns the
+.VS 8.4
+The \fBlindex\fP command accepts a parameter, \fIlist\fP, which
+it treats as a Tcl list. It also accepts zero or more \fIindices\fP into
+the list.  The indices may be presented either consecutively on the
+command line, or grouped in a
+Tcl list and presented as a single argument.
+.PP
+If no indices are presented, the command takes the form:
+.CS
+lindex list
+.CE
+or
+.CS
+lindex list {}
+.CE
+In this case, the return value of \fBlindex\fR is simply the value of the
+\fIlist\fR parameter.
+.PP
+When presented with a single index, the \fBlindex\fR command
+treats \fIlist\fR as a Tcl list and returns the
+.VE
 \fIindex\fR'th element from it (0 refers to the first element of the list).
-In extracting the element, \fIlindex\fR observes the same rules
+In extracting the element, \fBlindex\fR observes the same rules
 concerning braces and quotes and backslashes as the Tcl command
 interpreter; however, variable
 substitution and command substitution do not occur.
@@ -31,9 +51,42 @@ string is returned.
 If \fIindex\fR has the value \fBend\fR, it refers to the last element
 in the list, and \fBend\-\fIinteger\fR refers to the last element in
 the list minus the specified integer offset.
-
+.PP
+.VS 8.4
+If additional \fIindex\fR arguments are supplied, then each argument is
+used in turn to select an element from the previous indexing operation,
+allowing the script to select elements from sublists.  The command,
+.CS
+lindex $a 1 2 3
+.CE
+or
+.CS
+lindex $a {1 2 3}
+.CE
+is synonymous with
+.CS
+lindex [lindex [lindex $a 1] 2] 3
+.CE
+.SH EXAMPLES
+.CS
+lindex {a b c}  => a b c
+lindex {a b c} {} => a b c
+lindex {a b c} 0 => a
+lindex {a b c} 2 => c
+lindex {a b c} end => c
+lindex {a b c} end-1 => b
+lindex {{a b c} {d e f} {g h i}} 2 1 => h
+lindex {{a b c} {d e f} {g h i}} {2 1} => h
+lindex {{{a b} {c d}} {{e f} {g h}}} 1 1 0 => g
+lindex {{{a b} {c d}} {{e f} {g h}}} {1 1 0} => g
+.CE
+.VE
 .SH "SEE ALSO"
-list(n), lappend(n), linsert(n), llength(n), lsearch(n), lsort(n),
+list(n), lappend(n), linsert(n), llength(n), lsearch(n), 
+.VS 8.4
+lset(n),
+.VE
+lsort(n),
 lrange(n), lreplace(n)
 
 .SH KEYWORDS
diff --git a/doc/linsert.n b/doc/linsert.n
index f306441..98fd374 100644
--- a/doc/linsert.n
+++ b/doc/linsert.n
@@ -1,11 +1,12 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: linsert.n,v 1.5 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: linsert.n,v 1.6 2001/11/14 23:15:33 hobbs Exp $
 '\" 
 .so man.macros
 .TH linsert n 8.2 Tcl "Tcl Built-In Commands"
@@ -29,8 +30,12 @@ elements in the list, then the new elements are appended to the list.
 \fBend\-\fIinteger\fR refers to the last element in the list minus the
 specified integer offset.
 
+
 .SH "SEE ALSO"
-list(n), lappend(n), llength(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), llength(n), lsearch(n), 
+lset(n), lsort(n), lrange(n), lreplace(n)
+.VE
 
 .SH KEYWORDS
 element, insert, list
diff --git a/doc/list.n b/doc/list.n
index 824a473..32305ad 100644
--- a/doc/list.n
+++ b/doc/list.n
@@ -1,11 +1,12 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: list.n,v 1.4 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: list.n,v 1.5 2001/11/14 23:15:33 hobbs Exp $
 '\" 
 .so man.macros
 .TH list n "" Tcl "Tcl Built-In Commands"
@@ -42,7 +43,11 @@ while \fBconcat\fR with the same arguments will return
 .CE
 
 .SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), lsort(n),
+lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
+.VS 8.4
+lset(n),
+.VE
+lsort(n),
 lrange(n), lreplace(n)
 
 .SH KEYWORDS
diff --git a/doc/llength.n b/doc/llength.n
index 163af67..591dc23 100644
--- a/doc/llength.n
+++ b/doc/llength.n
@@ -1,11 +1,12 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: llength.n,v 1.4 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: llength.n,v 1.5 2001/11/14 23:15:33 hobbs Exp $
 '\" 
 .so man.macros
 .TH llength n "" Tcl "Tcl Built-In Commands"
@@ -23,7 +24,10 @@ Treats \fIlist\fR as a list and returns a decimal string giving
 the number of elements in it.
 
 .SH "SEE ALSO"
-list(n), lindex(n), lrange(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), lsearch(n), 
+lset(n), lsort(n), lrange(n), lreplace(n)
+.VE
 
 .SH KEYWORDS
 element, list, length
diff --git a/doc/lrange.n b/doc/lrange.n
index e937cf4..73a3419 100644
--- a/doc/lrange.n
+++ b/doc/lrange.n
@@ -1,11 +1,12 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lrange.n,v 1.4 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: lrange.n,v 1.5 2001/11/14 23:15:33 hobbs Exp $
 '\" 
 .so man.macros
 .TH lrange n 7.4 Tcl "Tcl Built-In Commands"
@@ -36,7 +37,10 @@ for simple fields that aren't enclosed in braces); it does, however,
 produce exactly the same results as ``\fBlist [lindex \fIlist first\fB]\fR''
 
 .SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), list(n), llength(n), lreplace(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
+lset(n), lreplace(n), lsort(n)
+.VE
 
 .SH KEYWORDS
 element, list, range, sublist
diff --git a/doc/lreplace.n b/doc/lreplace.n
index ad84672..92dcad7 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.n
@@ -1,11 +1,12 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lreplace.n,v 1.6 2000/09/07 14:27:49 poenitz Exp $
+'\" RCS: @(#) $Id: lreplace.n,v 1.7 2001/11/14 23:15:33 hobbs Exp $
 '\" 
 .so man.macros
 .TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
@@ -44,8 +45,10 @@ between \fIfirst\fR and \fIlast\fR are simply deleted.  If \fIlist\fR
 is empty, any \fIelement\fR arguments are added to the end of the list.
 
 .SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n),
-lsearch(n), lsort(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
+lset(n), lrange(n), lsort(n)
+.VE
 
 .SH KEYWORDS
 element, list, replace
diff --git a/doc/lsearch.n b/doc/lsearch.n
index 4898b4e..16b3ce2 100644
--- a/doc/lsearch.n
+++ b/doc/lsearch.n
@@ -1,11 +1,12 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+.\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lsearch.n,v 1.7 2001/09/10 22:51:40 hobbs Exp $
+'\" RCS: @(#) $Id: lsearch.n,v 1.8 2001/11/14 23:15:33 hobbs Exp $
 '\" 
 .so man.macros
 .TH lsearch n 8.4 Tcl "Tcl Built-In Commands"
@@ -79,8 +80,10 @@ last takes precendence.  If more than one of \fB\-increasing\fR and
 \fB\-decreasing\fR is specified, the option specified last takes precedence.
 
 .SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n),
-lreplace(n), lsort(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), llength(n), 
+lset(n), lsort(n), lrange(n), lreplace(n)
+.VE
 
 .SH KEYWORDS
 list, match, pattern, regular expression, search, string
diff --git a/doc/lset.n b/doc/lset.n
new file mode 100755
index 0000000..38517a1
--- /dev/null
+++ b/doc/lset.n
@@ -0,0 +1,107 @@
+.\" Copyright (c) 2001 by Kevin B. Kenny.  All rights reserved.
+.\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: lset.n,v 1.1 2001/11/14 23:15:33 hobbs Exp $
+'\" 
+.so man.macros
+.TH lset n 8.4 Tcl "Tcl Built-In Commands"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+lset \- Change an element in a list
+.SH SYNOPSIS
+\fBlset \fIlist ?index...? newValue\fR
+.BE
+.SH DESCRIPTION
+.PP
+The \fBlset\fP command accepts a parameter, \fIlist\fP, which
+it interprets as the name of a variable containing a Tcl list. 
+It also accepts zero or more \fIindices\fP into
+the list.  The indices may be presented either consecutively on the
+command line, or grouped in a
+Tcl list and presented as a single argument.
+Finally, it acccepts a new value for an element of \fIlist\fP.
+.PP
+If no indices are presented, the command takes the form:
+.CS
+lset list newValue
+.CE
+or
+.CS
+lset list {} newValue
+.CE
+In this case, \fInewValue\fP replaces the old value of the variable \fIlist\fP.
+.PP
+When presented with a single index, the \fBlset\fR command
+treats the content of the \fIlist\fR variable as a Tcl list.
+It addresses the \fIindex\fR'th element in it 
+(0 refers to the first element of the list).
+When interpreting the list, \fBlset\fR 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 \fInewValue\fP.  This new list is stored in the
+variable \fIlist\fP, and is also the return value from the \fBlset\fP
+command.
+.PP
+If \fIindex\fR is negative or greater than or equal to the number
+of elements in \fI$list\fR, then an error occurs.
+.PP
+If \fIindex\fR has the value \fBend\fR, it refers to the last element
+in the list, and \fBend\-\fIinteger\fR refers to the last element in
+the list minus the specified integer offset.
+.PP
+If additional \fIindex\fR 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,
+.CS
+lset a 1 2 newValue
+.CE
+or
+.CS
+lset a {1 2} newValue
+.CE
+replaces element 2 of sublist 1 with \fInewValue\fP.
+.PP
+The integer appearing in each \fIindex\fR argument must be greater
+than or equal to zero.  The integer appearing in each \fIindex\fR
+argument must be strictly less than the length of the corresponding
+list.  In other words, the \fBlset\fR command cannot change the size
+of a list.  If an index is outside the permitted range, an error is reported.
+.SH EXAMPLES
+In each of these examples, the initial value of \fIx\fP is:
+.CS
+{a b c} {d e f} {g h i}
+.CE
+The indicated return value also becomes the new value of \fIx\fP.
+.CS
+lset x {j k l} => j k l
+lset x {} {j k l} => j k l
+lset x 0 j => j {d e f} {g h i}
+lset x 2 j => {a b c} {d e f} j
+lset x end j => {a b c} {d e f} j
+lset x end-1 j => {a b c} j {d e f}
+lset x 2 1 j => {a b c} {d e f} {g j i}
+lset x {2 1} j => {a b c} {d e f} {g j i}
+lset x {2 3} j
+.CE
+In the following examples, the initial value of \fIx\fP is:
+.CS
+{{a b} {c d}} {{e f} {g h}}
+.CE
+The indicated return value also becomes the new value of \fIx\fP.
+.CS
+lset x 1 1 0 j => {{a b} {c d}} {{e f} {j h}}
+lset x {1 1 0} j => {{a b} {c d}} {{e f} {j h}}
+.CE
+.SH "SEE ALSO"
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
+lsort(n), lrange(n), lreplace(n)
+
+.SH KEYWORDS
+element, index, list, replace, set
+.VE
diff --git a/doc/lsort.n b/doc/lsort.n
index 67f7f09..1278100 100644
--- a/doc/lsort.n
+++ b/doc/lsort.n
@@ -2,11 +2,12 @@
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
 '\" Copyright (c) 1999 Scriptics Corporation
+.\" Copyright (c) 2001 Kevin B. Kenny.  All rights reserved.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: lsort.n,v 1.10 2001/09/28 15:32:17 dkf Exp $
+'\" RCS: @(#) $Id: lsort.n,v 1.11 2001/11/14 23:15:33 hobbs Exp $
 '\" 
 .so man.macros
 .TH lsort n 8.3 Tcl "Tcl Built-In Commands"
@@ -184,8 +185,10 @@ More complex sorting using a comparison function:
 .CE
 
 .SH "SEE ALSO"
-lappend(n), lindex(n), linsert(n), list(n), llength(n), lrange(n),
-lreplace(n), lsearch(n)
+.VS 8.4
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
+lset(n), lrange(n), lreplace(n)
+.VE
 
 .SH KEYWORDS
 element, list, order, sort