1 files changed, 104 insertions, 0 deletions
diff --git a/doc/lseq.n b/doc/lseq.n
new file mode 100644
index 0000000..e6ba7a6
--- /dev/null
+++ b/doc/lseq.n
@@ -0,0 +1,104 @@
+'\"
+'\" Copyright (c) 2022 Eric Taylor.  All rights reserved.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+.TH lseq n 8.7 Tcl "Tcl Built-In Commands"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+lseq \- Build a numeric sequence returned as a list
+.SH SYNOPSIS
+\fBlseq \fIStart \fR?(\fB..\fR|\fBto\fR)? \fIEnd\fR ??\fBby\fR? \fIStep\fR?
+
+\fBlseq \fIStart \fBcount\fR \fICount\fR ??\fBby\fR? \fIStep\fR?
+
+\fBlseq \fICount\fR ?\fBby \fIStep\fR?
+.BE
+.SH DESCRIPTION
+.PP
+The \fBlseq\fR command creates a sequence of numeric values using the given
+parameters \fIStart\fR, \fIEnd\fR, and \fIStep\fR. The \fIoperation\fR
+argument ".." or "to" defines the range. The "count" option is used
+to define a count of the number of elements in the list. A short form use of
+the command, with a
+single count value, will create a range from 0 to count-1.
+
+The \fBlseq\fR command can produce both increasing and decreasing sequences. When
+both Start and End are provided without a Step value, then if Start <= End,
+the sequence will be increasing and if Start > End it will be decreasing. If a
+Step vale is included, it's sign should agree with the direction of the
+sequence (descending -> negative and ascending -> positive), otherwise an
+empty list is returned.  For example:
+
+.CS \"
+    % lseq 1 to 5    ;# increasing
+    1 2 3 4 5
+
+    % lseq 5 to 1    ;# decreasing
+    5 4 3 2 1
+
+    % lseq 6 to 1 by 2   ;# decreasing, step wrong sign, empty list
+
+    % lseq 1 to 5 by 0   ;# all step sizes of 0 produce an empty list
+
+.\"
+.CE
+
+The numeric arguments, \fIStart\fR, \fIEnd\fR, \fIStep\fR, and \fICount\fR,
+may also be a valid expression. The expression will be evaluate and the
+numeric result be used.  An expression that does not evaluate to a number will
+produce an invalid argument error.
+
+.SH EXAMPLES
+.CS
+.\"
+
+ lseq 3
+ \(-> 0 1 2
+
+ lseq 3 0
+ \(-> 3 2 1 0
+
+ lseq 10 .. 1 by -2
+ \(-> 10 8 6 4 2
+
+ set l [lseq 0 -5]
+ \(-> 0 -1 -2 -3 -4 -5
+
+ foreach i [lseq [llength $l]] {
+   puts l($i)=[lindex $l $i]
+ }
+ \(-> l(0)=0
+    l(1)=-1
+    l(2)=-2
+    l(3)=-3
+    l(4)=-4
+    l(5)=-5
+
+ foreach i [lseq [llength $l]-1 0] {
+    puts l($i)=[lindex $l $i]
+ }
+ \(-> l(5)=-5
+    l(4)=-4
+    l(3)=-3
+    l(2)=-2
+    l(1)=-1
+    l(0)=0
+
+ set sqrs [lmap i [lseq 1 10] {expr $i*$i}]
+ \(-> 1 4 9 16 25 36 49 64 81 100
+.\"
+.CE
+.SH "SEE ALSO"
+foreach(n), list(n), lappend(n), lassign(n), lindex(n), linsert(n), llength(n),
+lmap(n), lpop(n), lrange(n), lremove(n), lreplace(n),
+lreverse(n), lsearch(n), lset(n), lsort(n)
+.SH KEYWORDS
+element, index, list
+'\" Local Variables:
+'\" mode: nroff
+'\" fill-column: 78
+'\" End: