Merge branch 'master' of git://factorcode.org/git/factor

basis/bootstrap/finish-bootstrap.factor

@@ -8,9 +8,14 @@ namespaces eval kernel vocabs.loader io ;
         (command-line) parse-command-line
         load-vocab-roots
         run-user-init
+
+        "e" get script get or [
             "e" get [ eval( -- ) ] when*
-        ignore-cli-args? not script get and
+            script get [ run-script ] when*
-        [ run-script ] [ "run" get run ] if*
+        ] [
+            "run" get run
+        ] if
+
         output-stream get [ stream-flush ] when*
         0 exit
     ] [ print-error 1 exit ] recover

basis/command-line/command-line-docs.factor

@@ -37,10 +37,6 @@ HELP: main-vocab
 HELP: default-cli-args
 { $description "Sets global variables corresponding to default command line arguments." } ;
 
-HELP: ignore-cli-args?
-{ $values { "?" "a boolean" } }
-{ $description "On Mac OS X, source files to run are supplied by the Cocoa API, so to avoid running them twice the startup code has to call this word." } ;
-
 ARTICLE: "runtime-cli-args" "Command line switches for the VM"
 "A handful of command line switches are processed by the VM and not the library. They control low-level features."
 { $table

basis/command-line/command-line.factor

@@ -67,7 +67,4 @@ SYMBOL: main-vocab-hook
         main-vocab "run" set
     ] bind ;
 
-: ignore-cli-args? ( -- ? )
-    os macosx? "run" get "ui" = and ;
-
 [ default-cli-args ] "command-line" add-startup-hook

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"
+ARTICLE: "eval-vocabs" "Evaluating strings with a different vocabulary search path"
-"The " { $vocab-link "eval" } " vocabulary implements support for evaluating strings at runtime."
+"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/grouping/grouping-tests.factor

@@ -30,3 +30,5 @@ IN: grouping.tests
 [ f ] [ [ 1.0 1 1 ] all-equal? ] unit-test
 [ t ] [ { 1 2 3 4 } [ < ] monotonic? ] unit-test
 [ f ] [ { 1 2 3 4 } [ > ] monotonic? ] unit-test
+
+[ { 6 7 8 3 4 5 0 1 2 } ] [ 9 iota >array dup 3 <groups> reverse! drop ] unit-test

basis/help/crossref/crossref.factor

@@ -7,10 +7,10 @@ IN: help.crossref
 
 : article-links ( topic elements -- seq )
     [ article-content ] dip
-    collect-elements [ >link ] map ;
+    collect-elements ;
 
 : article-children ( topic -- seq )
-    { $subsection $subsections } article-links ;
+    { $subsection $subsections } article-links [ >link ] map ;
 
 : help-path ( topic -- seq )
     [ article-parent ] follow rest ;

basis/help/lint/lint.factor

@@ -69,7 +69,7 @@ PRIVATE>
     '[ _ vocab-help [ article drop ] when* ] check-something ;
 
 : check-vocab ( vocab -- )
