From 10af34de4d2844ea51a6ae7a54b26d60e817abda Mon Sep 17 00:00:00 2001
From: slava <slava@factorcode.org>
Date: Sat, 17 Jun 2006 03:12:40 +0000
Subject: [PATCH] Documentation updates

---
 TODO.FACTOR.txt                      |   6 +-
 contrib/httpd/help-responder.factor  |   4 +-
 library/bootstrap/boot-stage1.factor |   3 +
 library/generic/generic.facts        |  10 +-
 library/help/crossref.factor         |   6 +-
 library/help/crossref.facts          |  43 +++++
 library/help/help.factor             |  18 +-
 library/help/help.facts              |  51 ++++++
 library/help/markup.factor           |  40 ++---
 library/help/markup.facts            | 244 +++++++++++++++++++++++++++
 library/help/search.factor           |   2 +-
 library/help/stylesheet.factor       |  13 +-
 library/help/word-help.factor        |   5 +-
 library/io/nested-style.factor       |   3 +-
 library/kernel.facts                 |   4 +-
 library/ui/tools/browser.factor      |   2 +-
 library/ui/tools/help.factor         |   2 +-
 library/words.facts                  |  12 +-
 18 files changed, 418 insertions(+), 50 deletions(-)
 create mode 100644 library/help/crossref.facts
 create mode 100644 library/help/help.facts
 create mode 100644 library/help/markup.facts

diff --git a/TODO.FACTOR.txt b/TODO.FACTOR.txt
index 6fc35c7f3a..2a53689e6a 100644
--- a/TODO.FACTOR.txt
+++ b/TODO.FACTOR.txt
@@ -1,5 +1,6 @@
 + io:
 
+- pop all callbacks at once
 - unix i/o: problems with passing f to syscalls
 - factorcode httpd started using 99% CPU, but still received connections;
   closing read-fds solved it
@@ -8,10 +9,12 @@
 
 + help:
 
+- double 'presented' for the block & char style
 - refactor style stack code so that nested styles are handled at a lower-level
   - with-style & with-stream-style
     - in HTML, we can nest div tags, etc
-- automatically update help graph when adding/removing articles/words
+- automatically update help graph and search index when adding/removing
+  articles/words
 - help search:
   - edit distance algorithm
   - store positions in index
@@ -21,6 +24,7 @@
 
 + ui:
 
+- help viewer in ui: show title
 - x11 title bars are funny
 - cocoa: starting the UI with +foo switches opens them as files
 - if the listener is running a command when the image is saved, it
diff --git a/contrib/httpd/help-responder.factor b/contrib/httpd/help-responder.factor
index ac1772d83b..e5994163aa 100644
--- a/contrib/httpd/help-responder.factor
+++ b/contrib/httpd/help-responder.factor
@@ -8,6 +8,6 @@ USING: hashtables help html httpd io kernel namespaces sequences ;
 
 : help-responder ( -- )
     serving-html
-    help-topic dup article-title dup [
-        <h1> write </h1> [ help ] with-html-stream
+    help-topic dup article-title [
+        [ help ] with-html-stream
     ] html-document ;
diff --git a/library/bootstrap/boot-stage1.factor b/library/bootstrap/boot-stage1.factor
index 932012c861..028ee9158f 100644
--- a/library/bootstrap/boot-stage1.factor
+++ b/library/bootstrap/boot-stage1.factor
@@ -244,6 +244,9 @@ vectors words ;
         "/library/generic/slots.facts"
         "/library/generic/standard-combination.facts"
         "/library/generic/tuple.facts"
+        "/library/help/crossref.facts"
+        "/library/help/help.facts"
+        "/library/help/markup.facts"
         "/library/io/binary.facts"
         "/library/io/buffer.facts"
         "/library/io/c-streams.facts"
diff --git a/library/generic/generic.facts b/library/generic/generic.facts
index a68afed7e3..79854240ef 100644
--- a/library/generic/generic.facts
+++ b/library/generic/generic.facts
@@ -38,7 +38,7 @@ HELP: define-predicate "( class predicate quot -- )"
     }
     "These properties allow the method combination code to generate method dispatch logic."
 }
-{ $notes $low-level-note } ;
+$low-level-note ;
 
 HELP: superclass "( class -- super )"
 { $values { "class" "a class word" } { "super" "a class word" } }
