* doc/linsert.n: [Bug 3045123]: Make description of what is actually

	happening more accurate.

1 files changed, 15 insertions, 5 deletions

diff --git a/doc/linsert.n b/doc/linsert.n
index 22ad6ae..9cccab5 100644
--- a/doc/linsert.n
+++ b/doc/linsert.n
@@ -6,7 +6,7 @@
 '\" 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.17 2008/10/17 10:22:25 dkf Exp $
+'\" RCS: @(#) $Id: linsert.n,v 1.18 2010/08/21 16:58:08 dkf Exp $
 '\" 
 .so man.macros
 .TH linsert n 8.2 Tcl "Tcl Built-In Commands"
@@ -23,10 +23,17 @@ This command produces a new list from \fIlist\fR by inserting all of the
 \fIelement\fR arguments just before the \fIindex\fR'th element of
 \fIlist\fR.  Each \fIelement\fR argument will become a separate element of
 the new list.  If \fIindex\fR is less than or equal to zero, then the new
-elements are inserted at the beginning of the list.  
-The interpretation of the \fIindex\fR value is the same as
-for the command \fBstring index\fR, supporting simple index
-arithmetic and indices relative to the end of the list.
+elements are inserted at the beginning of the list, and if \fIindex\fR is
+greater or equal to the length of \fIlist\fR, it is as if it was \fBend\fR.
+As with \fBstring index\fR, the \fIindex\fR value supports both simple index
+arithmetic and end-relative indexing.
+.PP
+Subject to the restrictions that indices must refer to locations inside the
+list and that the \fIelement\fRs will always be inserted in order, insertions
+are done so that when \fIindex\fR is start-relative, the first \fIelement\fR
+will be at that index in the resulting list, and when \fIindex\fR is
+end-relative, the last \fIelement\fR will be at that index in the resulting
+list.
 .SH EXAMPLE
 .PP
 Putting some values into a list, first indexing from the start and
@@ -45,3 +52,6 @@ lset(n), lsort(n), lrange(n), lreplace(n),
 string(n)
 .SH KEYWORDS
 element, insert, list
+'\" Local Variables:
+'\" mode: nroff
+'\" End: