Fix circularity

core/alien/alien.factor

@@ -1,16 +1,24 @@
-! Copyright (C) 2004, 2007 Slava Pestov.
+! Copyright (C) 2004, 2008 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-IN: alien
 USING: assocs kernel math namespaces sequences system
-byte-arrays bit-arrays float-arrays kernel.private tuples ;
+kernel.private tuples ;
+IN: alien
 
 ! Some predicate classes used by the compiler for optimization
 ! purposes
 PREDICATE: alien simple-alien
     underlying-alien not ;
 
-UNION: simple-c-ptr
+! These mixins are not intended to be extended by user code.
-    simple-alien byte-array bit-array float-array POSTPONE: f ;
+! They are not unions, because if they were we'd have a circular
+! dependency between alien and {byte,bit,float}-arrays.
+MIXIN: simple-c-ptr
+INSTANCE: simple-alien simple-c-ptr
+INSTANCE: f simple-c-ptr
+
+MIXIN: c-ptr
+INSTANCE: alien c-ptr
+INSTANCE: f c-ptr
 
 DEFER: pinned-c-ptr?
 
@@ -20,9 +28,6 @@ PREDICATE: alien pinned-alien
 UNION: pinned-c-ptr
     pinned-alien POSTPONE: f ;
 
-UNION: c-ptr
-    alien bit-array byte-array float-array POSTPONE: f ;
-
 M: f expired? drop t ;
 
 : <alien> ( address -- alien )
@@ -47,9 +52,7 @@ M: alien equal?
 
 SYMBOL: libraries
 
-global [
+libraries global [ H{ } assoc-like ] change-at
-    libraries [ H{ } assoc-like ] change
-] bind
 
 TUPLE: library path abi dll ;
 

core/arrays/arrays-docs.factor

@@ -1,6 +1,5 @@
-USING: byte-arrays bit-arrays help.markup help.syntax
+USING: help.markup help.syntax
-kernel kernel.private prettyprint strings sbufs vectors
+kernel kernel.private prettyprint sequences.private ;
-quotations sequences.private ;
 IN: arrays
 
 ARTICLE: "arrays" "Arrays"
@@ -34,16 +33,10 @@ HELP: <array> ( n elt -- array )
 { $values { "n" "a non-negative integer" } { "elt" "an initial element" } { "array" "a new array" } }
 { $description "Creates a new array with the given length and all elements initially set to " { $snippet "elt" } "." } ;
 
-{ <array> <string> <sbuf> <vector> <byte-array> <bit-array> }
-related-words
-
 HELP: >array
 { $values { "seq" "a sequence" } { "array" array } }
 { $description "Outputs a freshly-allocated array with the same elements as a given sequence." } ;
 
-{ >array >quotation >string >sbuf >vector >byte-array >bit-array }
-related-words
-
 HELP: 1array
 { $values { "x" object } { "array" array } }
 { $description "Create a new array with one element." } ;

core/bit-arrays/bit-arrays.factor

@@ -1,4 +1,4 @@
-! Copyright (C) 2007 Slava Pestov.
+! Copyright (C) 2007, 2008 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 USING: math alien kernel kernel.private sequences
 sequences.private ;
@@ -49,3 +49,5 @@ M: bit-array equal?
     over bit-array? [ sequence= ] [ 2drop f ] if ;
 
 INSTANCE: bit-array sequence
+INSTANCE: bit-array simple-c-ptr
+INSTANCE: bit-array c-ptr

core/byte-arrays/byte-arrays-docs.factor

@@ -1,5 +1,4 @@
-USING: arrays bit-arrays vectors strings sbufs
+USING: help.markup help.syntax ;
-kernel help.markup help.syntax ;
 IN: byte-arrays
 
 ARTICLE: "byte-arrays" "Byte arrays"

core/byte-arrays/byte-arrays.factor

@@ -1,8 +1,8 @@
-! Copyright (C) 2007 Slava Pestov.
+! Copyright (C) 2007, 2008 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
+USING: kernel kernel.private alien sequences sequences.private
+math ;
 IN: byte-arrays
-USING: kernel kernel.private alien sequences
-sequences.private math ;
 
 M: byte-array clone (clone) ;
 M: byte-array length array-capacity ;
@@ -16,3 +16,5 @@ M: byte-array equal?
     over byte-array? [ sequence= ] [ 2drop f ] if ;
 
 INSTANCE: byte-array sequence
+INSTANCE: byte-array simple-c-ptr
+INSTANCE: byte-array c-ptr

core/float-arrays/float-arrays.factor

@@ -1,8 +1,8 @@
-! Copyright (C) 2007 Slava Pestov.
+! Copyright (C) 2007, 2008 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-IN: float-arrays
 USING: kernel kernel.private alien sequences
 sequences.private math math.private ;
+IN: float-arrays
 
 <PRIVATE
 
@@ -30,6 +30,8 @@ M: float-array equal?
     over float-array? [ sequence= ] [ 2drop f ] if ;
 
 INSTANCE: float-array sequence
+INSTANCE: float-array simple-c-ptr
+INSTANCE: float-array c-ptr
 
 : 1float-array ( x -- array ) 1 swap <float-array> ; flushable
 

core/sequences/sequences-docs.factor

@@ -1,6 +1,5 @@
 USING: arrays bit-arrays help.markup help.syntax
-sequences.private vectors strings sbufs kernel math math.vectors
+sequences.private vectors strings sbufs kernel math ;
-;
 IN: sequences
 
 ARTICLE: "sequences-unsafe" "Unsafe sequence operations"
