Improve documentation of [tcl::process]

1 files changed, 54 insertions, 35 deletions

diff --git a/doc/process.n b/doc/process.n
index 536b98b..165e413 100644
--- a/doc/process.n
+++ b/doc/process.n
@@ -16,11 +16,31 @@ tcl::process \- Subprocess management
 .SH DESCRIPTION
 .PP
 This command provides a way to manage subprocesses created by the \fBopen\fR
-and \fBexec\fR commands. The legal \fIoptions\fR (which may be abbreviated) are:
+and \fBexec\fR commands, as identified by the process identifiers (PIDs) of
+those subprocesses. The legal \fIoptions\fR (which may be abbreviated) are:
+.TP
+\fB::tcl::process autopurge\fR ?\fIflag\fR?
+.
+Automatic purge facility. If \fIflag\fR is specified as a boolean value then
+it activates or deactivate autopurge. In all cases it returns the current
+status as a boolean value. When autopurge is active,
+\fBTcl_ReapDetachedProcs\fR is called each time the \fBexec\fR command is
+executed or a pipe channel created by \fBopen\fR is closed. When autopurge is
+inactive, \fB::tcl::process\fR purge must be called explicitly. By default
+autopurge is active.
 .TP
 \fB::tcl::process list\fR
 .
-Returns the list of subprocess PIDs.
+Returns the list of subprocess PIDs. This includes all currently executing
+subprocesses and all terminated subprocesses that have not yet had their
+corresponding process table entries purged.
+.TP
+\fB::tcl::process purge\fR ?\fIpids\fR?
+.
+Cleans up all data associated with terminated subprocesses. If \fIpids\fR is
+specified as a list of PIDs then the command only cleanup data for the matching
+subprocesses if they exist, and raises an error otherwise. If a process listed is
+still active, this command does nothing to that process.
 .TP
 \fB::tcl::process status\fR ?\fIswitches\fR? ?\fIpids\fR?
 .
@@ -29,62 +49,48 @@ Returns a dictionary mapping subprocess PIDs to their respective status. If
 status of the matching subprocesses if they exist, and raises an error
 otherwise. For active processes, the status is an empty value. For terminated
 processes, the status is a list with the following format:
-.QW "{code ?\fImsg errorCode\fR?}" ,
+.QW "\fB{\fIcode\fR ?\fImsg errorCode\fR?\fB}\fR" ,
 where:
 .RS
 .TP
-\fBcode\fR\0
+\fIcode\fR\0
 .
-is a standard Tcl return code,
+is a standard Tcl return code, i.e., \fB0\fR for TCL_OK and \fB1\fR
+for TCL_ERROR,
 .TP
-\fBmsg\fR\0
+\fImsg\fR\0
 .
 is the human-readable error message,
 .TP
-\fBerrorCode\fR\0
+\fIerrorCode\fR\0
 .
 uses the same format as the \fBerrorCode\fR global variable
-.RE
+.PP
 Note that \fBmsg\fR and \fBerrorCode\fR are only present for abnormally
-terminated processes (i.e. those where \fBcode\fR is nonzero). Under the hood
-this command calls \fBTcl_WaitPid\fR with the \fBWNOHANG\fR flag set for
+terminated processes (i.e. those where the \fIcode\fR is nonzero). Under the
+hood this command calls \fBTcl_WaitPid\fR with the \fBWNOHANG\fR flag set for
 non-blocking behavior, unless the \fB\-wait\fR switch is set (see below).
-.RS
 .PP
 Additionally, \fB::tcl::process status\fR accepts the following switches:
 .TP
 \fB\-wait\fR\0
 .
 By default the command returns immediately (the underlying \fBTcl_WaitPid\fR is
-called with the \fBWNOHANG\fR flag set) unless this switch is set. If \fBpids\fR
+called with the \fBWNOHANG\fR flag set) unless this switch is set. If \fIpids\fR
 is specified as a list of PIDs then the command waits until the status of the
