Documentation updates

basis/compiler/errors/errors-docs.factor

@@ -14,7 +14,7 @@ $nl
 { $subsection :warnings }
 { $subsection :errors }
 { $subsection :linkage }
-"Compiler warnings and errors are also shown in the " { $link "ui.tools.error-list" } "." ;
+"Compiler warnings and errors are reported using the " { $link "tools.errors" } " mechanism and are shown in the " { $link "ui.tools.error-list" } "." ;
 
 HELP: compiler-error
 { $values { "error" "an error" } { "word" word } }

basis/concurrency/promises/promises-docs.factor

@@ -7,6 +7,10 @@ IN: concurrency.promises
 HELP: promise
 { $class-description "The class of write-once promises." } ;
 
+HELP: <promise>
+{ $values { "promise" promise } }
+{ $description "Creates a new promise which may be fulfilled by calling " { $link fulfill } "." } ;
+
 HELP: promise-fulfilled?
 { $values { "promise" promise } { "?" "a boolean" } }
 { $description "Tests if " { $link fulfill } " has previously been called on the promise, in which case " { $link ?promise } " will return immediately without blocking." } ;

basis/editors/editors-docs.factor

@@ -14,6 +14,9 @@ ARTICLE: "editor" "Editor integration"
 
 ABOUT: "editor"
 
+HELP: edit-hook
+{ $var-description "A quotation with stack effect " { $snippet "( file line -- )" } ". If not set, the " { $link edit } " word throws a condition with restarts for loading one of the sub-vocabularies of the " { $vocab-link "editors" } " vocabulary." } ;
+
 HELP: edit
 { $values { "defspec" "a definition specifier" } }
 { $description "Opens the source file containing the definition using the current " { $link edit-hook } ". See " { $link "editor" } "." }

basis/help/cookbook/cookbook.factor

@@ -74,7 +74,7 @@ $nl
     "shuffle-words"
     "words"
     "generic"
-    "tools"
+    "handbook-tools-reference"
 } ;
 
 ARTICLE: "cookbook-combinators" "Control flow cookbook"

basis/help/handbook/handbook.factor

@@ -5,7 +5,7 @@ math system strings sbufs vectors byte-arrays quotations
 io.streams.byte-array classes.builtin parser lexer
 classes.predicate classes.union classes.intersection
 classes.singleton classes.tuple help.vocabs math.parser
-accessors definitions ;
+accessors definitions sets ;
 IN: help.handbook
 
 ARTICLE: "conventions" "Conventions"
@@ -197,28 +197,6 @@ ARTICLE: "io" "Input and output"
 { $subsection "io.ports" }
 { $see-also "destructors" } ;
 
-ARTICLE: "tools" "Developer tools"
-{ $subsection "tools.vocabs" }
-"Exploratory tools:"
-{ $subsection "see" }
-{ $subsection "editor" }
-{ $subsection "listener" }
-{ $subsection "tools.crossref" }
-{ $subsection "inspector" }
-{ $subsection "tools.completion" }
-"Debugging tools:"
-{ $subsection "tools.annotations" }
-{ $subsection "tools.test" }
-{ $subsection "tools.threads" }
-"Performance tools:"
-{ $subsection "tools.memory" }
-{ $subsection "profiling" }
-{ $subsection "timing" }
-{ $subsection "tools.disassembler" }
-"Deployment tools:"
-{ $subsection "tools.deploy" }
-{ $see-also "ui-tools" } ;
-
 ARTICLE: "article-index" "Article index"
 { $index [ articles get keys ] } ;
 
@@ -247,59 +225,79 @@ ARTICLE: "class-index" "Class index"
 
 USING: help.cookbook help.tutorial ;
 
-ARTICLE: "handbook-language-reference" "Language reference"
+ARTICLE: "handbook-language-reference" "The language"
-"Fundamentals:"
+{ $heading "Fundamentals" }
 { $subsection "conventions" }
 { $subsection "syntax" }
 { $subsection "effects" }
 { $subsection "evaluator" }
