From f3f254e8bab8854467fda3c5a2c48a640fb7687c Mon Sep 17 00:00:00 2001 From: dkf Date: Mon, 22 May 2023 07:48:43 +0000 Subject: Small documentation corrections --- doc/chan.n | 19 ++++++++-- doc/close.n | 21 +++++++---- doc/configurable.n | 2 +- doc/link.n | 14 ++++---- doc/lremove.n | 2 +- doc/lseq.n | 103 ++++++++++++++++++++++++++++------------------------- 6 files changed, 95 insertions(+), 66 deletions(-) diff --git a/doc/chan.n b/doc/chan.n index 1ecef4c..70f451d 100644 --- a/doc/chan.n +++ b/doc/chan.n @@ -55,7 +55,9 @@ channel is flushed in the background before finally being closed. .PP \fBchan close\fR may return an error if an error occurs while flushing output. If a process in a command pipeline created by \fBopen\fR returns an -error, \fBchan close\fR generates an error in the same manner as \fBexec\fR. +error (either by returning a non-zero exit code or writing to its standard +error file descriptor), \fBchan close\fR generates an error in the same +manner as \fBexec\fR. .PP Closing one side of a socket or command pipeline may lead to the shutdown() or close() of the underlying system resource, leading to a reaction from whatever @@ -70,6 +72,17 @@ description of channel sharing. .PP When the last interpreter sharing a channel is destroyed, the channel is switched to blocking mode and fully flushed and then closed. +.PP +Channels are automatically closed when an interpreter is destroyed and +when the process exits. +From 8.6 on (TIP#398), nonblocking channels are no longer switched to +blocking mode when exiting; this guarantees a timely exit even when the +peer or a communication channel is stalled. To ensure proper flushing of +stalled nonblocking channels on exit, one must now either (a) actively +switch them back to blocking or (b) use the environment variable +\fBTCL_FLUSH_NONBLOCKING_ON_EXIT\fR, which when set and not equal to +.QW \fB0\fR +restores the previous behavior. .RE .TP \fBchan configure \fIchannelName\fR ?\fIoptionName\fR? ?\fIvalue\fR? ?\fIoptionName value\fR?... @@ -288,8 +301,8 @@ first words of a command that provides the interface for a \fBrefchan\fR. \fBImode\fR is a list of one or more of the strings .QW \fBread\fR or -.QW \fBwrite\fR -, indicating whether the channel is a read channel, a write channel, or both. +.QW \fBwrite\fR , +indicating whether the channel is a read channel, a write channel, or both. It is an error if the handler does not support the chosen mode. .PP The handler is called as needed from the global namespace at the top level, and diff --git a/doc/close.n b/doc/close.n index 3d18aea..2066583 100644 --- a/doc/close.n +++ b/doc/close.n @@ -12,11 +12,12 @@ .SH NAME close \- Close an open channel .SH SYNOPSIS -\fBclose \fIchannelId\fR ?r(ead)|w(rite)? +\fBclose \fIchannelId\fR ?\fBr\fR(\fBead\fR)|\fBw\fR(\fBrite\fR)? .BE .SH DESCRIPTION .PP -Closes or half-closes the channel given by \fIchannelId\fR. +Closes or half-closes the channel given by \fIchannelId\fR. \fBchan close\fR +is another name for this command. .PP \fIChannelId\fR must be an identifier for an open channel such as a Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), @@ -49,12 +50,20 @@ When the last interpreter in which the channel is registered invokes .PP Channels are automatically closed when an interpreter is destroyed and when the process exits. -From 8.6 on (TIP#398), nonblocking channels are no longer switched to blocking mode when exiting; this guarantees a timely exit even when the peer or a communication channel is stalled. To ensure proper flushing of stalled nonblocking channels on exit, one must now either (a) actively switch them back to blocking or (b) use the environment variable TCL_FLUSH_NONBLOCKING_ON_EXIT, which when set and not equal to "0" restores the previous behavior. +From 8.6 on (TIP#398), nonblocking channels are no longer switched to +blocking mode when exiting; this guarantees a timely exit even when the +peer or a communication channel is stalled. To ensure proper flushing of +stalled nonblocking channels on exit, one must now either (a) actively +switch them back to blocking or (b) use the environment variable +\fBTCL_FLUSH_NONBLOCKING_ON_EXIT\fR, which when set and not equal to +.QW \fB0\fR +restores the previous behavior. .PP The command returns an empty string, and may generate an error if an error occurs while flushing output. If a command in a command -pipeline created with \fBopen\fR returns an error, \fBclose\fR -generates an error (similar to the \fBexec\fR command.) +pipeline created with \fBopen\fR returns an error (either by returning a +non-zero exit code or writing to its standard error file descriptor), +\fBclose\fR generates an error (similar to the \fBexec\fR command.) .PP The two-argument form is a .QW "half-close" : @@ -95,7 +104,7 @@ proc withOpenFile {filename channelVar script} { } .CE .SH "SEE ALSO" -file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3) +chan(n), file(n), open(n), socket(n), eof(n), Tcl_StandardChannels(3) .SH KEYWORDS blocking, channel, close, nonblocking, half-close '\" Local Variables: diff --git a/doc/configurable.n b/doc/configurable.n index 6477894..a138c33 100644 --- a/doc/configurable.n +++ b/doc/configurable.n @@ -4,7 +4,7 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -.TH configurable n 0.1 TclOO "TclOO Commands" +.TH configurable n 0.4 TclOO "TclOO Commands" .so man.macros .BS '\" Note: do not modify the .SH NAME line immediately below! diff --git a/doc/link.n b/doc/link.n index e06be33..a11c261 100644 --- a/doc/link.n +++ b/doc/link.n @@ -52,11 +52,11 @@ oo::class create ABC { constructor {} { \fBlink\fR Foo - # The method foo is now directly accessible as foo here + # The method Foo is now directly accessible as Foo here \fBlink\fR {bar Foo} - # The method foo is now directly accessible as bar + # The method Foo is now directly accessible as bar \fBlink\fR {::ExternalCall Foo} - # The method foo is now directly accessible in the global + # The method Foo is now directly accessible in the global # namespace as ExternalCall } @@ -71,13 +71,13 @@ oo::class create ABC { ABC create abc abc grill \fI\(-> Step 1:\fR - \fI\(-> This is foo in ::abc\fR + \fI\(-> This is Foo in ::abc\fR \fI\(-> Step 2:\fR - \fI\(-> This is foo in ::abc\fR + \fI\(-> This is Foo in ::abc\fR # Direct access via the linked command puts "Step 3:"; ExternalCall \fI\(-> Step 3:\fR - \fI\(-> This is foo in ::abc\fR + \fI\(-> This is Foo in ::abc\fR .CE .PP This example shows that multiple linked commands can be made in a call to @@ -88,7 +88,7 @@ oo::class create Ex { constructor {} { \fBlink\fR a b c # The methods a, b, and c (defined below) are all now - # directly acessible within methods under their own names. + # directly accessible within methods under their own names. } method a {} { diff --git a/doc/lremove.n b/doc/lremove.n index 8763ea6..bd4a5eb 100644 --- a/doc/lremove.n +++ b/doc/lremove.n @@ -16,7 +16,7 @@ lremove \- Remove elements from a list by index .SH DESCRIPTION .PP \fBlremove\fR returns a new list formed by simultaneously removing zero or -more elements of \fIlist\fR at each of the indices given by an arbirary number +more elements of \fIlist\fR at each of the indices given by an arbitrary number of \fIindex\fR arguments. The indices may be in any order and may be repeated; the element at index will only be removed once. The index values are interpreted the same as index values for the command \fBstring index\fR, diff --git a/doc/lseq.n b/doc/lseq.n index df8a8bc..08be86f 100644 --- a/doc/lseq.n +++ b/doc/lseq.n @@ -11,73 +11,80 @@ .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 \fR?(\fB..\fR|\fBto\fR)? \fIend\fR ??\fBby\fR? \fIstep\fR? -\fBlseq \fIStart \fBcount\fR \fICount\fR ??\fBby\fR? \fIStep\fR? +\fBlseq \fIstart \fBcount\fR \fIcount\fR ??\fBby\fR? \fIstep\fR? -\fBlseq \fICount\fR ?\fBby \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 +parameters \fIstart\fR, \fIend\fR, and \fIstep\fR. +The \fIoperation\fR argument +.QW \fB..\fR +or +.QW \fBto\fR +defines an inclusive range; if it is omitted, the range is exclusive. +The \fBcount\fR option is used to define a count of the number of elements in +the list. +The \fIstep\fR (which may be preceded by \fBby\fR) is 1 if not provided. +The short form with a +single \fIcount\fR value will create a range from 0 to \fIcount\fR-1 (i.e., +\fIcount\fR values). +.PP +The numeric arguments, \fIstart\fR, \fIend\fR, \fIstep\fR, and \fIcount\fR, +can also be a valid expression. the \fBlseq\fR command will evaluate the +expression (as if with \fBexpr\fR) 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. +value; a non-numeric expression result will result in an error. .SH EXAMPLES .CS .\" +\fBlseq\fR 3 + \fI\(-> 0 1 2\fR - lseq 3 - \(-> 0 1 2 +\fBlseq\fR 3 0 + \fI\(-> 3 2 1 0\fR - lseq 3 0 - \(-> 3 2 1 0 +\fBlseq\fR 10 .. 1 by -2 + \fI\(-> 10 8 6 4 2\fR - lseq 10 .. 1 by -2 - \(-> 10 8 6 4 2 +set l [\fBlseq\fR 0 -5] + \fI\(-> 0 -1 -2 -3 -4 -5\fR - 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 [\fBlseq\fR [llength $l]] { + puts l($i)=[lindex $l $i] +} + \fI\(-> l(0)=0\fR + \fI\(-> l(1)=-1\fR + \fI\(-> l(2)=-2\fR + \fI\(-> l(3)=-3\fR + \fI\(-> l(4)=-4\fR + \fI\(-> l(5)=-5\fR - foreach i [lseq [llength $l]-1 0] { +foreach i [\fBlseq\fR {[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 +} + \fI\(-> l(5)=-5\fR + \fI\(-> l(4)=-4\fR + \fI\(-> l(3)=-3\fR + \fI\(-> l(2)=-2\fR + \fI\(-> l(1)=-1\fR + \fI\(-> l(0)=0\fR - set i 17 - \(-> 17 - if {$i in [lseq 0 50]} { # equivalent to: (0 <= $i && $i < 50) - puts "Ok" - } else { - puts "outside :(" - } - \(-> Ok +set i 17 + \fI\(-> 17\fR +if {$i in [\fBlseq\fR 0 50]} { # equivalent to: (0 <= $i && $i < 50) + puts "Ok" +} else { + puts "outside :(" +} + \fI\(-> Ok\fR - set sqrs [lmap i [lseq 1 10] {expr $i*$i}] - \(-> 1 4 9 16 25 36 49 64 81 100 +set sqrs [lmap i [\fBlseq\fR 1 10] { expr {$i*$i} }] + \fI\(-> 1 4 9 16 25 36 49 64 81 100\fR .\" .CE .SH "SEE ALSO" -- cgit v0.12