Clarify in-thread documentation

core/errors.facts

@@ -28,18 +28,18 @@ HELP: throw ( error -- * )
 
 HELP: catch
 { $values { "try" "a quotation" } { "error/f" "an object" } }
-{ $description "Calls the " { $snippet "try" } " quotation. If an error is thrown in the dynamic extent of the quotation, restores the datastack and pushes the error. If the quotation returns successfully, outputs " { $link f } " without restoring the datastack." }
+{ $description "Calls the " { $snippet "try" } " quotation. If an error is thrown in the dynamic extent of the quotation, restores the data stack and pushes the error. If the quotation returns successfully, outputs " { $link f } " without restoring the data stack." }
 { $notes "This word cannot differentiate between the case of " { $link f } " being thrown, and no error being thrown. You should never throw " { $link f } ", and you should also use other error handling combinators where possible." }
 { $see-also cleanup recover } ;
 
 HELP: cleanup
 { $values { "try" "a quotation" } { "cleanup" "a quotation" } }
-{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the datastack, calls the " { $snippet "cleanup" } " quotation, and rethrows the error. If the " { $snippet "try" } " quotation returns successfully, calls the " { $snippet "cleanup" } " quotation without restoring the datastack." }
+{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the data stack, calls the " { $snippet "cleanup" } " quotation, and rethrows the error. If the " { $snippet "try" } " quotation returns successfully, calls the " { $snippet "cleanup" } " quotation without restoring the data stack." }
 { $see-also catch recover } ;
 
 HELP: recover
 { $values { "try" "a quotation" } { "recovery" "a quotation with stack effect " { $snippet "( error -- )" } } }
-{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the datastack and calls the " { $snippet "recovery" } " quotation to handle the error." } 
+{ $description "Calls the " { $snippet "try" } " quotation. If an exception is thrown in the dynamic extent of the " { $snippet "try" } " quotation, restores the data stack and calls the " { $snippet "recovery" } " quotation to handle the error." } 
 { $see-also catch cleanup } ;
 
 HELP: rethrow

core/handbook/dataflow.facts

@@ -100,7 +100,7 @@ ARTICLE: "interpreter" "The interpreter"
     { "If the end of the current quotation has been reached, the parent quotation is popped from the call stack and execution resumes from the saved location" }
     { "Otherwise, the interpreter performs an action depending on the type of the object at the instruction pointer:"
         { $list
-            { { $emphasis "Symbol word" } " - pushed on the datastack. See " { $link "symbols" } }
+            { { $emphasis "Symbol word" } " - pushed on the data stack. See " { $link "symbols" } }
             { { $emphasis "Compound word" } " - the associated quotation is called. See " { $link "colon-definition" } }
             { { $emphasis "Compiled or primitive word" } " - the interpreter jumps to machine code. See " { $link "primitives" } }
             { { $emphasis "Undefined word" } " -  an error is raised. See " { $link "deferred" } }

core/kernel.facts

@@ -256,7 +256,7 @@ HELP: with
 
 HELP: keep-datastack
 { $values { "quot" "a quotation" } }
-{ $description "Calls a quotation, saving the datastack before calling it and restoring it after it returns." } ;
+{ $description "Calls a quotation, saving the data stack before calling it and restoring it after it returns." } ;
 
 HELP: die
 { $description "Starts the front-end processor (FEP), which is a low-level debugger which can inspect memory addresses and the like. The FEP is also entered when a critical error occurs." } ;

core/threads.facts

@@ -1,4 +1,4 @@
-USING: help threads kernel ;
+USING: help threads kernel io ;
 
 HELP: run-queue
 { $values { "queue" "a queue" } }
@@ -36,7 +36,15 @@ HELP: sleep
 
 HELP: in-thread
 { $values { "quot" "a quotation" } }
-{ $description "Spawns a new thread. The new thread begins running immediately. If an unhandled error occurs in the thread, the error is logged to the default stream in the dynamic extent of the caller of this word." } ;
+{ $description "Spawns a new thread. The new thread begins running immediately."
+$terpri
+"The new thread inherits the current data stack and name stack. The call stack initially contains the new quotation only, so when the quotation returns the thread stops. The catch stack contains a default handler which logs errors to the " { $link stdio } " stream." }
+{ $examples
+    { $code "1 2 [ + . ] in-thread" }
+}
+{ $notes
+    "A higher-level concurrency library can be found in the " { $snippet "libs/concurrency" } " module; see " { $link "modules" } "."
+} ;
 
 HELP: idle-thread
 { $description "Runs the idle thread, which services I/O requests and relinquishes control to the operating system until the next Factor thread has to wake up again." }

core/tools/debugger.facts

@@ -37,7 +37,7 @@ HELP: print-error
 
 HELP: try
 { $values { "quot" "a quotation" } }
-{ $description "Calls the quotation. If it throws an error, logs the error to the default stream and restores the datastack." } ;
+{ $description "Calls the quotation. If it throws an error, logs the error to the default stream and restores the data stack." } ;
 
 HELP: expired-error.
 { $error-description "Thrown by " { $link alien-address } " and " { $link alien-invoke } " if an " { $link alien } " object passed in as a parameter has expired. Alien objects expire if they are saved an image which is subsequently loaded; this prevents a certain class of programming errors, usually attempts to use uninitialized objects, since holding a C address is meaningless between sessions." }