-"Data types:"
+{ $heading "Data types" }
 { $subsection "booleans" }
 { $subsection "numbers" }
 { $subsection "collections" }
-"Evaluation:"
+{ $heading "Evaluation" }
 { $subsection "words" }
 { $subsection "shuffle-words" }
 { $subsection "combinators" }
 { $subsection "errors" }
 { $subsection "continuations" }
-"Named values:"
+{ $heading "Named values" }
 { $subsection "locals" }
 { $subsection "namespaces" }
 { $subsection "namespaces-global" }
 { $subsection "values" }
-"Abstractions:"
+{ $heading "Abstractions" }
 { $subsection "objects" }
 { $subsection "destructors" }
 { $subsection "macros" }
 { $subsection "fry" }
-"Program organization:"
+{ $heading "Program organization" }
 { $subsection "vocabs.loader" }
 "Vocabularies tagged " { $link T{ vocab-tag { name "extensions" } } } " implement various additional language abstractions." ;
 
-ARTICLE: "handbook-environment-reference" "Environment reference"
+ARTICLE: "handbook-system-reference" "The implementation"
-"Parse time and compile time:"
+{ $heading "Parse time and compile time" }
 { $subsection "parser" }
 { $subsection "definitions" }
 { $subsection "vocabularies" }
 { $subsection "source-files" }
 { $subsection "compiler" }
-"Tools:"
+{ $heading "Virtual machine" }
-{ $subsection "prettyprint" }
-{ $subsection "tools" }
-{ $subsection "help" }
-{ $subsection "inference" }
 { $subsection "images" }
-"VM:"
 { $subsection "cli" }
 { $subsection "rc-files" }
 { $subsection "init" }
 { $subsection "system" }
 { $subsection "layouts" } ;
 
-ARTICLE: "handbook-library-reference" "Library reference"
+ARTICLE: "handbook-tools-reference" "Developer tools"
-"This index only includes articles from loaded vocabularies. To explore more vocabularies, see " { $link "vocab-index" } "."
+"The below tools are text-based. " { $link "ui-tools" } " are documented separately."
-{ $index [ "handbook" orphan-articles remove ] } ;
+{ $heading "Workflow" }
+{ $subsection "listener" }
+{ $subsection "editor" }
+{ $subsection "tools.vocabs" }
+{ $subsection "tools.test" }
+{ $subsection "help" }
+{ $heading "Debugging" }
+{ $subsection "prettyprint" }
+{ $subsection "inspector" }
+{ $subsection "tools.annotations" }
+{ $subsection "inference" }
+{ $heading "Browsing" }
+{ $subsection "see" }
+{ $subsection "tools.crossref" }
+{ $heading "Performance" }
+{ $subsection "timing" }
+{ $subsection "profiling" }
+{ $subsection "tools.memory" }
+{ $subsection "tools.threads" }
+{ $subsection "tools.disassembler" }
+{ $heading "Deployment" }
+{ $subsection "tools.deploy" } ;
+
+ARTICLE: "handbook-library-reference" "Libraries"
+"This index lists articles from loaded vocabularies which are not subsections of any other article. To explore more vocabularies, see " { $link "vocab-index" } "."
+{ $index [ orphan-articles { "help.home" "handbook" } diff ] } ;
 
 ARTICLE: "handbook" "Factor handbook"
 "Learn the language:"
@@ -307,11 +305,11 @@ ARTICLE: "handbook" "Factor handbook"
 { $subsection "first-program" }
 "Reference material:"
 { $subsection "handbook-language-reference" }
-{ $subsection "handbook-environment-reference" }
 { $subsection "io" }
 { $subsection "ui" }
+{ $subsection "handbook-system-reference" }
+{ $subsection "handbook-tools-reference" }
 { $subsection "ui-tools" }
-{ $subsection "unicode" }
 { $subsection "alien" }
 { $subsection "handbook-library-reference" }
 "Explore loaded libraries:"

basis/help/home/home-docs.factor

@@ -8,6 +8,7 @@ ARTICLE: "help.home" "Factor documentation"
   { $link "handbook" }
   { $link "vocab-index" }
   { $link "ui-tools" }
