From f27a9b65d779c70b127229e413aec5c49b6b2aca Mon Sep 17 00:00:00 2001
From: dkf <donal.k.fellows@manchester.ac.uk>
Date: Thu, 27 Sep 2018 07:44:50 +0000
Subject: Updated documentation

---
 doc/lreplace.n | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/doc/lreplace.n b/doc/lreplace.n
index d19f0cd..35a9130 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.n
@@ -30,13 +30,26 @@ 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
+first element of the list.
+.VS TIP505
+If \fIfirst\fR indicates a position greater than the index of the last element
+of the list, it is treated as if it is an index one greater than the last
+element. This allows this command to append elements to the list.
+.VE TIP505
+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 before the point specified by \fIfirst\fR
 with no elements being deleted.
+.VS TIP505
+If \fIlast\fR is greater than the index of the last item of the list, it is
+treated as if it is an index one greater than the last element. This means
+that if it is also greater than than \fIfirst\fR, all elements from
+\fIfirst\fR to the end of the list will be replaced, and otherwise the
+elements will be appended.
+.VE TIP505
 .PP
 The \fIelement\fR arguments specify zero or more new arguments to
 be added to the list in place of those that were deleted.
@@ -78,9 +91,26 @@ proc lremove {listVariable value} {
     set var [\fBlreplace\fR $var $idx $idx]
 }
 .CE
+.PP
+.VS TIP505
+Adding elements to the end of the list; note that \fBend+2\fR will initially
+be treated as if it is \fB6\fR here, but both that and \fB12345\fR are greater
+than the index of the final item so they behave identically:
+.PP
+.CS
+% set var {a b c d e}
+a b c d e
+% set var [\fBlreplace\fR $var 12345 end+2 f g h i]
+a b c d e f g h i
+.CE
+.VE TIP505
 .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
+.\" Local variables:
+.\" mode: nroff
+.\" fill-column: 78
+.\" End:
-- 
cgit v0.12