1 files changed, 64 insertions, 21 deletions
diff --git a/doc/lreplace.n b/doc/lreplace.n
index 9977a90..7bba543 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.n
@@ -1,14 +1,13 @@
 '\"
 '\" Copyright (c) 1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.  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.2 1998/09/14 18:39:53 stanton Exp $
-'\" 
-.so man.macros
+'\"
 .TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
+.so man.macros
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
@@ -16,28 +15,72 @@ lreplace \- Replace elements in a list with new elements
 .SH SYNOPSIS
 \fBlreplace \fIlist first last \fR?\fIelement element ...\fR?
 .BE
-
 .SH DESCRIPTION
 .PP
-\fBLreplace\fR returns a new list formed by replacing one or more elements of
+\fBlreplace\fR returns a new list formed by replacing one or more elements of
 \fIlist\fR with the \fIelement\fR arguments.
-\fIFirst\fR gives the index in \fIlist\fR of the first element
-to be replaced (0 refers to the first element).
-If \fIfirst\fR is less than zero then it refers to the first
-element of \fIlist\fR;  the element indicated by \fIfirst\fR
-must exist in the list.
-\fILast\fR gives the index in \fIlist\fR of the last element
-to be replaced.
-If \fIlast\fR is less than \fIfirst\fR then no elements are deleted;
-the new elements are simply inserted before \fIfirst\fR.
-\fIFirst\fR or \fIlast\fR may be \fBend\fR
-(or any abbreviation of it) to refer to the last element of the list.
+\fIfirst\fR and \fIlast\fR are index values specifying the first and
+last elements of the range to replace.
+The index values \fIfirst\fR and \fIlast\fR are interpreted
+the same as index values for the command \fBstring index\fR,
+supporting simple index arithmetic and indices relative to the
+end of the list.
+0 refers to the first element of the
+list, and \fBend\fR refers to the last element of the list.
+If \fIlist\fR is empty, then \fIfirst\fR and \fIlast\fR are ignored.
+.PP
+If \fIfirst\fR is less than zero, it is considered to refer to before the
+first element of the list.  For non-empty lists, the element indicated
+by \fIfirst\fR must exist or \fIfirst\fR must indicate before the
+start of the list.
+.PP
+If \fIlast\fR is less than \fIfirst\fR, then any specified elements
+will be inserted into the list at the point specified by \fIfirst\fR
+with no elements being deleted.
+.PP
 The \fIelement\fR arguments specify zero or more new arguments to
 be added to the list in place of those that were deleted.
 Each \fIelement\fR argument will become a separate element of
-the list.
-If no \fIelement\fR arguments are specified, then the elements
-between \fIfirst\fR and \fIlast\fR are simply deleted.
-
+the list.  If no \fIelement\fR arguments are specified, then the elements
+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 EXAMPLES
+.PP
+Replacing an element of a list with another:
+.PP
+.CS
+% \fBlreplace\fR {a b c d e} 1 1 foo
+a foo c d e
+.CE
+.PP
+Replacing two elements of a list with three:
+.PP
+.CS
+% \fBlreplace\fR {a b c d e} 1 2 three more elements
+a three more elements d e
+.CE
+.PP
+Deleting the last element from a list in a variable:
+.PP
+.CS
+% set var {a b c d e}
+a b c d e
+% set var [\fBlreplace\fR $var end end]
+a b c d
+.CE
+.PP
+A procedure to delete a given element from a list:
+.PP
+.CS
+proc lremove {listVariable value} {
+    upvar 1 $listVariable var
+    set idx [lsearch -exact $var $value]
+    set var [\fBlreplace\fR $var $idx $idx]
+}
+.CE
+.SH "SEE ALSO"
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
+lset(n), lrange(n), lsort(n),
+string(n)
 .SH KEYWORDS
 element, list, replace