+  { $link "ui-listener" }
 }
 { $heading "Recently visited" }
 { $table

basis/io/launcher/launcher-docs.factor

@@ -140,7 +140,46 @@ HELP: <process-stream>
   { "desc" "a launch descriptor" }
   { "encoding" "an encoding descriptor" }
   { "stream" "a bidirectional stream" } }
-{ $description "Launches a process and redirects its input and output via a pair of pipes which may be read and written as a stream of the given encoding." } ;
+{ $description "Launches a process and redirects its input and output via a pair of pipes which may be read and written as a stream with the given encoding." } ;
+
+HELP: <process-reader>
+{ $values
+  { "desc" "a launch descriptor" }
+  { "encoding" "an encoding descriptor" }
+  { "stream" "an input stream" } }
+{ $description "Launches a process and redirects its output via a pipe which may be read as a stream with the given encoding." } ;
+
+HELP: <process-writer>
+{ $values
+  { "desc" "a launch descriptor" }
+  { "encoding" "an encoding descriptor" }
+  { "stream" "an output stream" }
+}
+{ $description "Launches a process and redirects its input via a pipe which may be written to as a stream with the given encoding." } ;
+
+HELP: with-process-stream
+{ $values
+  { "desc" "a launch descriptor" }
+  { "encoding" "an encoding descriptor" }
+  { "quot" quotation }
+}
+{ $description "Launches a process and redirects its input and output via a pair of pipes. The quotation is called with " { $link input-stream } " and " { $link output-stream } " rebound to these pipes." } ;
+
+HELP: with-process-reader
+{ $values
+  { "desc" "a launch descriptor" }
+  { "encoding" "an encoding descriptor" }
+  { "quot" quotation }
+}
+{ $description "Launches a process and redirects its output via a pipe. The quotation is called with " { $link input-stream } " and " { $link output-stream } " rebound to this pipe." } ;
+
+HELP: with-process-writer
+{ $values
+  { "desc" "a launch descriptor" }
+  { "encoding" "an encoding descriptor" }
+  { "quot" quotation }
+}
+{ $description "Launches a process and redirects its input via a pipe. The quotation is called with " { $link input-stream } " and " { $link output-stream } " rebound to this pipe." } ;
 
 HELP: wait-for-process
 { $values { "process" process } { "status" object } }
@@ -175,7 +214,11 @@ ARTICLE: "io.launcher.launch" "Launching processes"
 "Redirecting standard input and output to a pipe:"
 { $subsection <process-reader> }
 { $subsection <process-writer> }
-{ $subsection <process-stream> } ;
+{ $subsection <process-stream> }
+"Combinators built on top of the above:"
+{ $subsection with-process-reader }
+{ $subsection with-process-writer }
+{ $subsection with-process-stream } ;
 
 ARTICLE: "io.launcher.examples" "Launcher examples"
 "Starting a command and waiting for it to finish:"

basis/tools/errors/errors-docs.factor

@@ -1 +1,19 @@
 IN: tools.errors
+USING: help.markup help.syntax source-files.errors ;
+
+HELP: errors.
+{ $values { "errors" "a sequence of " { $link source-file-error } " instances" } }
+{ $description "Prints a list of errors, grouped by source file." } ;
+
+ARTICLE: "tools.errors" "Batch error reporting"
+"Some tools, such as the " { $link "compiler" } ", " { $link "tools.test" } " and " { $link "help.lint" } " need to report multiple errors at a time. Each error is associated with a source file, line number, and optionally, a definition. " { $link "errors" } " cannot be used for this purpose, so the " { $vocab-link "source-files.errors" } " vocabulary provides an alternative mechanism. Note that the words in this vocabulary are used for implementation only; to actually list errors, consult the documentation for the relevant tools."
+$nl
+"Source file errors inherit from a class:"
+{ $subsection source-file-error }
+"Printing an error summary:"
+{ $subsection error-summary }
+"Printing a list of errors:"
+{ $subsection errors. }
+"Batch errors are reported in the " { $link "ui.tools.error-list" } "." ;
+
+ABOUT: "tools.errors"

