Various documentation improvements

basis/compression/lzw/lzw-docs.factor

@@ -52,7 +52,7 @@ HELP: reset-lzw-uncompress
 }
 { $description "Reset the LZW uncompressor state (either at initialization time or immediately after receiving a Clear Code). " } ;
 
-ARTICLE: "compression.lzw.differences" "LZW Differences between TIFF and GIF"
+ARTICLE: "compression.lzw.differences" "LZW differences between TIFF and GIF"
 { $vocab-link "compression.lzw" }
 $nl
 "There are some subtle differences between the LZW algorithm used by TIFF and GIF images."
@@ -66,7 +66,7 @@ $nl
 "TIFF and GIF both add the concept of a 'Clear Code' and a 'End of Information Code' to the LZW algorithm. In both cases, the 'Clear Code' is equal to 2**(code-size - 1) and the 'End of Information Code' is equal to the Clear Code + 1. These 2 codes are reserved in the string table. So in both cases, the LZW string table is initialized to have a length equal to the End of Information Code + 1."
 ;
 
-ARTICLE: "compression.lzw" "LZW Compression"
+ARTICLE: "compression.lzw" "LZW compression"
 { $vocab-link "compression.lzw" }
 $nl
 "Implements both the TIFF and GIF variations of the LZW algorithm."

basis/eval/eval-docs.factor

@@ -1,25 +1,73 @@
 IN: eval
-USING: help.markup help.syntax strings io effects ;
+USING: help.markup help.syntax strings io effects parser
+listener vocabs.parser debugger combinators ;
+
+HELP: (eval)
+{ $values { "str" string } { "effect" effect } }
+{ $description "Parses Factor source code from a string, and calls the resulting quotation, which must have the given stack effect." }
+{ $notes "This word must be wrapped within " { $link with-file-vocabs } " or " { $link with-interactive-vocabs } ", since it assumes that the " { $link manifest } " variable is set in the current dynamic scope." }
+{ $errors "Throws an error if the input is malformed, or if the evaluation itself throws an error." } ;
 
 HELP: eval
 { $values { "str" string } { "effect" effect } }
 { $description "Parses Factor source code from a string, and calls the resulting quotation, which must have the given stack effect." }