@@ -483,14 +482,12 @@ HELP: 2reduce
                    { $snippet "( prev elt1 elt2 -- next )" } }
           { "result" "the final result" } }
 { $description "Combines successive pairs of elements from the two sequences using a ternary operation. The first input value at each iteration except the first one is the result of the previous iteration. The first input value at the first iteration is " { $snippet "identity" } "." }
-{ $examples "The " { $link v. } " word provides a particularly elegant implementation of the dot product." }
 { $notes "If one sequence is shorter than the other, then only the prefix having the length of the minimum of the two is examined." } ;
 
 HELP: 2map
 { $values { "seq1" sequence } { "seq2" sequence } { "quot" "a quotation with stack effect " { $snippet "( elt1 elt2 -- new )" } } { "newseq" "a new sequence" } }
 { $description "Applies the quotation to each pair of elements in turn, yielding new elements which are collected into a new sequence having the same class as " { $snippet "seq1" } "." }
-{ $notes "If one sequence is shorter than the other, than only the prefix having the length of the minimum of the two is examined." }
+{ $notes "If one sequence is shorter than the other, than only the prefix having the length of the minimum of the two is examined." } ;
-{ $see-also v+ v- v* v/ } ;
 
 HELP: 2all?
 { $values { "seq1" sequence } { "seq2" sequence } { "quot" "a quotation with stack effect " { $snippet "( elt1 elt2 -- ? )" } } { "?" "a boolean" } }

core/vocabs/loader/loader.factor

@@ -68,11 +68,9 @@ SYMBOL: load-help?
 : source-wasn't-loaded f swap set-vocab-source-loaded? ;
 
 : load-source ( root name -- )
-    [ source-was-loaded ] keep [
+    [ source-wasn't-loaded ] keep
-        [ vocab-source path+ bootstrap-file ]
+    [ vocab-source path+ bootstrap-file ] keep
-        [ ] [ source-wasn't-loaded ]
+    source-was-loaded ;
-        cleanup
-    ] keep source-was-loaded ;
 
 : docs-were-loaded t swap set-vocab-docs-loaded? ;
 
@@ -80,14 +78,10 @@ SYMBOL: load-help?
 
 : load-docs ( root name -- )
     load-help? get [
-        [ docs-were-loaded ] keep [
+        [ docs-weren't-loaded ] keep
-            [ vocab-docs path+ ?run-file ]
+        [ vocab-docs path+ ?run-file ] keep
-            [ ] [ docs-weren't-loaded ]
+        docs-were-loaded
-            cleanup
+    ] [ 2drop ] if ;
-        ] keep docs-were-loaded
-    ] [
-        2drop
-    ] if ;
 
 : amend-vocab-from-root ( root name -- vocab )
     dup vocab-source-loaded? [ 2dup load-source ] unless

extra/bootstrap/help/help.factor

@@ -6,6 +6,7 @@ IN: bootstrap.help
 : load-help
     t load-help? set-global
 
+    [ vocab ] load-vocab-hook [
         vocabs
         [ vocab-root ] subset
         [ vocab-source-loaded? ] subset
@@ -16,6 +17,7 @@ IN: bootstrap.help
                 dup vocab-root swap load-docs
             ] if
         ] each
+    ] with-variable
 
     "help.handbook" require ;
 

extra/destructors/destructors-docs.factor

@@ -1,4 +1,4 @@
-USING: help.markup help.syntax libc kernel destructors ;
+USING: help.markup help.syntax libc kernel ;
 IN: destructors
 
 HELP: free-always
@@ -27,5 +27,4 @@ HELP: with-destructors
 { $notes "Destructors are not allowed to throw exceptions.  No exceptions." }
 { $examples
     { $code "[ 10 malloc free-always ] with-destructors" }
-}
+} ;
-{ $see-also } ;

extra/help/handbook/handbook.factor

@@ -1,7 +1,8 @@
 USING: help help.markup help.syntax help.topics
 namespaces words sequences classes assocs vocabs kernel
 arrays prettyprint.backend kernel.private io tools.browser
-generic math tools.profiler system ui ;
+generic math tools.profiler system ui strings sbufs vectors
+byte-arrays bit-arrays float-arrays quotations ;
 IN: help.handbook
 
 ARTICLE: "conventions" "Conventions"
@@ -345,3 +346,9 @@ ARTICLE: "changes" "Changes in the latest release"
     "Solaris/x86 fixes. (Samuel Tardieu)"
     "Linux/AMD64 port works again."
 } ;
+
+{ <array> <string> <sbuf> <vector> <byte-array> <bit-array> <float-array> }
+related-words
+
+{ >array >quotation >string >sbuf >vector >byte-array >bit-array >float-array }
+related-words

extra/help/help-docs.factor

@@ -1,5 +1,6 @@
-USING: help.markup help.crossref help.topics help.syntax
+USING: help.markup help.crossref help.stylesheet help.topics
-definitions io prettyprint inspector arrays math ;
+help.syntax definitions io prettyprint inspector arrays math
+sequences vocabs ;
 IN: help
 
 ARTICLE: "printing-elements" "Printing markup elements"
@@ -59,6 +60,9 @@ ARTICLE: "element-types" "Element types"
 { $subsection "block-elements" }
 { $subsection "markup-utils" } ;
 
+IN: help.markup
+ABOUT: "element-types"
+
 ARTICLE: "browsing-help" "Browsing documentation"
 "The easiest way to browse the help is from the help browser tool in the UI, however you can also display help topics in the listener. Help topics are identified by article name strings, or words. You can request a specific help topic:"
 { $subsection help }
@@ -112,6 +116,7 @@ ARTICLE: "help" "Help system"
 { $subsection "help.lint" }
 { $subsection "help-impl" } ;
 