-    "Checking " write dup write "..." print
+    "Checking " write dup write "..." print flush
     [ check-about ]
     [ words [ check-word ] each ]
     [ vocab-articles get at [ check-article ] each ]

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"
+ARTICLE: "prettyprint.stylesheet" "Prettyprinter stylesheet"
-{ $vocab-link "prettyprint.stylesheet" }
+"The " { $vocab-link "prettyprint.stylesheet" } " vocabulary defines variables which control the way that the prettyprinter formats output based on object type."
-$nl
-"Control the way that the prettyprinter formats output based on object type. These hooks form a basic \"syntax\" highlighting system."
 { $subsections
     word-style
     string-style

basis/tools/crossref/crossref.factor

@@ -1,9 +1,10 @@
-! Copyright (C) 2005, 2009 Slava Pestov.
+! Copyright (C) 2005, 2010 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: words assocs definitions io io.pathnames io.styles kernel
-prettyprint sorting see sets sequences arrays hashtables help.crossref
+prettyprint sorting see sets sequences arrays hashtables help
-help.topics help.markup quotations accessors source-files namespaces
+help.crossref help.topics help.markup quotations accessors
-graphs vocabs generic generic.single threads compiler.units init ;
+source-files namespaces graphs vocabs generic generic.single
+threads compiler.units init combinators.smart ;
 IN: tools.crossref
 
 SYMBOL: crossref
@@ -50,10 +51,16 @@ M: callable uses ( quot -- assoc )
 
 M: word uses def>> uses ;
 
-M: link uses { $subsection $subsections $link $see-also } article-links ;
+M: link uses
+    [ { $subsection $subsections $link $see-also } article-links [ >link ] map ]
+    [ { $vocab-link } article-links [ >vocab-link ] map ]
+    bi append ;
 
 M: pathname uses string>> source-file top-level-form>> [ uses ] [ { } ] if* ;
 
+! To make UI browser happy
+M: vocab uses drop f ;
+
 GENERIC: crossref-def ( defspec -- )
 
 M: object crossref-def
@@ -62,18 +69,23 @@ M: object crossref-def
 M: word crossref-def
     [ call-next-method ] [ subwords [ crossref-def ] each ] bi ;
 
+: defs-to-crossref ( -- seq )
+    [
+        all-words
+        all-articles [ >link ] map
+        source-files get keys [ <pathname> ] map
+    ] append-outputs ;
+
 : build-crossref ( -- crossref )
     "Computing usage index... " write flush yield
-    H{ } clone crossref [
+    H{ } clone [
-        all-words
+        crossref set-global
-        source-files get keys [ <pathname> ] map
+        defs-to-crossref [ crossref-def ] each
-        [ [ crossref-def ] each ] bi@
+    ] keep
-        crossref get
-    ] with-variable
     "done" print flush ;
 
 : get-crossref ( -- crossref )
-    crossref global [ drop build-crossref ] cache ;
+    crossref get-global [ build-crossref ] unless* ;
 
 GENERIC: irrelevant? ( defspec -- ? )
 

basis/ui/gadgets/gadgets.factor

@@ -1,4 +1,4 @@
-! Copyright (C) 2005, 2009 Slava Pestov.
+! Copyright (C) 2005, 2010 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: accessors arrays hashtables kernel math namespaces
 make sequences quotations math.vectors combinators sorting
@@ -62,18 +62,19 @@ M: gadget children-on nip children>> ;
 
 <PRIVATE
 
-: ((fast-children-on)) ( gadget dim axis -- <=> )
+:: (fast-children-on) ( point axis children quot -- i )
-    [ swap loc>> v- ] dip v. 0 <=> ;
+    children [
-
+        [ point ] dip
-:: (fast-children-on) ( dim axis children -- i )
+        quot call( value -- loc ) v-
-    children [ dim axis ((fast-children-on)) ] search drop ;
+        axis v. 0 <=>
+    ] search drop ; inline
 
 PRIVATE>
 
-: fast-children-on ( rect axis children -- from to )
+:: fast-children-on ( rect axis children quot -- slice )
-    [ [ loc>> ] 2dip (fast-children-on) 0 or ]
+    rect loc>> axis children quot (fast-children-on) 0 or
-    [ [ rect-bounds v+ ] 2dip (fast-children-on) ?1+ ]
+    rect rect-bounds v+ axis children quot (fast-children-on) ?1+
-    3bi ;
+    children <slice> ; inline
 
 M: gadget contains-rect? ( bounds gadget -- ? )
     dup visible?>> [ call-next-method ] [ 2drop f ] if ;

basis/ui/gadgets/grids/grids-tests.factor

@@ -1,12 +1,14 @@
 USING: ui.gadgets ui.gadgets.grids tools.test kernel arrays
 namespaces math.rectangles accessors ui.gadgets.grids.private
-ui.gadgets.debug sequences ;
+ui.gadgets.debug sequences classes ;
 IN: ui.gadgets.grids.tests
 
 [ { 0 0 } ] [ { } <grid> pref-dim ] unit-test
 
 : 100x100 ( -- gadget ) <gadget> { 100 100 } >>dim ;
 
+: 200x200 ( -- gadget ) <gadget> { 200 200 } >>dim ;
+
 [ { 100 100 } ] [
     100x100
     1array 1array <grid> pref-dim
@@ -82,3 +84,21 @@ IN: ui.gadgets.grids.tests
     dup layout
     children>> [ loc>> ] map
 ] unit-test
+
+! children-on logic was insufficient
+[ ] [
+    100x100 dup "a" set 200x200 2array
+    100x100 dup "b" set 200x200 2array 2array <grid> f >>fill? "g" set
+] unit-test
+
+[ ] [ "g" get prefer ] unit-test
+[ ] [ "g" get layout ] unit-test
+
+[ { 0 50 } ] [ "a" get loc>> ] unit-test
+[ { 0 250 } ] [ "b" get loc>> ] unit-test
+
+[ gadget { 200 200 } ]
+[ { 120 20 } "g" get pick-up [ class ] [ dim>> ] bi ] unit-test
+
+[ gadget { 200 200 } ]
+[ { 120 220 } "g" get pick-up [ class ] [ dim>> ] bi ] unit-test

basis/ui/gadgets/grids/grids.factor

@@ -1,7 +1,8 @@
-! Copyright (C) 2006, 2009 Slava Pestov.
+! Copyright (C) 2006, 2010 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: arrays kernel math math.order math.matrices namespaces make sequences words io
+USING: arrays kernel math math.order math.matrices namespaces
-math.vectors ui.gadgets ui.baseline-alignment columns accessors strings.tables
+make sequences words io math.vectors ui.gadgets
+ui.baseline-alignment columns accessors strings.tables
 math.rectangles fry ;
 IN: ui.gadgets.grids
 
@@ -115,8 +116,10 @@ M: grid layout* [ grid>> ] [ <grid-layout> ] bi grid-layout ;
 
 M: grid children-on ( rect gadget -- seq )
     dup children>> empty? [ 2drop f ] [
-        [ { 0 1 } ] dip grid>>
+        [ { 0 1 } ] dip
-        [ 0 <column> fast-children-on ] [ <slice> concat ] bi
+        [ grid>> ] [ dim>> ] bi
+        '[ _ [ loc>> vmin ] reduce ] fast-children-on
+        concat
     ] if ;
 
 M: grid gadget-text*

basis/ui/gadgets/packs/packs.factor

@@ -1,4 +1,4 @@
-! Copyright (C) 2005, 2009 Slava Pestov.
+! Copyright (C) 2005, 2010 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: sequences ui.gadgets ui.baseline-alignment
 ui.baseline-alignment.private kernel math math.functions math.vectors
@@ -100,5 +100,4 @@ M: pack layout*
     dup children>> pref-dims pack-layout ;
 
 M: pack children-on ( rect gadget -- seq )
-    [ orientation>> ] [ children>> ] bi
+    [ orientation>> ] [ children>> ] bi [ loc>> ] fast-children-on ;
-    [ fast-children-on ] keep <slice> ;

basis/ui/gadgets/panes/panes.factor

@@ -1,4 +1,4 @@
-! Copyright (C) 2005, 2009 Slava Pestov.
+! Copyright (C) 2005, 2010 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: arrays hashtables io kernel namespaces sequences
 strings quotations math opengl combinators memoize math.vectors
@@ -352,7 +352,8 @@ M: paragraph stream-format
 GENERIC: sloppy-pick-up* ( loc gadget -- n )
 
 M: pack sloppy-pick-up* ( loc gadget -- n )
-    [ orientation>> ] [ children>> ] bi (fast-children-on) ;
+    [ orientation>> ] [ children>> ] bi
+    [ loc>> ] (fast-children-on) ;
 
 M: gadget sloppy-pick-up*
     children>> [ contains-point? ] with find-last drop ;

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" } "."
+"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" } "."
-{ $subsections "parser-files" }
+$nl
-"The parser can be extended."
+"The parser can be invoked reflectively, to run strings and source files."
-{ $subsections "parser-lexer" }
+{ $subsections
-"The parser can be invoked reflectively;"
+    "eval"
-{ $subsections parse-stream }
+    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

extra/mason/child/child-tests.factor

@@ -1,7 +1,7 @@
 IN: mason.child.tests
 USING: mason.child mason.config tools.test namespaces io kernel sequences ;
 
-[ { "make" "winnt-x86-32" } ] [
+[ { "nmake" "/f" "nmakefile" } ] [
     [
         "winnt" target-os set
         "x86.32" target-cpu set

extra/mason/child/child.factor

@@ -1,14 +1,17 @@
-! Copyright (C) 2008, 2009 Eduardo Cavazos, Slava Pestov.
+! Copyright (C) 2008, 2010 Eduardo Cavazos, Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: accessors arrays calendar combinators.short-circuit fry
 continuations debugger io.directories io.files io.launcher
 io.pathnames io.encodings.ascii kernel make mason.common mason.config
 mason.platform mason.report mason.notify namespaces sequences
-quotations macros ;
+quotations macros system combinators ;
 IN: mason.child
 
 : make-cmd ( -- args )
-    gnu-make platform 2array ;
+    {
+        { [ target-os get "winnt" = ] [ { "nmake" "/f" "nmakefile" } ] }
+        [ gnu-make platform 2array ]
+    } cond ;
 
 : make-vm ( -- )
     "factor" [