@@ -88,7 +88,7 @@ HELP: generic f
 HELP: make-generic "( word -- )"
 { $values { "word" "a generic word" } }
 { $description "Regenerates the definition of a generic word by applying the method combination to the set of defined methods." }
-{ $notes $low-level-note } ;
+$low-level-note ;
 
 HELP: check-method "( class generic -- )"
 { $values { "class" "a class word" } { "generic" "a generic word" } }
@@ -97,12 +97,12 @@ HELP: check-method "( class generic -- )"
 HELP: ?make-generic "( word -- )"
 { $values { "word" "a generic word" } }
 { $description "Regenerates the definition of a generic word, unless bootstrap is in progress, in which case nothing is done. This avoids regenerating generic words multiple times during bootstrap as methods are defined. Instead, all generic words are built once at the end of the process, resulting in a performance improvement." }
-{ $notes $low-level-note } ;
+$low-level-note ;
 
 HELP: with-methods "( word quot -- )"
 { $values { "word" "a generic word" } { "quot" "a quotation with stack effect " { $snippet "( methods -- )" } } }
 { $description "Applies a quotation to the generic word's methods hashtable, and regenerates the generic word's definition when the quotation returns." }
-{ $notes $low-level-note } ;
+$low-level-note ;
 
 HELP: define-method "( quot class generic -- )"
 { $values { "quot" "a quotation" } { "class" "a class word" } { "generic" "a generic word" } }
@@ -144,7 +144,7 @@ HELP: min-class "( class seq -- class/f )"
 HELP: define-class "( class -- )"
 { $values { "class" "a class word" } }
 { $description "Sets a property indicating this is a class word, and registers the class in the global union lookup map." }
-{ $notes $low-level-note } ;
+$low-level-note ;
 
 HELP: implementors "( class -- seq )"
 { $values { "class" "a class word" } { "seq" "a sequence of generic words" } }
diff --git a/library/help/crossref.factor b/library/help/crossref.factor
index b11e99576d..8696c1df42 100644
--- a/library/help/crossref.factor
+++ b/library/help/crossref.factor
@@ -10,8 +10,6 @@ namespaces sequences strings words ;
         [ word-article ] word-subset %
     ] { } make ;
 
-: each-article ( quot -- ) all-articles swap each ; inline
-
 GENERIC: elements* ( elt-type element -- )
 
 M: simple-element elements* [ elements* ] each-with ;
@@ -25,7 +23,7 @@ M: array elements*
 : elements ( elt-type element -- seq ) [ elements* ] { } make ;
 
 : collect-elements ( elt-type article -- )
-    elements [ 1 swap tail [ dup set ] each ] each ; inline
+    elements [ 1 swap tail [ dup set ] each ] each ;
 
 : links-out ( article -- seq )
     article-content [
@@ -36,7 +34,7 @@ M: array elements*
 
 SYMBOL: help-graph
 
-: links-in ( article -- )
+: links-in ( article -- seq )
     dup link? [ link-name ] when help-graph get in-edges ;
 
 : xref-article ( article -- )
diff --git a/library/help/crossref.facts b/library/help/crossref.facts
new file mode 100644
index 0000000000..4a02d42a61
--- /dev/null
+++ b/library/help/crossref.facts
@@ -0,0 +1,43 @@
+IN: help
+
+HELP: all-articles "( -- seq )"
+{ $values { "seq" "a sequence" } }
+{ $description "Outputs a sequence of all help article names, and all words with documentation." } ;
+
+HELP: elements "( elt-type element -- seq )"
+{ $values { "elt-type" "a word" } { "element" "a markup element" } { "seq" "a new sequence" } }
+{ $description "Outputs a sequence of all elements of type " { $snippet "elt-type" } " found by traversing " { $snippet "element" } "." } ;
+
+HELP: collect-elements "( elt-type element -- )"
+{ $values { "elt-type" "a word" } { "element" "a markup element" } { "seq" "a new sequence" } }
+{ $description "Sets a variable for each child element of every element of type " { $snippet "elt-type" } " found by traversing " { $snippet "element" } "." }
+{ $notes "This word is used in the implementation of " { $link links-out } "." } ;
+
+HELP: links-out "( topic -- seq )"
+{ $values { "topic" "an article name or a word" } { "seq" "a new sequence" } }
+{ $description "Outputs a sequence of all help articles and words linked to from " { $snippet "article" } "." } ;
+
+HELP: help-graph f
+{ $description "Variable. A graph whose vertices are help articles and edges are links. See " { $link "graphs" } "." }
+{ $see-also links-in xref-articles } ;
+
+HELP: links-in "( topic -- seq )"
+{ $values { "topic" "an article name or a word" } { "seq" "a new sequence" } }
+{ $description "Outputs a sequence of all help articles and words which link to " { $snippet "article" } "." } ;
+
+HELP: xref-article "( topic -- )"
+{ $values { "topic" "an article name or a word" } }
+{ $description "Adds a vertex representing this article, along with edges representing links to the " { $link help-graph } " graph." }
+$low-level-note ;
+
+HELP: unxref-article "( topic -- )"
+{ $values { "topic" "an article name or a word" } }
+{ $description "Remove the vertex representing the article from the " { $link help-graph } " graph." }
+$low-level-note ;
+
+HELP: xref-articles "( -- )"
+{ $description "Update the " { $link help-graph } " graph of article links. Usually this is done automatically." } ;
+
+HELP: links-in. "( topic -- )"
+{ $values { "topic" "an article name or a word" } }
+{ $description "Prints an outliner listing all help articles linking to " { $snippet "article" } "." } ;
diff --git a/library/help/help.factor b/library/help/help.factor
index a11d07949c..d37c2dc1ed 100644
--- a/library/help/help.factor
+++ b/library/help/help.factor
@@ -7,6 +7,8 @@ strings ;
 ! Markup
 GENERIC: print-element
 
+DEFER: $title
+
 ! Help articles
 SYMBOL: articles
 
@@ -28,9 +30,19 @@ M: f article-content drop \ f article-content ;
 
 SYMBOL: last-block
 
-: (help) ( element -- )
-    default-style [ last-block on print-element ] with-nesting ;
+: print-title ( article -- )
+    article-title $title ;
 
-: help ( topic -- ) article-content (help) terpri ;
+: with-default-style ( quot -- )
+    default-char-style [
+        default-para-style [ last-block on call ] with-nesting
+    ] with-style ; inline
+
+: print-content ( element -- )
+    [ print-element ] with-default-style ;
+
+: (help) ( topic -- ) article-content print-content terpri ;
+
+: help ( topic -- ) dup print-title (help) ;
 
 : handbook ( -- ) "handbook" help ;
diff --git a/library/help/help.facts b/library/help/help.facts
new file mode 100644
index 0000000000..e5247e60c7
--- /dev/null
+++ b/library/help/help.facts
@@ -0,0 +1,51 @@
+IN: help
+USING: io ;
+
+HELP: print-element "( element -- )"
+{ $values { "element" "a markup element" } }
+{ $description "Prints a markup element to the " { $link stdio } " stream." } ;
+
+HELP: articles f
+{ $description "Variable. Hashtable mapping article names to " { $link article } " instances." } ;
+
+HELP: article "( name -- article )"
+{ $values { "name" "an article name" } { "article" "an " { $link article } " object" } }
+{ $description "Outputs a named " { $link article } " object." } ;
+
+HELP: article-title "( topic -- string )"
+{ $values { "topic" "an article name or a word" } { "string" "a string" } }
+{ $description "Outputs the title of a specific help article." } ;
+
+HELP: article-content "( topic -- element )"
+{ $values { "topic" "an article name or a word" } { "element" "a markup element" } }
+{ $description "Outputs the content of a specific help article." } ;
+
+HELP: add-article "( name title element -- )"
+{ $values { "name" "a string" } { "title" "a string" } { "element" "a markup element" } }
+{ $description "Adds a help article to the " { $link articles } " hashtable." }
+{ $notes "This word is used to implement " { $link POSTPONE: ARTICLE: } "." } ;
+
+HELP: last-block f
+{ $description "Variable. Set by " { $link print-element } " if the last element output was a block element, thus if the next element is a block element no newline needs to be output." } ;
+
+HELP: print-content "( element -- )"
+{ $values { "element" "a markup element" } }
+{ $description "Prints a top-level markup element to the " { $link stdio } " stream." } ;
+
+HELP: (help) "( topic -- )"
+{ $values { "topic" "an article name or a word" } }
+{ $description
+    "Displays a help article or documentation associated to a word on the " { $link stdio } " stream. This word does not print the article title, so it is intended for use by outliners and in other contexts where the title is already visible to the user."
+}
+{ $see-also help } ;
+
+HELP: help "( topic -- )"
+{ $values { "topic" "an article name or a word" } }
+{ $description
+    "Displays a help article or documentation associated to a word on the " { $link stdio } " stream."
+}
+{ $see-also (help) } ;
+
+HELP: handbook "( -- )"
+{ $description "Displays the Factor developer's handbook." }
+{ $see-also help } ;
diff --git a/library/help/markup.factor b/library/help/markup.factor
index 979ae87c1d..565f967686 100644
--- a/library/help/markup.factor
+++ b/library/help/markup.factor
@@ -34,8 +34,6 @@ M: word print-element { } swap execute ;
 
 ! Some spans
 
-: $heading [ heading-style ($span) ] ($block) ;
-
 : $snippet snippet-style ($span) ;
 
 : $emphasis emphasis-style ($span) ;
@@ -45,6 +43,9 @@ M: word print-element { } swap execute ;
 : $terpri last-block off terpri terpri drop ;
 
 ! Some blocks
+: $title [ title-style ($span) ] ($block) ;
+
+: $heading [ heading-style ($span) ] ($block) ;
 
 : ($code) ( presentation quot -- )
     [
@@ -87,6 +88,15 @@ M: word print-element { } swap execute ;
 : $examples ( content -- )
     "Examples" $heading print-element ;
 
+: $example ( content -- )
+    1 swap cut* swap "\n" join dup <input> [
+        input-style format terpri print-element
+    ] ($code) ;
+
+: $markup-example ( content -- )
+    first dup unparse " print-element" append 1array $code
+    print-element ;
+
 : $warning ( content -- )
     [
         warning-style [
@@ -94,14 +104,6 @@ M: word print-element { } swap execute ;
         ] with-nesting
     ] ($block) ;
 
-: textual-list ( seq quot -- )
-    [ ", " print-element ] interleave ; inline
-
-: $example ( content -- )
-    1 swap cut* swap "\n" join dup <input> [
-        input-style format terpri print-element
-    ] ($code) ;
-
 ! Some links
 TUPLE: link name ;
 
@@ -118,14 +120,12 @@ M: link summary
     ] with-style ;
 
 : $subsection ( object -- )
-    [
-        first [ help ] swap ($subsection)
-    ] ($block) ;
+    [ first [ (help) ] swap ($subsection) ] ($block) ;
 
 : $subtopic ( object -- )
     [
         subtopic-style [
-            unclip f rot [ (help) ] curry write-outliner
+            unclip f rot [ print-content ] curry write-outliner
         ] with-style
     ] ($block) ;
 
@@ -133,6 +133,9 @@ M: link summary
     last-block off first link-style
     [ dup article-title swap <link> write-object ] with-style ;
 
+: textual-list ( seq quot -- )
+    [ ", " print-element ] interleave ; inline
+
 : $links ( content -- )
     [ 1array $link ] textual-list ;
 
@@ -146,8 +149,7 @@ M: link summary
 
 : $values ( content -- )
     "Arguments and values" $heading
-    [ first2 >r \ $snippet swap 2array r> 2array ] map
-    $table ;
+    [ unclip \ $snippet swap 2array swap 2array ] map $table ;
 
 : $predicate ( content -- )
     { { "object" "an object" } } $values
@@ -170,7 +172,7 @@ M: link summary
     "Notes" $heading print-element ;
 
 : $see ( content -- )
-    code-style [ first see ] with-nesting ;
+    code-style [ dup array? [ first ] when see ] with-nesting ;
 
 : $definition ( content -- )
     "Definition" $heading $see ;
@@ -188,7 +190,7 @@ M: link summary
 
 : $low-level-note
     drop
-    "Calling this word directly is not necessary in most cases. Higher-level words call it automatically." print-element ;
+    "Calling this word directly is not necessary in most cases. Higher-level words call it automatically." $notes ;
 
 : $values-x/y
     drop
@@ -207,4 +209,4 @@ M: link summary
     swap sort-articles [ ($subsection) terpri ] each-with ;
 
 : $outliner ( content -- )
-    first call [ help ] help-outliner ;
+    first call [ (help) ] help-outliner ;
diff --git a/library/help/markup.facts b/library/help/markup.facts
new file mode 100644
index 0000000000..084a924403
--- /dev/null
+++ b/library/help/markup.facts
@@ -0,0 +1,244 @@
+IN: help
+USING: arrays inspector io math prettyprint sequences ;
+
+HELP: simple-element f
+{ $description "Class of simple elements, which are just arrays of elements." } ;
+
+HELP: ($span) "( content style -- )"
+{ $values { "content" "a markup element" } { "style" "a hashtable" } }
+{ $description "Prints an inline markup element." } ;
+
+HELP: ?terpri "( -- )"
+{ $description "Prints a newline if the last element which was output is not a block." } ;
+
+HELP: ($block) "( quot -- )"
+{ $values { "quot" "a quotation" } }
+{ $description "Prints a block markup element with newlines before and after." } ;
+
+HELP: $title "( element -- )"
+{ $values { "element" "a markup element" } }
+{ $description "Prints a markup element, usually a string, as a block with the " { $link title-style } "." }
+{ $examples
+    { $markup-example { $title "Fermat's Last Theorem" } }
+} ;
+
+HELP: $heading "( element -- )"
+{ $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: $code "( element -- )"
+{ $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."
+    $terpri
+    "If you want to show code along with sample output, use the " { $link $example } " element."
+}
+{ $examples
+    { $markup-example { $code "2 2 + ." } }
+} ;
+
+HELP: $syntax "( word -- )"
+{ $values { "word" "a word" } }
+{ $description "Prints a description of a parsing word's syntax. This element is automatically output by the help system, so help descriptions of parsing words should not call it." } ;
+
+HELP: $stack-effect "( word -- )"
+{ $values { "word" "a word" } }
+{ $description "Prints a description of a word's stack effect. This element is automatically output by the help system, so help descriptions of parsing words should not call it." } ;
+
+HELP: $vocabulary "( element -- )"
+{ $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: $synopsis "( element -- )"
+{ $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
+{ $description "Prints a the header material found on every word help page -- the word's vocabulary, stack effect and syntax, printing the latter only for parsing words. This markup element is automatically output by the help system, so help descriptions of parsing words should not call it." } ;
+
+HELP: $description "( element -- )"
+{ $values { "element" "a markup element" } }
+{ $description "Prints the description subheading found on the help page of most words." } ;
+
+HELP: $contract "( element -- )"
+{ $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 "( element -- )"
+{ $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 "( element -- )"
+{ $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 { $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 "( element -- )"
+{ $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 "( element -- )"
+{ $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: $subsection "( element -- )"
+{ $values { "element" "a markup element of the form " { $snippet "{ topic }" } } }
+{ $description "Prints an expandable outliner containing the body of the help topic named by the first string element of " { $snippet "element" } "." }
+{ $examples
+    { $markup-example { $subsection "sequences" } }
+} ;
+
+HELP: $subtopic "( element -- )"
+{ $values { "element" "a markup element of the form " { $snippet "{ title content }" } } }
+{ $description "Prints an expandable outliner with the given title containing an arbitrary markup element." }
+{ $examples
+    { $markup-example { $subtopic "Subtopic example"
+    "Subtopics are useful for short notes, sidebars "
+    "and other bits of info which don't really deserve "
+    "their own help article." } }
+} ;
+
+HELP: $link "( element -- )"
+{ $values { "element" "a markup element of the form " { $snippet "{ topic }" } } }
+{ $description "Prints a link to a help article or word." }
+{ $examples
+    { $markup-example { $link "queues" } }
+    { $markup-example { $link + } }
+} ;
+
+HELP: textual-list "( seq -- str )"
+{ $values { "seq" "a sequence of strings" } { "str" "a string" } }
+{ $description "Concatenates a sequence of strings together, separated by " { $snippet "\", \"" } "." }
+{ $examples
+    { $example "{ \"fish\" \"chips\" \"salt\" } textual-list print" "fish, chips, salt" }
+} ;
+
+HELP: $links "( topics -- )"
+{ $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 "( topics -- )"
+{ $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" "queues" } }
+} ;
+
+HELP: $table "( element -- )"
+{ $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 "( element -- )"
+{ $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: $predicate "( element -- )"
+{ $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: $list "( element -- )"
+{ $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 "( element -- )"
+{ $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 "( element -- )"
+{ $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 "( element -- )"
+{ $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 "( element -- )"
+{ $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 "( word -- )"
+{ $values { "word" "a word" } } }
+{ $description "Prints a heading followed by the definition of " { $snippet "word" } " by calling " { $link see } "." }
+{ $notes
+    "This markup element is output by " { $link show } " but not " { $link help } "."
+} ;
+
+HELP: $curious "( element -- )"
+{ $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 "( element -- )"
+{ $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: sort-articles "( seq -- assoc )"
+{ $values { "seq" "a sequence of help article names and words" } { "assoc" "a new sequence of pairs" } }
+{ $description "Constructs a key-sorted association list mapping article titles to help topics." } ;
+
+HELP: help-outliner "( seq quot -- )"
+{ $values { "seq" "a sequence of help article names and words" } { "quot" "a quotation with stack effect " { $snippet "( topic -- )" } } }
+{ $description "Writes an outliner of help topics to the " { $link stdio } " stream. Expanding a help topic calls " { $snippet "quot" } " with the topic on the data stack." } ;
+
+HELP: $outliner "( element -- )"
+{ $values { "element" "a markup element of the form " { $snippet "( quot -- )" } } }
+{ $description "Calls the quotation to generate a sequence of help topics, and outputs an outliner for each one. Expanding a help topic shows the article body." } ;
diff --git a/library/help/search.factor b/library/help/search.factor
index 8b9dba22c6..3e00404341 100644
--- a/library/help/search.factor
+++ b/library/help/search.factor
@@ -21,7 +21,7 @@ porter-stemmer prettyprint sequences strings ;
     tokenize [ >r 2dup r> nest hash+ ] each 2drop ;
 
 : index-article-title ( article -- )
-    10 swap dup article-title index-text ;
+    3 swap dup article-title index-text ;
 
 : index-article-content ( article -- )
     1 swap dup [ help ] string-out index-text ;
diff --git a/library/help/stylesheet.factor b/library/help/stylesheet.factor
index 2cf77bdabf..2a0fd69d02 100644
--- a/library/help/stylesheet.factor
+++ b/library/help/stylesheet.factor
@@ -3,10 +3,14 @@
 IN: help
 USING: styles ;
 
-: default-style
+: default-char-style
     H{
         { font "sans-serif" }
         { font-size 12 }
+    } ;
+
+: default-para-style
+    H{
         { wrap-margin 500 }
     } ;
 
@@ -16,6 +20,13 @@ USING: styles ;
 : emphasis-style
     H{ { font-style italic } } ;
 
+: title-style
+    H{
+        { font "sans-serif" }
+        { font-size 16 }
+        { font-style bold }
+    } ;
+
 : heading-style
     H{
         { font "sans-serif" }
diff --git a/library/help/word-help.factor b/library/help/word-help.factor
index 38a1c704c5..0f34e57b7c 100644
--- a/library/help/word-help.factor
+++ b/library/help/word-help.factor
@@ -1,7 +1,7 @@
 ! Copyright (C) 2005, 2006 Slava Pestov.
 ! See http://factorcode.org/license.txt for BSD license.
 IN: help
-USING: arrays kernel namespaces prettyprint sequences words ;
+USING: arrays io kernel namespaces prettyprint sequences words ;
 
 M: word article-title
     dup word-name swap stack-effect [ " " swap append3 ] when* ;
@@ -20,5 +20,4 @@ M: word article-content
         ] ?if
     ] { } make ;
 
-: word-help ( word -- )
-    dup article-content { $definition } rot add add (help) ;
+: show ( word -- ) dup help $definition terpri ;
diff --git a/library/io/nested-style.factor b/library/io/nested-style.factor
index b54608ea52..f53486e90a 100644
--- a/library/io/nested-style.factor
+++ b/library/io/nested-style.factor
@@ -9,7 +9,8 @@ TUPLE: nested-style-stream style ;
     >r stdio get <nested-style-stream> r> with-stream* ; inline
 
 : do-nested-style ( style stream -- style delegate )
-    [ nested-style-stream-style hash-union ] keep delegate ;
+    [ nested-style-stream-style swap hash-union ] keep
+    delegate ;
 
 : collapse-nested-style ( style delegate -- style delegate )
     dup nested-style-stream? [ do-nested-style ] when ;
diff --git a/library/kernel.facts b/library/kernel.facts
index 8fcd246b85..4f4e78150d 100644
--- a/library/kernel.facts
+++ b/library/kernel.facts
@@ -68,7 +68,7 @@ HELP: hashcode "( obj -- n )"
 "If mutable objects are used as hashtable keys, they must not be mutated in such a way that their hashcode changes. Doing so will violate bucket sorting invariants and result in undefined behavior." } ;
 
 HELP: = "( obj1 obj2 -- ? )"
-{ $values { "obj1" "an object" } { "obj2" "an object" } }
+{ $values { "obj1" "an object" } { "obj2" "an object" } { "?" "a boolean" } }
 { $contract
     "Tests if two objects are equal. If two objects are equal, they should the same printed representation, although the converse is not always true."
     $terpri
@@ -80,7 +80,7 @@ HELP: = "( obj1 obj2 -- ? )"
     }
     "The precise contract is as follows:"
     { $list
-        { "if no more specific method is defined, " { $link = } "  calls " { $link eq? } }
+        { "if no more specific method is defined, " { $link = } " calls " { $link eq? } }
         { "two numbers are equal if they have the same numerical value after being upgraded to the highest type of the two (see " { $link "number-protocol" } ")" }
         "two sequences are equal if they have the same type and elements"
         "two tuples are equal if their classes and slot values are equal"
diff --git a/library/ui/tools/browser.factor b/library/ui/tools/browser.factor
index 52e7f95a88..e5703fc355 100644
--- a/library/ui/tools/browser.factor
+++ b/library/ui/tools/browser.factor
@@ -52,7 +52,7 @@ DEFER: show-vocab
 : <word-pages> ( word -- tabs )
     {
         { "Definition" [ see ] }
-        { "Documentation" [ help ] }
+        { "Documentation" [ (help) ] }
         { "Calls in" [ usage. ] }
         { "Links in" [ links-in. ] }
         { "Properties" [ word-props describe ] }
diff --git a/library/ui/tools/help.factor b/library/ui/tools/help.factor
index 1e071f957d..600659921b 100644
--- a/library/ui/tools/help.factor
+++ b/library/ui/tools/help.factor
@@ -50,7 +50,7 @@ M: help-gadget focusable-child*
     [ over history-seq push-new update-history ] [ 2drop ] if ;
 
 : fancy-help ( obj -- )
-    link-name dup word? [ word-help ] [ help ] if ;
+    link-name dup word? [ show ] [ help ] if ;
 
 : show-help ( link help -- )
     dup add-history [ set-help-gadget-showing ] 2keep
diff --git a/library/words.facts b/library/words.facts
index 59dd8f1c05..84908c6d47 100644
--- a/library/words.facts
+++ b/library/words.facts
@@ -82,12 +82,12 @@ HELP: uses "( word -- seq )"
 { $see-also uses } ;
 
 HELP: crossref f
-{ $description "Variable. A hashtable mapping words to usages, where usages are a set represented by a hashtable with words as keys and dummy sentinels as values." }
+{ $description "Variable. A graph whose vertices are words and edges are usages. See " { $link "graphs" } "." }
 { $see-also usages xref-words } ;
 
 HELP: xref-word "( word -- )"
 { $values { "word" "a word" } }
-{ $description "Adds dependencies from every word called by this word to this word." }
+{ $description "Adds a vertex representing this word, along with edges representing dependencies to the " { $link crossref } " graph." }
 $low-level-note ;
 
 HELP: usage "( word -- seq )"
@@ -106,9 +106,9 @@ HELP: unxref-word* "( word -- )"
 { $contract "Updates the word to cope with a callee being redefined." }
 $low-level-note ;
 
-HELP: unxref-word "( callee caller -- )"
-{ $values { "callee" "a word" } { "caller" "a word" } }
-{ $description "Remove the fact that " { $snippet "caller" } " calls " { $snippet "callee" } " from the cross-referencing database." }
+HELP: unxref-word "( word -- )"
+{ $values { "word" "a word" } }
+{ $description "Remove the vertex representing the word from the " { $link crossref } " graph." }
 $low-level-note ;
 
 HELP: define "( word def primitive -- )"
@@ -217,7 +217,7 @@ HELP: word-subset "( quot -- seq )"
 { $description "Outputs a sequence of words satisfying the predicate." } ;
 
 HELP: xref-words "( -- )"
-{ $description "Update the word dependency database. Usually this is done automatically." } ;
+{ $description "Update the " { $link crossref } " graph of word dependencies. Usually this is done automatically." } ;
 
 HELP: lookup "( name vocab -- word )"
 { $values { "name" "a string" } { "vocab" "a string" } { "word" "a word or " { $link f } } }