From de3168ad7119906f949fcbcd902b593bafa757cb Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Tue, 26 Jan 2010 01:01:12 +1300 Subject: [PATCH] Various documentation improvements --- basis/compression/lzw/lzw-docs.factor | 4 +- basis/eval/eval-docs.factor | 60 +++++++++++++++++-- basis/listener/listener-docs.factor | 7 ++- .../stylesheet/stylesheet-docs.factor | 14 ++--- basis/vocabs/refresh/refresh-docs.factor | 8 ++- core/parser/parser-docs.factor | 32 ++++------ core/vocabs/loader/loader-docs.factor | 24 +++++--- core/vocabs/parser/parser-docs.factor | 2 +- extra/combinators/tuple/tuple-docs.factor | 2 +- 9 files changed, 105 insertions(+), 48 deletions(-) diff --git a/basis/compression/lzw/lzw-docs.factor b/basis/compression/lzw/lzw-docs.factor index dccfb25a39..28dc36902b 100644 --- a/basis/compression/lzw/lzw-docs.factor +++ b/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." diff --git a/basis/eval/eval-docs.factor b/basis/eval/eval-docs.factor index 250241dcfc..2021a2d10d 100644 --- a/basis/eval/eval-docs.factor +++ b/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" diff --git a/basis/listener/listener-docs.factor b/basis/listener/listener-docs.factor index a054067755..77bec12c1a 100644 --- a/basis/listener/listener-docs.factor +++ b/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." } ; diff --git a/basis/prettyprint/stylesheet/stylesheet-docs.factor b/basis/prettyprint/stylesheet/stylesheet-docs.factor index 60014514af..12781a568b 100644 --- a/basis/prettyprint/stylesheet/stylesheet-docs.factor +++ b/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 diff --git a/basis/vocabs/refresh/refresh-docs.factor b/basis/vocabs/refresh/refresh-docs.factor index b074a9e502..ee02a491e1 100644 --- a/basis/vocabs/refresh/refresh-docs.factor +++ b/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 diff --git a/core/parser/parser-docs.factor b/core/parser/parser-docs.factor index 97dbab384e..42903a2cec 100644 --- a/core/parser/parser-docs.factor +++ b/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 } } diff --git a/core/vocabs/loader/loader-docs.factor b/core/vocabs/loader/loader-docs.factor index 02a604ac32..f2da4a1383 100644 --- a/core/vocabs/loader/loader-docs.factor +++ b/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" diff --git a/core/vocabs/parser/parser-docs.factor b/core/vocabs/parser/parser-docs.factor index 6a7bd4d212..66900978a8 100644 --- a/core/vocabs/parser/parser-docs.factor +++ b/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" } ":" diff --git a/extra/combinators/tuple/tuple-docs.factor b/extra/combinators/tuple/tuple-docs.factor index d0eda50cd4..600986e906 100644 --- a/extra/combinators/tuple/tuple-docs.factor +++ b/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