-matching subprocesses are available. If \fBpids\fR is not specified then it
-waits for all known subprocesses.
+matching subprocesses are available. If \fIpids\fR was not specified, this
+command will wait for all known subprocesses.
 .TP
 \fB\-\|\-\fR
 .
 Marks the end of switches.  The argument following this one will
 be treated as the first \fIarg\fR even if it starts with a \fB\-\fR.
 .RE
-.TP
-\fB::tcl::process purge ?\fIpids\fR?
-.
-Cleans up all data associated with terminated subprocesses. If \fBpids\fR is
-specified as a list of PIDs then the command only cleanup data for the matching
-subprocesses if they exist, and raises an error otherwise. If the process is
-still active then it does nothing.
-.TP
-\fB::tcl::process autopurge ?\fIflag\fR?
-.
-Automatic purge facility. If \fBflag\fR is specified as a boolean value then it
-activates or deactivate autopurge. In all cases it returns the current status as
-a boolean value. When autopurge is active, \fBTcl_ReapDetachedProcs\fR is called
-each time the exec command is executed or a pipe channel created by open is
-closed. When autopurge is inactive, \fB::tcl::process\fR purge must be called
-explicitly. By default autopurge is active.
-.RE
 .SH "EXAMPLES"
 .PP
+These show the use of \fB::tcl::process\fR. Some of the results from
+\fB::tcl::process status\fR are split over multiple lines for readability.
+.PP
 .CS
 \fB::tcl::process autopurge\fR
      \fI\(-> true\fR
@@ -102,7 +108,12 @@ set pid2 [pid $chan]
      \fI\(-> 123 456 789 1011\fR
 
 \fB::tcl::process status\fR
-     \fI\(-> 123 0 456 {1 "child killed: write on pipe with no readers" {CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}} 789 {1 "child suspended: background tty read" {CHILDSUSP 789 SIGTTIN "background tty read"}} 1011 {}\fR
+     \fI\(-> 123 0
+       456 {1 "child killed: write on pipe with no readers" {
+         CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}}
+       789 {1 "child suspended: background tty read" {
+         CHILDSUSP 789 SIGTTIN "background tty read"}}
+       1011 {}\fR
 
 \fB::tcl::process status\fR 123
      \fI\(-> 123 0\fR
@@ -111,10 +122,17 @@ set pid2 [pid $chan]
      \fI\(-> 1011 {}\fR
 
 \fB::tcl::process status\fR -wait
-     \fI\(-> 123 0 456 {1 "child killed: write on pipe with no readers" {CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}} 789 {1 "child suspended: background tty read" {CHILDSUSP 789 SIGTTIN "background tty read"}} 1011 {1 "child process exited abnormally" {CHILDSTATUS 1011 -1}}\fR
+     \fI\(-> 123 0
+       456 {1 "child killed: write on pipe with no readers" {
+         CHILDKILLED 456 SIGPIPE "write on pipe with no readers"}}
+       789 {1 "child suspended: background tty read" {
+         CHILDSUSP 789 SIGTTIN "background tty read"}}
+       1011 {1 "child process exited abnormally" {
+         CHILDSTATUS 1011 -1}}\fR
 
 \fB::tcl::process status\fR 1011
-     \fI\(-> 1011 {1 "child process exited abnormally" {CHILDSTATUS 1011 -1}}\fR
+     \fI\(-> 1011 {1 "child process exited abnormally" {
+         CHILDSTATUS 1011 -1}}\fR
 
 \fB::tcl::process purge\fR
 exec command1 1 2 3 &
@@ -123,7 +141,8 @@ exec command1 1 2 3 &
      \fI\(-> 1213\fR
 .CE
 .SH "SEE ALSO"
-exec(n), open(n), Tcl_DetachPids(3), Tcl_WaitPid(3), Tcl_ReapDetachedProcs(3)
+exec(n), open(n), pid(n),
+Tcl_DetachPids(3), Tcl_WaitPid(3), Tcl_ReapDetachedProcs(3)
 .SH "KEYWORDS"
 background, child, detach, process, wait
 '\" Local Variables: