Changed the phrasing of some blocks making them easier to understand.

Thanks to Christopher Nelson for his feedback.

1 files changed, 39 insertions, 37 deletions

diff --git a/doc/StdChannels.3 b/doc/StdChannels.3
index 0945368..b22fb99 100644
--- a/doc/StdChannels.3
+++ b/doc/StdChannels.3
@@ -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.
 '\" 
-'\" RCS: @(#) $Id: StdChannels.3,v 1.1 2001/09/10 21:49:37 andreas_kupries Exp $
+'\" RCS: @(#) $Id: StdChannels.3,v 1.2 2001/09/10 23:30:32 andreas_kupries Exp $
 '\" 
 .so man.macros
 .TH Standard channels 3 7.5 Tcl "Tcl Library Procedures"
@@ -34,56 +34,58 @@ APIs to consider are \fBTcl_RegisterChannel\fR,
 \fBTcl_CreateChannel\fR and \fBTcl_GetChannel\fR.
 .SH Initialization of Tcl standard channels
 .PP
-There are several ways for the Tcl standard channels to be
-initialized, described below. Each of these deals differently with the
-situation of having no platform-specific standard channels available.
-A channel is not "available" if it could not be successfully opened;
-for example, in a Tcl application run as a Windows NT service.
+Standard channels are initialized by the Tcl library in three cases:
+when explicitly requested, when implicitly required before returning
+channel information, or when implicitly required during registration a
+new channel.
+.PP
+These cases differ in how they handle unavailable platform- specific
+standard channels.  (A channel is not "available" if it could not be
+successfully opened; for example, in a Tcl application run as a
+Windows NT service.)
 .TP
 1)
-The application using the Tcl library explicitly specifies the Tcl
-channels to use as standard channels by calling
-\fBTcl_SetStdChannel\fR.  Missing platform-specific standard channels
-do not matter here. This approach is not available at the script
-level.
+A single standard channel is initialized when it is explicitly
+specified in a call to \fBTcl_SetStdChannel\fR.  The state of the
+other standard channels are unaffected.
+.sp
+Missing platform-specific standard channels do not matter here. This
+approach is not available at the script level.
+.TP
+2)
+All uninitialized standard channels are initialized to
+platform-specific default values:
+.RS
+.TP
+(a)
+when open channels are listed with \fBTcl_GetChannelNames\fR (or the
+\fBfile channels\fR script command), or
 .TP
-2a)
-The application asks for one of the Tcl standard channels by calling
-\fBTcl_GetStdChannel\fR. This will initialize any of them which were
-not initialized before to their platform-dependent default values.
+(b)
+when information about any standard channel is requested with a call
+to \fBTcl_GetStdChannel\fR, or with a call to \fBTcl_GetChannel\fR
+which specifies one of the standard names (\fBstdin\fR, \fBstdout\fR
+and \fBstderr\fR).
+.RE
 .sp
+.RS
 In case of missing platform-specific standard channels, the Tcl
 standard channels are considered as initialized and then immediately
 closed. This means that the first three Tcl channels then opened by
 the application are designated as the Tcl standard channels.
-.TP
-2b)
-This is a special case of (2a). The initialization mentioned there
-will also happen whenever \fBTcl_GetChannel\fR is called with one of
-the standard names \fBstdin\fR, \fBstdout\fR and \fBstderr\fR as the
-name of the channel to retrieve. This happens whenever a command
-expecting a channel handle gets one of the standard names as its
-argument.
-.TP
-2c)
-Introspection of the list of open channels via \fBfile channels\fR (or
-\fBTcl_GetChannelNames\fR) will also initialize the Tcl standard
-channels to their platform-dependent default values.
+.RE
 .TP
 3)
-If the application does neither of the above the Tcl library will
-setup and initialize the Tcl standard channels to their platform
-dependent default values during the creation of the first
-user-requested channel. This happens inside of
-\fBTcl_RegisterChannel\fR.
+All uninitialized standard channels are initialized to
+platform-specific default values when a user-requested channel is
+registered with \fBTcl_RegisterChannel\fR.
 .sp
-In case of missing platform-specific standard channels the channel
+In case of unavailable platform-specific standard channels the channel
 whose creation caused the initialization of the Tcl standard channels
-is made a normal channel. The next three Tcl channels opened by the
-application are designated as the Tcl standard channels. In other
+is made a normal channel.  The next three Tcl channels opened by the
+application are designated as the Tcl standard channels.  In other
 words, of the first four Tcl channels opened by the application the
 second to fourth are designated as the Tcl standard channels.
-
 .PP
 .SH Re-initialization of Tcl standard channels
 .PP