Add more examples to documentation along the lines of David Welton's project.

6 files changed, 110 insertions, 5 deletions

diff --git a/ChangeLog b/ChangeLog
index 35d96cf..00337df 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2004-04-16  Donal K. Fellows  <donal.k.fellows@man.ac.uk>
+
+	* doc/lreplace.n, doc/lrange.n, doc/llength.n:	More examples for
+	* doc/linsert.n, doc/lappend.n:			the documentation.
+
 2004-04-16  Vince Darley  <vincentdarley@users.sourceforge.net>
 
 	* doc/FileSystem.3: Corrected documentation of Tcl_FSUtime, and
diff --git a/doc/lappend.n b/doc/lappend.n
index 6a0d9bc..90cf6f9 100644
--- a/doc/lappend.n
+++ b/doc/lappend.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: lappend.n,v 1.6 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: lappend.n,v 1.7 2004/04/16 22:20:58 dkf Exp $
 '\" 
 .so man.macros
 .TH lappend n "" Tcl "Tcl Built-In Commands"
@@ -32,6 +32,18 @@ large lists.  For example, ``\fBlappend a $b\fR'' is much
 more efficient than ``\fBset a [concat $a [list $b]]\fR'' when
 \fB$a\fR is long.
 
+.SH EXAMPLE
+Using \fBlappend\fR to build up a list of numbers.
+
+.CS
+% set var 1
+1
+% lappend var 2
+1 2
+% lappend var 3 4 5
+1 2 3 4 5
+.CE
+
 .SH "SEE ALSO"
 list(n), lindex(n), linsert(n), llength(n), 
 .VS 8.4
diff --git a/doc/linsert.n b/doc/linsert.n
index 3a0a66d..eca0acc 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.7 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: linsert.n,v 1.8 2004/04/16 22:20:58 dkf Exp $
 '\" 
 .so man.macros
 .TH linsert n 8.2 Tcl "Tcl Built-In Commands"
@@ -30,6 +30,17 @@ 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 EXAMPLE
+Putting some values into a list, first indexing from the start and
+then indexing from the end, and then chaining them together:
+
+.CS
+set oldList {the fox jumps over the dog}
+set midList [linsert $oldList 1 quick]
+set newList [linsert $midList end-1 lazy]
+# The old lists still exist though...
+set newerList [linsert [linsert $oldList end-1 quick] 1 lazy]
+.CE
 
 .SH "SEE ALSO"
 .VS 8.4
diff --git a/doc/llength.n b/doc/llength.n
index 68dd1d8..f784614 100644
--- a/doc/llength.n
+++ b/doc/llength.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: llength.n,v 1.6 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: llength.n,v 1.7 2004/04/16 22:20:58 dkf Exp $
 '\" 
 .so man.macros
 .TH llength n "" Tcl "Tcl Built-In Commands"
@@ -23,6 +23,32 @@ llength \- Count the number of elements in a list
 Treats \fIlist\fR as a list and returns a decimal string giving
 the number of elements in it.
 
+.SH EXAMPLES
+The result is the number of elements:
+.CS
+% llength {a b c d e}
+5
+% llength {a b c}
+3
+% llength {}
+0
+.CE
+
+Elements are not guaranteed to be exactly words in a dictionary sense
+of course, especially when quoting is used:
+.CS
+% llength {a b {c d} e}
+4
+% llength {a b { } c d e}
+6
+.CE
+
+An empty list is not necessarily an empty string:
+.CS
+% set var { }; puts "[string length $var],[llength $var]"
+1,0
+.CE
+
 .SH "SEE ALSO"
 .VS 8.4
 list(n), lappend(n), lindex(n), linsert(n), lsearch(n), 
diff --git a/doc/lrange.n b/doc/lrange.n
index bafc0a2..e2ec3eb 100644
--- a/doc/lrange.n
+++ b/doc/lrange.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: lrange.n,v 1.6 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: lrange.n,v 1.7 2004/04/16 22:20:58 dkf Exp $
 '\" 
 .so man.macros
 .TH lrange n 7.4 Tcl "Tcl Built-In Commands"
@@ -36,6 +36,36 @@ same result as ``\fBlindex \fIlist first\fR'' (although it often does
 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 EXAMPLES
+Selecting the first two elements:
+.CS
+% lrange {a b c d e} 0 1
+a b
+.CS
+
+Selecting the last three elements:
+.CS
+% lrange {a b c d e} end-2 end
+c d e
+.CE
+
+Selecting everything except the first and last element:
+.CS
+% lrange {a b c d e} 1 end-1
+b c d
+.CE
+
+Selecting a single element with \fBlrange\fR is not the same as doing
+so with \fBlindex\fR:
+.CS
+% set var {some {elements to} select}
+some {elements to} select
+% lindex $var 1
+elements to
+% lrange $var 1 1
+{elements to}
+.CE
+
 .SH "SEE ALSO"
 .VS 8.4
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n), 
diff --git a/doc/lreplace.n b/doc/lreplace.n
index 02164ac..6ddec46 100644
--- a/doc/lreplace.n
+++ b/doc/lreplace.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: lreplace.n,v 1.8 2001/11/14 23:38:39 hobbs Exp $
+'\" RCS: @(#) $Id: lreplace.n,v 1.9 2004/04/16 22:20:58 dkf Exp $
 '\" 
 .so man.macros
 .TH lreplace n 7.4 Tcl "Tcl Built-In Commands"
@@ -44,6 +44,27 @@ 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
+Replacing an element of a list with another:
+.CS
+% lreplace {a b c d e} 1 1 foo
+a foo c d e
+.CE
+
+Replacing two elements of a list with three:
+.CS
+% lreplace {a b c d e} 1 2 three more elements
+a three more elements d e
+.CE
+
+Deleting the last element from a list in a variable:
+.CS
+% set var {a b c d e}
+a b c d e
+% set var [lreplace $var end end]
+a b c d
+.CE
+
 .SH "SEE ALSO"
 .VS 8.4
 list(n), lappend(n), lindex(n), linsert(n), llength(n), lsearch(n),