tork-engine.1 in tork-19.0.0

- old
+ new
@@ -1,66 +1,84 @@
-.TH TORK\-ENGINE 1 2012\-10\-10 18.2.4
+.TH TORK\-ENGINE 1 2012\-10\-17 19.0.0
 .SH NAME
 .PP
 tork\-engine \- wraps 
 .BR tork-master (1) 
 with bookkeeping
 .SH SYNOPSIS
 .PP
 \fB\fCtork-engine\fR [\fIOPTION\fP]...
 .SH DESCRIPTION
 .PP
-This program tells 
+This program uses 
 .BR tork-master (1) 
-to run your tests and keeps track of test
-results.  It reads the following single\-line commands (JSON arrays) from its
-standard input stream and performs the respective actions as described below.
-It also funnels the standard output stream of 
-.BR tork-master (1) 
-into its own.
+to run tests and keeps track of the results.
+.PP
+This program can be controlled remotely by multiple 
+.BR tork-remote (1) 
+instances.
+.SS Input
+.PP
+This program reads the following commands, which are single\-line JSON arrays,
+from stdin and performs the actions described respectively.
 .TP
-\fB\fC["reabsorb_overhead",\fR \fIpaths\fP\fB\fC,\fR \fIfiles\fP\fB\fC]\fR
-Stops any test files that are currently running, reabsorbs the given test
-execution overhead, and resumes running those interrupted test files.  See
-the "load" command in 
-.BR tork-master (1) 
-for more information.
+\fB\fC["reabsorb_overhead"]\fR
+Stops any test files that are currently running, reabsorbs the test
+execution overhead, and then re\-runs those stopped test files.
 .TP
-\fB\fC["run_test_file"\fR, \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP\fB\fC]\fR
-Runs tests that correspond to the given \fIline_numbers\fP array in the given
-\fItest_file\fP.  If \fIline_numbers\fP is \fB\fCnull\fR, then only those lines that have
-changed since the last time the \fItest_file\fP was run will be substituted.  If
-\fIline_numbers\fP is an empty array, then the entire \fItest_file\fP will be run.
+\fB\fC["run_test_file"\fR, \fItest_file\fP\fB\fC,\fR \fIline_numbers\fP...\fB\fC]\fR
+Runs tests that correspond to the given sequence of \fIline_numbers\fP in the
+given \fItest_file\fP.  If no \fIline_numbers\fP are given, then only those lines
+that have changed since the last run of \fItest_file\fP will be substituted.
+If any \fIline_numbers\fP are zero, then the entire \fItest_file\fP will be run.
 .TP
-\fB\fC["stop_running_test_files"]\fR
-Stops any test files that are currently running.
+\fB\fC["run_test_files"\fR, \fItest\fIfiles\fPwith\fIoptional\fPline_numbers\fP\fB\fC]\fR
+Calls the \fB\fCrun_test_file\fR command once for each item in the given array.
 .TP
+\fB\fC["stop_running_test_files"\fR, \fIsignal\fP\fB\fC]\fR
+Stops test files that are currently running by sending the given \fIsignal\fP
+(optional; defaults to "SIGTERM") to their respective worker processes.
+.TP
 \fB\fC["rerun_passed_test_files"]\fR
 Runs all test files that have passed during their most recent run.
 .TP
 \fB\fC["rerun_failed_test_files"]\fR
 Runs all test files that have failed during their most recent run.
 .TP
 \fB\fC["quit"]\fR
 Stops all tests that are currently running and exits.
+.SS Output
+.PP
+This program prints the following messages, which are single\-line JSON arrays,
+to stdout.
+.TP
+\fB\fC["pass_now_fail",\fR \fItest_file\fP\fB\fC,\fR \fImessage\fP\fB\fC]\fR
+A previously passing \fItest_file\fP has now failed.  See \fImessage\fP for details.
+.TP
+\fB\fC["fail_now_pass",\fR \fItest_file\fP\fB\fC,\fR \fImessage\fP\fB\fC]\fR
+A previously failing \fItest_file\fP has now passed.  See \fImessage\fP for details.
+.TP
+\fI...\fP
+Messages from 
+.BR tork-master (1) 
+are also reproduced here.
 .SH OPTIONS
 .TP
 \fB\fC-h\fR, \fB\fC--help\fR
 Show this help manual.
 .SH FILES
 .TP
-\fI.tork.rb\fP
-Optional Ruby script for configuring 
-.BR tork (1).
-.SH ENVIRONMENT
+\fI.tork/config.rb\fP
+Optional Ruby script that is loaded inside the driver process on startup.
+It can read and change the \fB\fCENV['TORK_CONFIGS']\fR environment variable.
 .TP
-\fB\fCTORK_CONFIGS\fR
-A single\-line JSON array containing paths to actual files or names of
-helper libraries in the tork/config/ namespace of Ruby's load path.
-These configuration files are loaded just before \fI.tork.rb\fP is loaded.
+\fI.tork/engine.rb\fP
+Optional Ruby script that is loaded inside the master process on startup.
+.SH ENVIRONMENT
+.PP
+See 
+.BR tork (1).
 .SH SEE ALSO
 .PP
 .BR tork (1), 
-.BR tork-herald (1), 
-.BR tork-driver (1), 
-.BR tork-engine (1), 
+.BR tork-remote (1), 
 .BR tork-master (1)
\ No newline at end of file