+{ $notes "The code string is parsed and called in a new dynamic scope with an initial vocabulary search path consisting of just the " { $snippet "syntax" } " vocabulary. The evaluated code can use " { $link "word-search-syntax" } " to alter the search path." }
 { $errors "Throws an error if the input is malformed, or if the evaluation itself throws an error." } ;
 
 HELP: eval(
 { $syntax "eval( inputs -- outputs )" }
 { $description "Parses Factor source code from the string at the top of the stack, and calls the resulting quotation, which must have the given stack effect." }
+{ $notes
+    "This parsing word is just a slightly nicer syntax for " { $link eval } ". The following are equivalent:"
+    { $code
+        "eval( inputs -- outputs )"
+        "(( inputs -- outputs )) eval"
+    }
+}
 { $errors "Throws an error if the input is malformed, or if the evaluation itself throws an error." } ;
 
 HELP: eval>string
 { $values { "str" string } { "output" string } }
-{ $description "Evaluates the Factor code in " { $snippet "str" } " with " { $link output-stream } " rebound to a string output stream, then outputs the resulting string. The code in the string must not take or leave any values on the stack." } ;
+{ $description "Evaluates the Factor code in " { $snippet "str" } " with " { $link output-stream } " rebound to a string output stream, then outputs the resulting string. The code in the string must not take or leave any values on the stack." }
+{ $errors "If the code throws an error, the error is caught, and the result of calling " { $link print-error } " on the error is returned." } ;
 
-ARTICLE: "eval" "Evaluating strings at runtime"
-"The " { $vocab-link "eval" } " vocabulary implements support for evaluating strings at runtime."
+ARTICLE: "eval-vocabs" "Evaluating strings with a different vocabulary search path"
+"Strings passed to " { $link eval } " are always evaluated with an initial vocabulary search path consisting of just the " { $snippet "syntax" } " vocabulary. This is the same search path that source files start out with. This behavior can be customized by taking advantage of the fact that " { $link eval } " is composed from two simpler words:"
+{ $subsections
+    (eval)
+    with-file-vocabs
+}
+"Code in the listener tool starts out with a different initial search path, with more vocabularies are available by default. Strings of code can be evaluated in this search path by using " { $link (eval) } " with a different combinator:"
+{ $subsections
+    with-interactive-vocabs
+}
+"When using " { $link (eval) } ", the quotation passed to " { $link with-file-vocabs } " and " { $link with-interactive-vocabs } " can also make specific vocabularies available to the evaluated string. This is done by having the quotation change the run-time vocabulary search path prior to calling " { $link (eval) } ". For run-time analogues of the parse-time " { $link "word-search-syntax" } " see " { $link "word-search-parsing" } "."
+$nl
+"The vocabulary set used by " { $link with-interactive-vocabs } " can be altered by rebinding a dynamic variable:"
+{ $subsections interactive-vocabs }
+{ $heading "Example" }
+"In this example, a string is evaluated with a fictional " { $snippet "cad.objects" } " vocabulary in the search path by default, together with the listener's " { $link interactive-vocabs } "; the quotation is expected to produce a sequence on the stack:"
+{ $code
+    """USING: eval listener vocabs.parser ;
+[
+    "cad-objects" use-vocab
+    (( -- seq )) (eval)
+] with-interactive-vocabs"""
+}
+"Note that the search path in the outer code (set by the " { $link POSTPONE: USING: } " form) has no relation to the search path used when parsing the string parameter (this is determined by " { $link with-interactive-vocabs } " and " { $link use-vocab } ")." ;
+
+ARTICLE: "eval" "Evaluating strings at run time"
+"The " { $vocab-link "eval" } " vocabulary implements support for evaluating strings of code dynamically."
+$nl
+"The main entry point is a parsing word, which wraps a library word:"
 { $subsections
     POSTPONE: eval(
-    eval>string
-} ;
+    eval
+}
+"This pairing is analogous to that of " { $link POSTPONE: call( } " with " { $link call-effect } "."
+$nl
+"Advanced features:"
+{ $subsections "eval-vocabs" eval>string }
+;
 
 ABOUT: "eval"

basis/listener/listener-docs.factor

@@ -1,4 +1,4 @@
-USING: help.markup help.syntax kernel io system prettyprint continuations ;
+USING: help.markup help.syntax kernel io system prettyprint continuations quotations ;
 IN: listener
 
 ARTICLE: "listener-watch" "Watching variables in the listener"
@@ -21,6 +21,11 @@ HELP: only-use-vocabs
 { $values { "vocabs" "a sequence of vocabulary specifiers" } }
 { $description "Replaces the current manifest's vocabulary search path with the given set of vocabularies." } ;
 
+HELP: with-interactive-vocabs
+{ $values { "quot" quotation } }
+{ $description "Calls the quotation in a scope with an initial vocabulary search path consisting of all vocabularies from " { $link interactive-vocabs } ", and with the current vocabulary for new definitions set to " { $vocab-link "scratchpad" } "." }
+{ $notes "This is the same initial search path as used by the " { $link "listener" } " tool." } ;
+
 HELP: show-var
 { $values { "var" "a variable name" } }
 { $description "Adds a variable to the watch list; its value will be printed by the listener after every expression." } ;

basis/prettyprint/stylesheet/stylesheet-docs.factor

@@ -8,33 +8,31 @@ HELP: effect-style
     { "effect" "an effect" }
     { "style" "a style assoc" }
 }
-{ $description "The styling hook for stack effects" } ;
+{ $description "The stylesheet for stack effects" } ;
 
 HELP: string-style
 { $values
     { "str" "a string" }
     { "style" "a style assoc" }
 }
-{ $description "The styling hook for string literals" } ;
+{ $description "The stylesheet for string literals" } ;
 
 HELP: vocab-style
 { $values
     { "vocab" "a vocabulary specifier" }
     { "style" "a style assoc" }
 }
-{ $description "The styling hook for vocab names" } ;
+{ $description "The stylesheet for vocab names" } ;
 
 HELP: word-style
 { $values
     { "word" "a word" }
     { "style" "a style assoc" }
 }
-{ $description "The styling hook for word names" } ;
+{ $description "The stylesheet for word names" } ;
 
-ARTICLE: "prettyprint.stylesheet" "Prettyprinter Formatted Output"
-{ $vocab-link "prettyprint.stylesheet" }
-$nl
-"Control the way that the prettyprinter formats output based on object type. These hooks form a basic \"syntax\" highlighting system."
+ARTICLE: "prettyprint.stylesheet" "Prettyprinter stylesheet"
+"The " { $vocab-link "prettyprint.stylesheet" } " vocabulary defines variables which control the way that the prettyprinter formats output based on object type."
 { $subsections
     word-style
     string-style

basis/vocabs/refresh/refresh-docs.factor

@@ -15,7 +15,13 @@ HELP: refresh-all
 { refresh refresh-all } related-words
 
 ARTICLE: "vocabs.refresh" "Runtime code reloading"
-"Reloading source files changed on disk:"
+"The " { $vocab-link "vocabs.refresh" } " vocabulary implements automatic reloading of changed source files."
+$nl
+"With the help of the " { $vocab-link "io.monitors" } " vocabulary, loaded source files across all vocabulary roots are monitored for changes on disk."
+$nl
+"If a change to a source file is detected, the next invocation of " { $link refresh-all } " will compare the file's checksum against its previous value, reloading the file if necessary. This takes advantage of the fact that the " { $vocab-link "source-files" } " vocabulary records CRC32 checksums of source files that have been parsed by " { $link "parser" } "."
+$nl
+"Words for reloading source files:"
 { $subsections
     refresh
     refresh-all

core/parser/parser-docs.factor

@@ -79,17 +79,6 @@ $nl
     "word-search-parsing"
 } ;
 
-ARTICLE: "parser-files" "Parsing source files"
-"The parser can run source files:"
-{ $subsections
-    run-file
-    parse-file
-}
-"The parser cross-references source files and definitions. This allows it to keep track of removed definitions, and prevent forward references and accidental redefinitions."
-$nl
-"While the above words are useful for one-off experiments, real programs should be written to use the vocabulary system instead; see " { $link "vocabs.loader" } "."
-{ $see-also "source-files" } ;
-
 ARTICLE: "top-level-forms" "Top level forms"
 "Any code outside of a definition is known as a " { $emphasis "top-level form" } "; top-level forms are run after the entire source file has been parsed, regardless of their position in the file."
 $nl
@@ -98,14 +87,19 @@ $nl
 "Also, top-level forms run in a new dynamic scope, so using " { $link set } " to store values is almost always wrong, since the values will be lost after the top-level form completes. To save values computed by a top-level form, either use " { $link set-global } " or define a new word with the value." ;
 
 ARTICLE: "parser" "The parser"
-"This parser is a general facility for reading textual representations of objects and definitions. The parser is implemented in the " { $vocab-link "parser" } " and " { $vocab-link "syntax" } " vocabularies."
+"The Factor parser reading textual representations of objects and definitions, with all syntax determined by " { $link "parsing-words" } ". The parser is implemented in the " { $vocab-link "parser" } " vocabulary, with standard syntax in the " { $vocab-link "syntax" } " vocabulary. See " { $link "syntax" } " for a description of standard syntax."
 $nl
-"This section concerns itself with usage and extension of the parser. Standard syntax is described in " { $link "syntax" } "."
-{ $subsections "parser-files" }
-"The parser can be extended."
-{ $subsections "parser-lexer" }
-"The parser can be invoked reflectively;"
-{ $subsections parse-stream }
+"The parser cross-references " { $link "source-files" } " and " { $link "definitions" } ". This functionality is used for improved error checking, as well as tools such as " { $link "tools.crossref" } " and " { $link "editor" } "."
+$nl
+"The parser can be invoked reflectively, to run strings and source files."
+{ $subsections
+    "eval"
+    run-file
+    parse-file
+}
+"If Factor is run from the command line with a script file supplied as an argument, the script is run using " { $link run-file } ". See " { $link "cli" } "."
+$nl
+"While " { $link run-file } " can be used interactively in the listener to load user code into the session, this should only be done for quick one-off scripts, and real programs should instead rely on the automatic " { $link "vocabs.loader" } "."
 { $see-also "parsing-words" "definitions" "definition-checking" } ;
 
 ABOUT: "parser"
@@ -204,7 +198,7 @@ HELP: bootstrap-syntax
 
 HELP: with-file-vocabs
 { $values { "quot" quotation } }
-{ $description "Calls the quotation in a scope with the initial the vocabulary search path for parsing a file. This consists of just the " { $snippet "syntax" } " vocabulary." } ;
+{ $description "Calls the quotation in a scope with an initial vocabulary search path consisting of just the " { $snippet "syntax" } " vocabulary." } ;
 
 HELP: parse-fresh
 { $values { "lines" "a sequence of strings" } { "quot" quotation } }

core/vocabs/loader/loader-docs.factor

@@ -28,38 +28,44 @@ ARTICLE: "vocabs.roots" "Vocabulary roots"
 { $subsections "add-vocab-roots" } ;
 
 ARTICLE: "vocabs.loader" "Vocabulary loader"
-"The vocabulary loader is defined in the " { $vocab-link "vocabs.loader" } " vocabulary."
+"The vocabulary loader combines the vocabulary system with " { $link "parser" } " in order to implement automatic loading of vocabulary source files. The vocabulary loader is implemented in the " { $vocab-link "vocabs.loader" } " vocabulary."
 $nl
-"Vocabularies are searched for in vocabulary roots."
+"When an attempt is made to use a vocabulary that has not been loaded into the image, the vocabulary loader is asked to locate the vocabulary's source files, and load them."
+$nl
+"The vocabulary loader searches for vocabularies in a set of directories known as vocabulary roots."
 { $subsections "vocabs.roots" }
-"Vocabulary names map directly to source files. A vocabulary named " { $snippet "foo.bar" } " must be defined in a " { $snippet "bar" } " directory nested inside a " { $snippet "foo" } " directory of a vocabulary root. Any level of vocabulary nesting is permitted."
+"Vocabulary names map directly to source files inside these roots. A vocabulary named " { $snippet "foo.bar" } " is defined in " { $snippet "foo/bar/bar.factor" } "; that is, a source file named " { $snippet "bar.factor" } " within a " { $snippet "bar" } " directory nested inside a " { $snippet "foo" } " directory of a vocabulary root. Any level of nesting, separated by dots, is permitted."
 $nl
 "The vocabulary directory - " { $snippet "bar" } " in our example - contains a source file:"
 { $list
-  { { $snippet "foo/bar/bar.factor" } " - the source file, must define words in the " { $snippet "foo.bar" } " vocabulary with an " { $snippet "IN: foo.bar" } " form" }
+  { { $snippet "foo/bar/bar.factor" } " - the source file must define words in the " { $snippet "foo.bar" } " vocabulary with an " { $snippet "IN: foo.bar" } " form" }
 }
-"Two other Factor source files, storing documentation and tests, respectively, are optional:"
+"Two other Factor source files, storing documentation and tests, respectively, may optionally be placed alongside the source file:"
 { $list
     { { $snippet "foo/bar/bar-docs.factor" } " - documentation, see " { $link "writing-help" } }
     { { $snippet "foo/bar/bar-tests.factor" } " - unit tests, see " { $link "tools.test" } }
 }
-"Finally, three text files can contain meta-data:"
+"Finally, optional three text files may contain meta-data:"
 { $list
     { { $snippet "foo/bar/authors.txt" } " - a series of lines, with one author name per line. These are listed under " { $link "vocab-authors" } }
     { { $snippet "foo/bar/summary.txt" } " - a one-line description" }
     { { $snippet "foo/bar/tags.txt" } " - a whitespace-separated list of tags which classify the vocabulary. Consult " { $link "vocab-tags" } " for a list of existing tags you can re-use" }
 }
-"While " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } " load vocabularies which have not been loaded before adding them to the search path, it is also possible to load a vocabulary without adding it to the search path:"
+"The " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } " words load vocabularies which have not been loaded yet, as needed."
+$nl
+"Vocabularies can also be loaded at run time, without altering the vocabulary search path. This is done by calling a word which loads a vocabulary if it is not in the image, doing nothing if it is:"
 { $subsections require }