+IN: help
 ABOUT: "help"
 
 HELP: $title
@@ -161,4 +166,239 @@ HELP: $predicate
 { $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
 { $description "Prints the boilerplate description of a class membership predicate word such as " { $link array? } " or " { $link integer? } "." } ;
 
+HELP: print-element
+{ $values { "element" "a markup element" } }
+{ $description "Prints a markup element to the " { $link stdio } " stream." } ;
+
+HELP: print-content
+{ $values { "element" "a markup element" } }
+{ $description "Prints a top-level markup element to the " { $link stdio } " stream." } ;
+
+HELP: simple-element
+{ $class-description "Class of simple elements, which are just arrays of elements." } ;
+
+HELP: ($span)
+{ $values { "quot" "a quotation" } }
+{ $description "Prints an inline markup element." } ;
+
+HELP: ($block)
+{ $values { "quot" "a quotation" } }
+{ $description "Prints a block markup element with newlines before and after." } ;
+
+HELP: $heading
+{ $values { "element" "a markup element" } }
+{ $description "Prints a markup element, usually a string, as a block with the " { $link heading-style } "." }
+{ $examples
+    { $markup-example { $heading "What remains to be discovered" } }
+} ;
+
+HELP: $subheading
+{ $values { "element" "a markup element of the form " { $snippet "{ title content }" } } }
+{ $description "Prints a markup element, usually a string, as a block with the " { $link strong-style } "." }
+{ $examples
+    { $markup-example { $subheading "Developers, developers, developers!" } }
+} ;
+
+HELP: $code
+{ $values { "element" "a markup element of the form " { $snippet "{ string... }" } } }
+{ $description "Prints code examples, as seen in many help articles. The markup element must be an array of strings." }
+{ $notes
+    "The code becomes clickable if the output stream supports it, and clicking it opens a listener window with the text inserted at the input prompt."
+    $nl
+    "If you want to show code along with sample output, use the " { $link $example } " element."
+}
+{ $examples
+    { $markup-example { $code "2 2 + ." } }
+} ;
+
+HELP: $vocabulary
+{ $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
+{ $description "Prints a word's vocabulary. This markup element is automatically output by the help system, so help descriptions of parsing words should not call it." } ;
+
+HELP: $description
+{ $values { "element" "a markup element" } }
+{ $description "Prints the description subheading found on the help page of most words." } ;
+
+HELP: $contract
+{ $values { "element" "a markup element" } }
+{ $description "Prints a heading followed by a contract, found on the help page of generic words. Every generic word should document a contract which specifies method behavior that callers can rely upon, and implementations must obey." }
+{ $examples
+    { $markup-example { $contract "Methods of this generic word must always crash." } }
+} ;
+
+HELP: $examples
+{ $values { "element" "a markup element" } }
+{ $description "Prints a heading followed by some examples. Word documentation should include examples, at least if the usage of the word is not entirely obvious." }
+{ $examples
+    { $markup-example { $examples { $example "2 2 + ." "4" } } }
+} ;
+
+HELP: $example
+{ $values { "element" "a markup element of the form " { $snippet "{ inputs... output }" } } }
+{ $description "Prints a clickable example with sample output. The markup element must be an array of strings. All but the last string are joined by newlines and taken as the input text, and the last string is the output. The example becomes clickable if the output stream supports it, and clicking it opens a listener window with the input text inserted at the input prompt." }
+{ $examples
+    "The output text should be a string of what the input prints when executed, not the final stack contents or anything like that. So the following is an incorrect example:"
+    { $markup-example { $unchecked-example "2 2 +" "4" } }
+    "However the following is right:"
+    { $markup-example { $example "2 2 + ." "4" } }
+    "Examples can incorporate a call to " { $link .s } " to show multiple output values; the convention is that you may assume the stack is empty before the example evaluates."
+} ;
+
+HELP: $markup-example
+{ $values { "element" "a markup element" } }
+{ $description "Prints a clickable example showing the prettyprinted source text of " { $snippet "element" } " followed by rendered output. The example becomes clickable if the output stream supports it." }
+{ $examples
+    { $markup-example { $markup-example { $emphasis "Hi" } } }
+} ;
+
+HELP: $warning
+{ $values { "element" "a markup element" } }
+{ $description "Prints an element inset in a block styled as so to draw the reader's attention towards it." }
+{ $examples
+    { $markup-example { $warning "Incorrect use of this product may cause serious injury or death." } }
+} ;
+
+HELP: $link
+{ $values { "element" "a markup element of the form " { $snippet "{ topic }" } } }
+{ $description "Prints a link to a help article or word." }
+{ $examples
+    { $markup-example { $link "dlists" } }
+    { $markup-example { $link + } }
+} ;
+
+HELP: textual-list
+{ $values { "seq" "a sequence" } { "quot" "a quotation with stack effect " { $snippet "( elt -- )" } } }
+{ $description "Applies the quotation to each element of the sequence, printing a comma between each pair of elements." }
+{ $examples
+    { $example "USE: help.markup" "{ \"fish\" \"chips\" \"salt\" } [ write ] textual-list" "fish, chips, salt" }
+} ;
+
+HELP: $links
+{ $values { "topics" "a sequence of article names or words" } }
+{ $description "Prints a series of links to help articles or word documentation." }
+{ $notes "This markup element is used to implement " { $link $links } "." }
+{ $examples
+    { $markup-example { $links + - * / } }
+} ;
+
+HELP: $see-also
+{ $values { "topics" "a sequence of article names or words" } }
+{ $description "Prints a heading followed by a series of links." }
+{ $examples
+    { $markup-example { $see-also "graphs" "dlists" } }
+} ;
+
+{ $see-also $related related-words } related-words
+
+HELP: $table
+{ $values { "element" "an array of arrays of markup elements" } }
+{ $description "Prints a table given as an array of rows, where each row must have the same number of columns." }
+{ $examples
+    { $markup-example
+        { $table
+            { "a" "b" "c" }
+            { "d" "e" "f" }
+        }
+    }
+} ;
+
+HELP: $values
+{ $values { "element" "an array of pairs of markup elements" } }
+{ $description "Prints the description of arguments and values found on every word help page. The first element of a pair is the argument name and is output with " { $link $snippet } ". The remainder can be an element of any form." } ;
+
+HELP: $list
+{ $values { "element" "an array of markup elements" } }
+{ $description "Prints a bulleted list of markup elements." }
+{ $notes
+    "A common mistake is that if an item consists of more than just a string, it will be broken up as several items:"
+    { $markup-example
+        { $list
+            "First item"
+            "Second item " { $emphasis "with emphasis" }
+        }
+    }
+    "The fix is easy; just group the two markup elements making up the second item into one markup element:"
+    { $markup-example
+        { $list
+            "First item"
+            { "Second item " { $emphasis "with emphasis" } }
+        }
+    }
+} ;
+
+HELP: $errors
+{ $values { "element" "a markup element" } }
+{ $description "Prints the errors subheading found on the help page of some words. This section should document any errors thrown by the word." }
+{ $examples
+    { $markup-example { $errors "I/O errors, network errors, hardware errors... oh my!" } }
+} ;
+
+HELP: $side-effects
+{ $values { "element" "a markup element of the form " { $snippet "{ string... }" } } }
+{ $description "Prints a heading followed by a list of input values or variables which are modified by the word being documented." }
+{ $examples
+    { $markup-example
+        { { $values { "seq" "a mutable sequence" } } { $side-effects "seq" } }
+    }
+} ;
+
+HELP: $notes
+{ $values { "element" "a markup element" } }
+{ $description "Prints the errors subheading found on the help page of some words. This section should usage tips and pitfalls." } ;
+
+HELP: $see
+{ $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
+{ $description "Prints the definition of " { $snippet "word" } " by calling " { $link see } "." }
+{ $examples
+    { $markup-example { "Here is a word definition:" { $see reverse } } }
+} ;
+
+HELP: $definition
+{ $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
+{ $description "Prints a heading followed by the definition of " { $snippet "word" } " by calling " { $link see } "." } ;
+
+HELP: $curious
+{ $values { "element" "a markup element" } }
+{ $description "Prints a heading followed by a markup element." }
+{ $notes "This element type is used by the cookbook-style introductory articles in the " { $link "handbook" } "." } ;
+
+HELP: $references
+{ $values { "element" "a markup element of the form " { $snippet "{ topic... }" } } }
+{ $description "Prints a heading followed by a series of links." }
+{ $notes "This element type is used by the cookbook-style introductory articles in the " { $link "handbook" } "." } ;
+
+HELP: HELP:
+{ $syntax "HELP: word content... ;" }
+{ $values { "word" "a word" } { "content" "markup elements" } }
+{ $description "Defines documentation for a word." }
+{ $examples
+    { $code
+        ": foo 2 + ;"
+        "HELP: foo"
+        "{ $values { \"m\" \"an integer\" } { \"n\" \"an integer\" } }"
+        "{ $description \"Increments a value by 2.\" } ;"
+        "\\ foo help"
+    }
+} ;
+
+HELP: ARTICLE:
+{ $syntax "ARTICLE: topic title content... ;" }
+{ $values { "topic" "an object" } { "title" "a string" } { "content" "markup elements" } }
+{ $description "Defines a help article. String topic names are reserved for core documentation. Contributed modules should name articles by arrays, where the first element of an array identifies the module; for example, " { $snippet "{ \"httpd\" \"intro\" }" } "." }
+{ $examples
+    { $code
+        "ARTICLE: \"example\" \"An example article\""
+        "\"Hello world.\" ;"
+    }
+} ;
+
+HELP: ABOUT:
+{ $syntax "MAIN: article" }
+{ $values { "article" "a help article" } }
+{ $description "Defines the main documentation article for the current vocabulary." } ;
+
+HELP: vocab-help
+{ $values { "vocab" "a vocabulary specifier" } { "help" "a help article" } }
+{ $description "Outputs the main help article for a vocabulary. The main help article can be set with " { $link POSTPONE: ABOUT:  } "." } ;
+
 USE: help.lint

extra/help/markup/markup-docs.factor

@@ -1,206 +0,0 @@
-USING: help.syntax help.stylesheet arrays
-definitions io math prettyprint sequences ;
-IN: help.markup
-
-ABOUT: "element-types"
-
-HELP: print-element
-{ $values { "element" "a markup element" } }
-{ $description "Prints a markup element to the " { $link stdio } " stream." } ;
-
-HELP: print-content
-{ $values { "element" "a markup element" } }
-{ $description "Prints a top-level markup element to the " { $link stdio } " stream." } ;
-
-HELP: simple-element
-{ $class-description "Class of simple elements, which are just arrays of elements." } ;
-
-HELP: ($span)
-{ $values { "quot" "a quotation" } }
-{ $description "Prints an inline markup element." } ;
-
-HELP: ($block)
-{ $values { "quot" "a quotation" } }
-{ $description "Prints a block markup element with newlines before and after." } ;
-
-HELP: $heading
-{ $values { "element" "a markup element" } }
-{ $description "Prints a markup element, usually a string, as a block with the " { $link heading-style } "." }
-{ $examples
-    { $markup-example { $heading "What remains to be discovered" } }
-} ;
-
-HELP: $subheading
-{ $values { "element" "a markup element of the form " { $snippet "{ title content }" } } }
-{ $description "Prints a markup element, usually a string, as a block with the " { $link strong-style } "." }
-{ $examples
-    { $markup-example { $subheading "Developers, developers, developers!" } }
-} ;
-
-HELP: $code
-{ $values { "element" "a markup element of the form " { $snippet "{ string... }" } } }
-{ $description "Prints code examples, as seen in many help articles. The markup element must be an array of strings." }
-{ $notes
-    "The code becomes clickable if the output stream supports it, and clicking it opens a listener window with the text inserted at the input prompt."
-    $nl
-    "If you want to show code along with sample output, use the " { $link $example } " element."
-}
-{ $examples
-    { $markup-example { $code "2 2 + ." } }
-} ;
-
-HELP: $vocabulary
-{ $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
-{ $description "Prints a word's vocabulary. This markup element is automatically output by the help system, so help descriptions of parsing words should not call it." } ;
-
-HELP: $description
-{ $values { "element" "a markup element" } }
-{ $description "Prints the description subheading found on the help page of most words." } ;
-
-HELP: $contract
-{ $values { "element" "a markup element" } }
-{ $description "Prints a heading followed by a contract, found on the help page of generic words. Every generic word should document a contract which specifies method behavior that callers can rely upon, and implementations must obey." }
-{ $examples
-    { $markup-example { $contract "Methods of this generic word must always crash." } }
-} ;
-
-HELP: $examples
-{ $values { "element" "a markup element" } }
-{ $description "Prints a heading followed by some examples. Word documentation should include examples, at least if the usage of the word is not entirely obvious." }
-{ $examples
-    { $markup-example { $examples { $example "2 2 + ." "4" } } }
-} ;
-
-HELP: $example
-{ $values { "element" "a markup element of the form " { $snippet "{ inputs... output }" } } }
-{ $description "Prints a clickable example with sample output. The markup element must be an array of strings. All but the last string are joined by newlines and taken as the input text, and the last string is the output. The example becomes clickable if the output stream supports it, and clicking it opens a listener window with the input text inserted at the input prompt." }
-{ $examples
-    "The output text should be a string of what the input prints when executed, not the final stack contents or anything like that. So the following is an incorrect example:"
-    { $markup-example { $unchecked-example "2 2 +" "4" } }
-    "However the following is right:"
-    { $markup-example { $example "2 2 + ." "4" } }
-    "Examples can incorporate a call to " { $link .s } " to show multiple output values; the convention is that you may assume the stack is empty before the example evaluates."
-} ;
-
-HELP: $markup-example
-{ $values { "element" "a markup element" } }
-{ $description "Prints a clickable example showing the prettyprinted source text of " { $snippet "element" } " followed by rendered output. The example becomes clickable if the output stream supports it." }
-{ $examples
-    { $markup-example { $markup-example { $emphasis "Hi" } } }
-} ;
-
-HELP: $warning
-{ $values { "element" "a markup element" } }
-{ $description "Prints an element inset in a block styled as so to draw the reader's attention towards it." }
-{ $examples
-    { $markup-example { $warning "Incorrect use of this product may cause serious injury or death." } }
-} ;
-
-HELP: $link
-{ $values { "element" "a markup element of the form " { $snippet "{ topic }" } } }
-{ $description "Prints a link to a help article or word." }
-{ $examples
-    { $markup-example { $link "dlists" } }
-    { $markup-example { $link + } }
-} ;
-
-HELP: textual-list
-{ $values { "seq" "a sequence" } { "quot" "a quotation with stack effect " { $snippet "( elt -- )" } } }
-{ $description "Applies the quotation to each element of the sequence, printing a comma between each pair of elements." }
-{ $examples
-    { $example "USE: help.markup" "{ \"fish\" \"chips\" \"salt\" } [ write ] textual-list" "fish, chips, salt" }
-} ;
-
-HELP: $links
-{ $values { "topics" "a sequence of article names or words" } }
-{ $description "Prints a series of links to help articles or word documentation." }
-{ $notes "This markup element is used to implement " { $link $links } "." }
-{ $examples
-    { $markup-example { $links + - * / } }
-} ;
-
-HELP: $see-also
-{ $values { "topics" "a sequence of article names or words" } }
-{ $description "Prints a heading followed by a series of links." }
-{ $examples
-    { $markup-example { $see-also "graphs" "dlists" } }
-} ;
-
-{ $see-also $related related-words } related-words
-
-HELP: $table
-{ $values { "element" "an array of arrays of markup elements" } }
-{ $description "Prints a table given as an array of rows, where each row must have the same number of columns." }
-{ $examples
-    { $markup-example
-        { $table
-            { "a" "b" "c" }
-            { "d" "e" "f" } 
-        }
-    }
-} ;
-
-HELP: $values
-{ $values { "element" "an array of pairs of markup elements" } }
-{ $description "Prints the description of arguments and values found on every word help page. The first element of a pair is the argument name and is output with " { $link $snippet } ". The remainder can be an element of any form." } ;
-
-HELP: $list
-{ $values { "element" "an array of markup elements" } }
-{ $description "Prints a bulleted list of markup elements." }
-{ $notes
-    "A common mistake is that if an item consists of more than just a string, it will be broken up as several items:"
-    { $markup-example
-        { $list
-            "First item"
-            "Second item " { $emphasis "with emphasis" }
-        }
-    }
-    "The fix is easy; just group the two markup elements making up the second item into one markup element:"
-    { $markup-example
-        { $list
-            "First item"
-            { "Second item " { $emphasis "with emphasis" } }
-        }
-    }
-} ;
-
-HELP: $errors
-{ $values { "element" "a markup element" } }
-{ $description "Prints the errors subheading found on the help page of some words. This section should document any errors thrown by the word." }
-{ $examples
-    { $markup-example { $errors "I/O errors, network errors, hardware errors... oh my!" } }
-} ;
-
-HELP: $side-effects
-{ $values { "element" "a markup element of the form " { $snippet "{ string... }" } } }
-{ $description "Prints a heading followed by a list of input values or variables which are modified by the word being documented." }
-{ $examples
-    { $markup-example
-        { { $values { "seq" "a mutable sequence" } } { $side-effects "seq" } }
-    }
-} ;
-
-HELP: $notes
-{ $values { "element" "a markup element" } }
-{ $description "Prints the errors subheading found on the help page of some words. This section should usage tips and pitfalls." } ;
-
-HELP: $see
-{ $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
-{ $description "Prints the definition of " { $snippet "word" } " by calling " { $link see } "." }
-{ $examples
-    { $markup-example { "Here is a word definition:" { $see reverse } } }
-} ;
-
-HELP: $definition
-{ $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
-{ $description "Prints a heading followed by the definition of " { $snippet "word" } " by calling " { $link see } "." } ;
-
-HELP: $curious
-{ $values { "element" "a markup element" } }
-{ $description "Prints a heading followed by a markup element." }
-{ $notes "This element type is used by the cookbook-style introductory articles in the " { $link "handbook" } "." } ;
-
-HELP: $references
-{ $values { "element" "a markup element of the form " { $snippet "{ topic... }" } } }
-{ $description "Prints a heading followed by a series of links." }
-{ $notes "This element type is used by the cookbook-style introductory articles in the " { $link "handbook" } "." } ;

extra/help/syntax/syntax-docs.factor

@@ -1,35 +0,0 @@
-USING: help.markup help.syntax vocabs ;
-
-HELP: HELP:
-{ $syntax "HELP: word content... ;" }
-{ $values { "word" "a word" } { "content" "markup elements" } }
-{ $description "Defines documentation for a word." }
-{ $examples
-    { $code
-        ": foo 2 + ;"
-        "HELP: foo"
-        "{ $values { \"m\" \"an integer\" } { \"n\" \"an integer\" } }"
-        "{ $description \"Increments a value by 2.\" } ;"
-        "\\ foo help"
-    }
-} ;
-
-HELP: ARTICLE:
-{ $syntax "ARTICLE: topic title content... ;" }
-{ $values { "topic" "an object" } { "title" "a string" } { "content" "markup elements" } }
-{ $description "Defines a help article. String topic names are reserved for core documentation. Contributed modules should name articles by arrays, where the first element of an array identifies the module; for example, " { $snippet "{ \"httpd\" \"intro\" }" } "." }
-{ $examples
-    { $code
-        "ARTICLE: \"example\" \"An example article\""
-        "\"Hello world.\" ;"
-    }
-} ;
-
-HELP: ABOUT:
-{ $syntax "MAIN: article" }
-{ $values { "article" "a help article" } }
-{ $description "Defines the main documentation article for the current vocabulary." } ;
-
-HELP: vocab-help
-{ $values { "vocab" "a vocabulary specifier" } { "help" "a help article" } }
-{ $description "Outputs the main help article for a vocabulary. The main help article can be set with " { $link POSTPONE: ABOUT:  } "." } ;

extra/io/launcher/launcher-docs.factor

@@ -1,6 +1,6 @@
 ! Copyright (C) 2007 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: help.markup help.syntax io.launcher quotations kernel ;
+USING: help.markup help.syntax quotations kernel ;
 IN: io.launcher
 
 HELP: +command+

extra/math/vectors/vectors-docs.factor

@@ -100,3 +100,7 @@ HELP: set-axis
 { $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "axis" "a sequence of 0/1" } { "w" "a sequence of numbers" } }
 { $description "Using " { $snippet "w" } " as a template, creates a new sequence containing corresponding elements from " { $snippet "u" } " in place of 0, and corresponding elements from " { $snippet "v" } " in place of 1." }
 { $examples { $example "USE: math.vectors" "{ 1 2 3 } { 4 5 6 } { 0 1 0 } set-axis ." "{ 1 5 3 }" } } ;
+
+{ 2map v+ v- v* v/ } related-words
+
+{ 2reduce v. } related-words

extra/qualified/qualified-docs.factor

@@ -1,4 +1,5 @@
-USING: qualified help.markup help.syntax ;
+USING: help.markup help.syntax ;
+IN: qualified
 
 HELP: QUALIFIED:
 { $syntax "QUALIFIED: vocab" }

extra/shuffle/shuffle-docs.factor

@@ -1,6 +1,7 @@
 ! Copyright (C) 2007 Chris Double.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: help.syntax help.markup kernel sequences shuffle ;
+USING: help.syntax help.markup kernel sequences ;
+IN: shuffle
 
 HELP: npick
 { $values { "n" "a number" } }

extra/ui/freetype/freetype-docs.factor

@@ -1,5 +1,6 @@
-USING: help.syntax help.markup ui.freetype strings kernel
+USING: help.syntax help.markup strings kernel alien opengl
-alien opengl quotations ui.render io.styles ;
+quotations ui.render io.styles freetype ;
+IN: ui.freetype
 
 HELP: freetype
 { $values { "alien" alien } }
@@ -14,8 +15,6 @@ HELP: init-freetype
 { $description "Initializes the FreeType library." }
 { $notes "Do not call this word if you are using the UI." } ;
 
-USE: ui.freetype
-
 HELP: font
 { $class-description "A font which has been loaded by FreeType. Font instances have the following slots:"
     { $list

extra/ui/gadgets/books/books-docs.factor

@@ -1,5 +1,5 @@
-USING: ui.gadgets.books help.markup
+USING: help.markup help.syntax ui.gadgets models ;
-help.syntax ui.gadgets models ;
+IN: ui.gadgets.books
 
 HELP: book
 { $class-description "A book is a control containing one or more children. The " { $link control-value } " is the index of exactly one child to be visible at any one time, the rest being hidden by having their " { $link gadget-visible? } " slots set to " { $link f } ". The sole visible child assumes the dimensions of the book gadget."

extra/ui/gadgets/buttons/buttons-docs.factor

@@ -1,6 +1,6 @@
-USING: ui.gadgets.buttons help.markup help.syntax ui.gadgets
+USING: help.markup help.syntax ui.gadgets ui.gadgets.labels
-ui.gadgets.labels ui.gadgets.menus ui.render kernel models
+ui.render kernel models classes ;
-classes ;
+IN: ui.gadgets.buttons
 
 HELP: button
 { $class-description "A button is a " { $link gadget } " which responds to mouse clicks by invoking a quotation."
@@ -54,10 +54,6 @@ HELP: <toolbar>
 { $values { "target" object } { "toolbar" gadget } }
 { $description "Creates a row of " { $link <command-button> } " gadgets invoking commands on " { $snippet "target" } ". The commands are taken from the " { $snippet "\"toolbar\"" } " command group of each class in " { $snippet "classes" } "." } ;
 
-HELP: <commands-menu>
-{ $values { "hook" "a quotation with stack effect " { $snippet "( button -- )" } } { "target" object } { "commands" "a sequence of commands" } { "gadget" "a new " { $link gadget } } }
-{ $description "Creates a popup menu of commands which are to be invoked on " { $snippet "target" } ". The " { $snippet "hook" } " quotation is run before a command is invoked." } ;
-
 ARTICLE: "ui.gadgets.buttons" "Button gadgets"
 "Buttons respond to mouse clicks by invoking a quotation."
 { $subsection button }

extra/ui/gadgets/frames/frames-docs.factor

@@ -1,6 +1,6 @@
-USING: help.syntax ui.gadgets kernel arrays quotations tuples
+USING: help.syntax help.markup ui.gadgets kernel arrays
-ui.gadgets.grids ui.gadgets.frames ;
+quotations tuples ui.gadgets.grids ;
-IN: help.markup
+IN: ui.gadgets.frames
 
 : $ui-frame-constant ( element -- )
     drop

extra/ui/gadgets/gadgets-docs.factor

@@ -1,5 +1,6 @@
-USING: ui.gadgets help.markup help.syntax opengl kernel strings
+USING: help.markup help.syntax opengl kernel strings
 tuples classes quotations models ;
+IN: ui.gadgets
 
 HELP: rect
 { $class-description "A rectangle with the following slots:"

extra/ui/gadgets/grid-lines/grid-lines-docs.factor

@@ -1,5 +1,6 @@
-USING: ui.gadgets help.markup help.syntax ui.gadgets.grid-lines
+USING: ui.gadgets help.markup help.syntax ui.gadgets.grids
-ui.gadgets.grids ui.render ;
+ui.render ;
+IN: ui.gadgets.grid-lines
 
 HELP: grid-lines
 { $class-description "A class implementing the " { $link draw-boundary } " generic word to draw lines between the cells of a " { $link grid } ". The color of the lines is a color specifier stored in the " { $link grid-lines-color } " slot." } ;

extra/ui/gadgets/grids/grids-docs.factor

@@ -1,5 +1,5 @@
-USING: ui.gadgets help.markup help.syntax arrays
+USING: ui.gadgets help.markup help.syntax arrays ;
-ui.gadgets.grids ;
+IN: ui.gadgets.grids
 
 HELP: grid
 { $class-description "A grid gadget lays out its children so that all gadgets in a column have equal width and all gadgets in a row have equal height."

extra/ui/gadgets/incremental/incremental-docs.factor

@@ -1,5 +1,5 @@
-USING: ui.gadgets help.markup help.syntax
+USING: ui.gadgets help.markup help.syntax ui.gadgets.packs ;
-ui.gadgets.incremental ui.gadgets.packs ;
+IN: ui.gadgets.incremental
 
 HELP: incremental
 { $class-description "An incremental layout gadget delegates to a " { $link pack } " and implements an optimization which the relayout operation after adding a child to be done in constant time."

extra/ui/gadgets/menus/menus-docs.factor

@@ -1,5 +1,10 @@
-USING: ui.gadgets help.markup help.syntax ui.gadgets.menus
+USING: ui.gadgets help.markup help.syntax ui.gadgets.worlds
-ui.gadgets.worlds ;
+kernel ;
+IN: ui.gadgets.menus
+
+HELP: <commands-menu>
+{ $values { "hook" "a quotation with stack effect " { $snippet "( button -- )" } } { "target" object } { "commands" "a sequence of commands" } { "gadget" "a new " { $link gadget } } }
+{ $description "Creates a popup menu of commands which are to be invoked on " { $snippet "target" } ". The " { $snippet "hook" } " quotation is run before a command is invoked." } ;
 
 HELP: show-menu
 { $values { "gadget" gadget } { "owner" gadget } }

extra/ui/gadgets/packs/packs-docs.factor

@@ -1,5 +1,6 @@
-USING: ui.gadgets ui.gadgets.packs help.markup help.syntax
+USING: ui.gadgets help.markup help.syntax generic kernel tuples
-generic kernel tuples quotations ;
+quotations ;
+IN: ui.gadgets.packs
 
 HELP: pack
 { $class-description "A gadget which lays out its children along a single axis stored in the " { $link gadget-orientation } " slot. Can be constructed with one of the following words:"

extra/ui/gadgets/presentations/presentations-docs.factor

@@ -1,6 +1,6 @@
-USING: help.markup help.syntax
+USING: help.markup help.syntax ui.gadgets.buttons
-ui.gadgets.buttons ui.gadgets.menus models ui.operations
+ui.gadgets.menus models ui.operations inspector kernel
-inspector kernel ui.gadgets.worlds ui.gadgets ;
+ui.gadgets.worlds ui.gadgets ;
 IN: ui.gadgets.presentations
 
 HELP: presentation

extra/ui/gadgets/scrollers/scrollers-docs.factor

@@ -1,5 +1,5 @@
-USING: ui.gadgets help.markup help.syntax
+USING: ui.gadgets help.markup help.syntax ui.gadgets.viewports
-ui.gadgets.viewports ui.gadgets.sliders ;
+ui.gadgets.sliders ;
 IN: ui.gadgets.scrollers
 
 HELP: scroller

extra/ui/gadgets/status-bar/status-bar-docs.factor

@@ -1,5 +1,6 @@
-USING: ui.gadgets.status-bar ui.gadgets.presentations
+USING: ui.gadgets.presentations help.markup help.syntax models
-help.markup help.syntax models ui.gadgets ui.gadgets.worlds ;
+ui.gadgets ui.gadgets.worlds ;
+IN: ui.gadgets.status-bar
 
 HELP: <status-bar>
 { $values { "model" model } { "gadget" "a new " { $link gadget } } }

extra/ui/gadgets/tracks/tracks-docs.factor

@@ -1,5 +1,6 @@
-USING: ui.gadgets.tracks ui.gadgets.packs help.markup
+USING: ui.gadgets.packs help.markup help.syntax ui.gadgets
-help.syntax ui.gadgets arrays kernel quotations tuples ;
+arrays kernel quotations tuples ;
+IN: ui.gadgets.tracks
 
 HELP: track
 { $class-description "A track is like a " { $link pack } " except each child is resized to a fixed multiple of the track's dimension in the direction of " { $link gadget-orientation } ". Tracks are created by calling " { $link <track> } "." } ;

extra/ui/gadgets/viewports/viewports-docs.factor

@@ -1,5 +1,5 @@
-USING: ui.gadgets.viewports help.markup
+USING: help.markup help.syntax ui.gadgets models ;
-help.syntax ui.gadgets models ;
+IN: ui.gadgets.viewports
 
 HELP: viewport
 { $class-description "A viewport is a control which positions a child gadget translated by the " { $link control-value } " vector. Viewports can be created directly by calling " { $link <viewport> } "." } ;

extra/ui/gadgets/worlds/worlds-docs.factor

@@ -1,6 +1,6 @@
-USING: ui.gadgets.worlds ui.gadgets ui.render ui.gestures
+USING: ui.gadgets ui.render ui.gestures ui.backend help.markup
-ui.backend help.markup help.syntax models ui.freetype opengl
+help.syntax models opengl strings ;
-strings ui.gadgets.worlds ;
+IN: ui.gadgets.worlds
 
 HELP: origin
 { $var-description "Within the dynamic extent of " { $link draw-world } ", holds the co-ordinate system origin for the gadget currently being drawn." } ;
@@ -40,7 +40,7 @@ HELP: world
         { { $link world-status } " - a " { $link model } " holding a string to be displayed in the world's status bar." }
         { { $link world-focus } " - the current owner of the keyboard focus in the world." }
         { { $link world-focused? } " - a boolean indicating if the native window containing the world has keyboard focus." }
-        { { $link world-fonts } " - a hashtable mapping " { $link font } " instances to vectors of " { $link sprite } " instances." }
+        { { $link world-fonts } " - a hashtable mapping font instances to vectors of " { $link sprite } " instances." }
         { { $link world-handle } " - a backend-specific native handle representing the native window containing the world, or " { $link f } " if the world is not grafted." }
         { { $link world-loc } " - the on-screen location of the native window containing the world. The co-ordinate system here is backend-specific." }
     }

extra/ui/tools/debugger/debugger-docs.factor

@@ -1,5 +1,6 @@
-USING: ui.tools.debugger ui.gadgets help.markup help.syntax
+USING: ui.gadgets help.markup help.syntax kernel quotations
-kernel quotations continuations debugger ui ;
+continuations debugger ui ;
+IN: ui.tools.debugger
 
 HELP: <debugger>
 { $values { "error" "an error" } { "restarts" "a sequence of " { $link restart } " instances" } { "restart-hook" "a quotation with stack effect " { $snippet "( list -- )" } } { "gadget" "a new " { $link gadget } } }

extra/ui/tools/deploy/deploy-docs.factor

@@ -1,4 +1,5 @@
-USING: help.markup help.syntax ui.tools.deploy ;
+USING: help.markup help.syntax ;
+IN: ui.tools.deploy
 
 HELP: deploy-tool
 { $values { "vocab" "a vocabulary specifier" } }

extra/ui/tools/interactor/interactor-docs.factor

@@ -1,5 +1,6 @@
-USING: ui.tools.interactor ui.gadgets ui.gadgets.editors
+USING: ui.gadgets ui.gadgets.editors listener io help.syntax
-listener io help.syntax help.markup ;
+help.markup ;
+IN: ui.tools.interactor
 
 HELP: interactor
 { $class-description "An interactor is an " { $link editor } " intended to be used as the input component of a " { $link "ui-listener" } "."