basis/tools/test/test-docs.factor

@@ -9,7 +9,8 @@ ARTICLE: "tools.test.write" "Writing unit tests"
 { $subsection POSTPONE: must-fail-with }
 "Assert that a quotation or word has a specific static stack effect (see " { $link "inference" } "):"
 { $subsection POSTPONE: must-infer }
-{ $subsection POSTPONE: must-infer-as } ;
+{ $subsection POSTPONE: must-infer-as }
+"All of the above are used like ordinary words but are actually parsing words. This ensures that parse-time state, namely the line number, can be associated with the test in question, and reported in test failures." ;
 
 ARTICLE: "tools.test.run" "Running unit tests"
 "The following words run test harness files; any test failures are collected and printed at the end:"
@@ -17,9 +18,9 @@ ARTICLE: "tools.test.run" "Running unit tests"
 { $subsection test-all }
 "The following word prints failures:"
 { $subsection :test-failures }
-"Help lint failures are also shown in the " { $link "ui.tools.error-list" } "."
+"Test failures are reported using the " { $link "tools.errors" } " mechanism and are shown in the " { $link "ui.tools.error-list" } "."
 $nl
-"Unit test failurs are instances of a class, and are stored in a global variable:"
+"Unit test failures are instances of a class, and are stored in a global variable:"
 { $subsection test-failure }
 { $subsection test-failures } ;
 

basis/ui/tools/error-list/error-list.factor

@@ -97,7 +97,7 @@ M: error-renderer column-titles
 M: error-renderer column-alignment drop { 0 1 0 0 } ;
 
 : sort-errors ( seq -- seq' )
-    [ [ [ asset>> ] [ line#>> ] bi 2array ] keep ] { } map>assoc
+    [ [ [ asset>> unparse-short ] [ line#>> ] bi 2array ] keep ] { } map>assoc
     sort-keys values ;
 
 : file-matches? ( error pathname/f -- ? )

basis/ui/tools/inspector/inspector-docs.factor

@@ -1,5 +1,5 @@
 USING: help.markup help.syntax ui.commands ui.gadgets.slots
-ui.gadgets.editors ;
+ui.gadgets.editors kernel ;
 IN: ui.tools.inspector
 
 ARTICLE: "ui-inspector-edit" "Editing slot values in the inspector"
@@ -21,4 +21,8 @@ $nl
 "The UI inspector is an instance of " { $link inspector-gadget } "."
 { $subsection "ui-inspector-edit" } ;
 
+HELP: inspector
+{ $values { "obj" object } }
+{ $description "Opens a new inspector window displaying the slots of " { $snippet "obj" } "." } ;
+
 ABOUT: "ui-inspector"

basis/ui/tools/listener/listener-docs.factor

@@ -27,6 +27,8 @@ ARTICLE: "ui-listener" "UI listener"
 { $command-map interactor "quotation" }
 { $heading "Editing commands" }
 "The text editing commands are standard; see " { $link "gadgets-editors-commands" } "."
+$nl
+"The listener displays a summary with any outstanding error conditions before every prompt. See " { $link "ui.tools.error-list" } " for details."
 { $heading "Implementation" }
 "Listeners are instances of " { $link listener-gadget } ". The listener consists of an output area (instance of " { $link pane } ") and an input area (instance of " { $link interactor } "). Clickable presentations can also be printed to the listener; see " { $link "ui-presentations" } "." ;
 

core/continuations/continuations-docs.factor

@@ -30,7 +30,7 @@ $nl
 { $heading "Anti-pattern #4: Logging and rethrowing" }
 "If you are going to rethrow an error, do not log a message. If you do so, the user will see two log messages for the same error, which will clutter logs without adding any useful information." ;
 
-ARTICLE: "errors" "Error handling"
+ARTICLE: "errors" "Exception handling"
 "Support for handling exceptional situations such as bad user input, implementation bugs, and input/output errors is provided by a set of words built using continuations."
 $nl
 "Two words raise an error in the innermost error handler for the current dynamic extent:"