-"Forcing a reload of a vocabulary, even if it has already been loaded:"
+"The above word will only ever load a vocabulary once in a given session. There is another word which unconditionally loads vocabulary from disk, regardless of whether or not is has already been loaded:"
 { $subsections reload }
+"For interactive development in the listener, calling " { $link reload } " directly is usually not necessary, since a better facility exists for " { $link "vocabs.refresh" } "."
+$nl
 "Application vocabularies can define a main entry point, giving the user a convenient way to run the application:"
 { $subsections
     POSTPONE: MAIN:
     run
     runnable-vocab
 }
-{ $see-also "vocabularies" "parser-files" "source-files" } ;
+{ $see-also "vocabularies" "parser" "source-files" } ;
 
 ABOUT: "vocabs.loader"
 

core/vocabs/parser/parser-docs.factor

@@ -65,7 +65,7 @@ $nl
 }
 { $see-also "words" } ;
 
-ARTICLE: "word-search-parsing" "Word lookup in parsing words"
+ARTICLE: "word-search-parsing" "Reflection support for vocabulary search path"
 "The parsing words described in " { $link "word-search-syntax" } " are implemented using the below words, which you can also call from your own parsing words."
 $nl
 "The current state used for word search is stored in a " { $emphasis "manifest" } ":"

extra/combinators/tuple/tuple-docs.factor

@@ -33,7 +33,7 @@ HELP: nmake-tuple
 { make-tuple 2make-tuple 3make-tuple nmake-tuple } related-words
 
 ARTICLE: "combinators.tuple" "Tuple-constructing combinators"
-"The " { $vocab-link "combinators.tuple" } " vocabulary provides dataflow combinators that construct " { $link tuple } " objects."
+"The " { $vocab-link "combinators.tuple" } " vocabulary provides combinators that construct " { $link tuple } " objects. These provide additional functionality above and beyond built-in " { $link "tuple-constructors" } "."
 { $subsections
     make-tuple
     2make-tuple