merge 8.7

3 files changed, 163 insertions, 1 deletions

diff --git a/doc/CrtAlias.3 b/doc/CrtAlias.3
index 2623dcd..77a3bc2 100644
--- a/doc/CrtAlias.3
+++ b/doc/CrtAlias.3
@@ -160,6 +160,7 @@ parts, so safety is not guaranteed after calling \fBTcl_MakeSafe\fR.
 Callers will want to take care with their use of \fBTcl_MakeSafe\fR
 to avoid false claims of safety.  For many situations, \fBTcl_CreateChild\fR
 may be a better choice, since it creates interpreters in a known-safe state.
+\fBTcl_MakeSafe\fR is deprecated and will be removed in Tcl 9.0.
 .PP
 \fBTcl_GetChild\fR returns a pointer to a child interpreter of
 \fIinterp\fR. The child interpreter is identified by \fIname\fR.
diff --git a/doc/lseq.n b/doc/lseq.n
new file mode 100644
index 0000000..5c7d03b
--- /dev/null
+++ b/doc/lseq.n
@@ -0,0 +1,92 @@
+'\"
+'\" 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 an inclusive range. The "count" option is used
+to define a count of the number of elements in the list. The short form with a
+single count value will create a range from 0 to count-1.
+
+The numeric arguments, \fIStart\fR, \fIEnd\fR, \fIStep\fR, and \fICount\fR,
+can also be a valid expression. the lseq command will evaluate the expression
+and use the numeric result, or return an error as with any invalid argument
+value. A valid expression is a valid [expr] expression, however, the result
+must be numeric; a non-numeric string will result in an 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 i 17
+ \(-> 17
+ if {$i in [lseq 0 50]} { # equivalent to: (0 <= $i && $i < 50)
+     puts "Ok"
+ } else {
+     puts "outside :("
+ }
+ \(-> Ok
+
+ 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:
diff --git a/doc/vwait.n b/doc/vwait.n
index f64d39c..5f240d6 100644
--- a/doc/vwait.n
+++ b/doc/vwait.n
@@ -12,6 +12,8 @@
 vwait \- Process events until a variable is written
 .SH SYNOPSIS
 \fBvwait\fR \fIvarName\fR
+.PP
+\fBvwait\fR ?\Ioptions\fR? ?\fIvarName ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
@@ -24,8 +26,75 @@ command will return as soon as the event handler that modified
 a variable name with respect to the global namespace, but can refer to any
 namespace's variables if the fully-qualified name is given.
 .PP
+In the second more complex command form \fIoptions\fR allow for finer
+control of the wait operation and to deal with multiple event sources.
+\fIOptions\fR can be made up of
+.TP
+\fB\-\-\fR
+.
+Marks the end of options. All following arguments are handled as
+variable names.
+.TP
+\fB\-all\fR
+.
+All conditions for the wait operation must be met to complete the
+wait operation. Otherwise (the default) the first event completes
+the wait.
+.TP
+\fB\-extended\fR
+.
+An extended result in list form is returned, see below for explanation.
+.TP
+\fB\-nofileevents\fR
+.
+File events are not handled in the wait operation.
+.TP
+\fB\-noidleevents\fR
+.
+Idle handlers are not invoked during the wait operation.
+.TP
+\fB\-notimerevents\fR
+.
+Timer handlers are not serviced during the wait operation.
+.TP
+\fB\-nowindowevents\fR
+.
+Events of the windowing system are not handled during the wait operation.
+.TP
+\fB\-readable\fR \fIchannel\fR
+.
+\fIChannel\fR must name a Tcl channel open for reading. If \fIchannel\fR
+is or becomes readable the wait operation completes.
+.TP
+\fB\-timeout\fR milliseconds\fR
+.
+The wait operation is constrained to \fImilliseconds\fR.
+.TP
+\fB\-variable\fR \fIvarName\fR
+.
+\fIVarName\fR must be the name of a global variable. Writing or
+unsetting this variable completes the wait operation.
+.TP
+\fB\-writable\fR \fIchannel\fR
+.
+\fIChannel\fR must name a Tcl channel open for writing. If \fIchannel\fR
+is or becomes writable the wait operation completes.
+.PP
+The result returned by \fBvwait\fR is for the simple form an empty
+string. If the \fI\-timeout\fR option is specified, the result is the
+number of milliseconds remaining when the wait condition has been
+met, or -1 if the wait operation timed out.
+.PP
+If the \fI\-extended\fR option is specified, the result is made up
+of a Tcl list with an even number of elements. Odd elements
+take the values \fBreadable\fR, \fBtimeleft\fR, \fBvariable\fR,
+and \fBwritable\fR. Even elements are the corresponding variable
+and channel names or the remaining number of milliseconds.
+The list is ordered by the occurrences of the event(s) with the
+exception of \fBtimeleft\fR which always comes last.
+.PP
 In some cases the \fBvwait\fR command may not return immediately
-after \fIvarName\fR is set.  This happens if the event handler
+after \fIvarName\fR et.al. is set. This happens if the event handler
 that sets \fIvarName\fR does not complete immediately.  For example,
 if an event handler sets \fIvarName\fR and then itself calls
 \fBvwait\fR to wait for a different variable, then it may not return