1 files changed, 34 insertions, 21 deletions
diff --git a/doc/lreplace.n b/doc/lreplace.n
index 600a986..2cd79d8 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.n
@@ -1,7 +1,7 @@
 '\"
 '\" 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.
+'\" 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.
@@ -15,26 +15,31 @@ 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
 \fIlist\fR with the \fIelement\fR arguments.
-\fIfirst\fR and \fIlast\fR specify the first and last index of the
-range of elements to replace.  0 refers to the first element of the
-list, and \fBend\fR (or any abbreviation of it) may be used to refer
-to the last element of the list.  If \fIlist\fR is empty, then
-\fIfirst\fR and \fIlast\fR are ignored.
-
-If \fIfirst\fR is less than zero, it is considered to refer to the
+.VS 8.5
+\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.
+.VE
+.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.
-
-If \fIlast\fR is less than zero but greater than \fIfirst\fR, then any
-specified elements will be prepended to the list.  If \fIlast\fR is
-less than \fIfirst\fR then no elements are deleted; the new elements
-are simply inserted before \fIfirst\fR.
-
+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
@@ -61,12 +66,20 @@ 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:
+.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"
-.VS 8.4
-list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
-lset(n), lrange(n), lsort(n)
+list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),
+lset(n), lrange(n), lsort(n),
+.VS 8.5
+string(n)
 .VE
-
 .SH KEYWORDS
 element, list, replace