More documentation updates

library/help/crossref.factor

@@ -19,7 +19,7 @@ M: array elements*
 
 : elements ( elt-type element -- seq ) [ elements* ] { } make ;
 
-: collect-elements ( element seq -- )
+: collect-elements ( element seq -- elements )
     [
         [
             swap elements [
@@ -40,6 +40,8 @@ SYMBOL: link-graph
 
 SYMBOL: parent-graph
 
+DEFER: $subsection
+
 : children ( article -- seq )
     article-content { $subsection } collect-elements ;
 
@@ -55,6 +57,15 @@ SYMBOL: parent-graph
 : where ( article -- seq )
     [ (where) ] { } make 1 swap tail ;
 
+: $where ( article -- )
+    where dup empty? [
+        drop
+    ] [
+        where-style [
+            [ "Parent topics: " write $links ] ($block)
+        ] with-style
+    ] if ;
+
 : xref-article ( article -- )
     dup
     [ links-out ] link-graph get add-vertex

library/help/crossref.facts

@@ -8,35 +8,54 @@ 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 -- )"
+HELP: collect-elements "( element seq -- )"
-{ $values { "elt-type" "a word" } { "element" "a markup element" } { "seq" "a new sequence" } }
+{ $values { "element" "a markup element" } { "seq" "a sequence of words" } { "elements" "a new sequence" } }
-{ $description "Sets a variable for each child element of every element of type " { $snippet "elt-type" } " found by traversing " { $snippet "element" } "." }
+{ $description "Collects the arguments of all sub-elements of " { $snippet "element" } " whose markup element type occurs in " { $snippet "seq" } "." }
-{ $notes "This word is used in the implementation of " { $link links-out } "." } ;
+{ $notes "Used to implement " { $link links-out } " and " { $link children } "." } ;
+
+HELP: link-graph f
+{ $description "Variable. A graph whose vertices are help articles and edges are links. See " { $link "graphs" } "." }
+{ $see-also links-out links-in xref-articles } ;
 
 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: parent-graph f
+{ $description "Variable. A graph whose vertices are help articles and edges are subsections. See " { $link "graphs" } "." }
+{ $see-also children parents xref-articles } ;
+
+HELP: children "( topic -- seq )"
+{ $values { "topic" "an article name or a word" } { "seq" "a new sequence" } }
+{ $description "Outputs a sequence of all subsections of " { $snippet "topic" } "." } ;
+
+HELP: parents "( topic -- seq )"
+{ $values { "topic" "an article name or a word" } { "seq" "a new sequence" } }
+{ $description "Outputs a sequence of all help articles which contain " { $snippet "topic" } " as a subsection." } ;
+
+HELP: where "( topic -- seq )"
+{ $values { "topic" "an article name or a word" } { "seq" "a new sequence" } }
+{ $description "Outputs a sequence of all help articles which contain " { $snippet "topic" } " as a subsection, traversing all the way up to the root." }
+{ $examples
+    { $example "\"sequences\" where ." "{ \"collections\" \"handbook\" }" }
+} ;
+
 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." }
+{ $description "Adds an article to the " { $link link-graph } " and " { $link parent-graph } " graphs." }
 $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." }
+{ $description "Removes an article to the " { $link link-graph } " and " { $link parent-graph } " graphs." }
 $low-level-note ;
 
 HELP: xref-articles "( -- )"
-{ $description "Update the " { $link help-graph } " graph of article links. Usually this is done automatically." } ;
+{ $description "Update the " { $link link-graph } " and " { $link parent-graph } " graphs. Usually this is done automatically." } ;
 
 HELP: links-in. "( topic -- )"
 { $values { "topic" "an article name or a word" } }

library/help/help.factor

@@ -8,7 +8,7 @@ M: word article-title
 
 M: word article-content
     [
-        \ $synopsis over 2array ,
+        \ $vocabulary over 2array ,
         dup "help" word-prop [
             %
         ] [

library/help/markup.factor

@@ -111,15 +111,6 @@ M: link summary "Link: " swap link-name append ;
 : $links ( content -- )
     [ 1array $link ] textual-list ;
 
-: $where ( article -- )
-    where dup empty? [
-        drop
-    ] [
-        where-style [
-            [ "Parent topics: " write $links ] ($block)
-        ] with-style
-    ] if ;
-
 : $see-also ( content -- )
     "See also" $heading $links ;
 

library/help/search.factor

@@ -17,17 +17,11 @@ porter-stemmer prettyprint sequences strings ;
         dup ignored-word? over length 1 = or swap empty? or not
     ] subset ;
 
-: index-text ( score article string -- )
+: index-text ( article string -- )
-    tokenize [ >r 2dup r> nest hash+ ] each 2drop ;
+    tokenize [ 1 -rot nest hash+ ] each-with ;
-
-: index-article-title ( article -- )
-    3 swap dup article-title index-text ;
-
-: index-article-content ( article -- )
-    1 swap dup [ help ] string-out index-text ;
 
 : index-article ( article -- )
-    dup index-article-title index-article-content ;
+    dup [ help ] string-out index-text ;
 
 SYMBOL: term-index
 

library/help/search.facts

@@ -8,22 +8,14 @@ HELP: tokenize "( string -- seq )"
 { $values { "string" "a string" } { "seq" "a sequence of strings" } }
 { $description "Split a string along whitespace boundaries, convert all tokens to lower case, and stem all tokens." } ;
 
-HELP: index-text "( score topic string -- )"
+HELP: index-text "( topic string -- )"
-{ $values { "score" "a relevance score" } { "topic" "a help article name or a word" } { "string" "a string" } }
+{ $values { "topic" "a help article name or a word" } { "string" "a string" } }
-{ $description "Tokenizes the string and adds each token to the term index, with the specified score placed on the topic." }
+{ $description "Tokenizes the string and adds each token to the term index." }
 { $notes "This word operates on the current namespace, and so must be wrapped in a " { $link bind } " to specify the term index hashtable." } ;
 
-HELP: index-article-title "( topic -- )"
-{ $values { "topic" "a help article name or a word" } }
-{ $description "Adds the tokens making up the article's title to the term index with a high relevancy score." } ;
-
-HELP: index-article-content "( topic -- )"
-{ $values { "topic" "a help article name or a word" } }
-{ $description "Adds the tokens making up the article's content to the term index with a regular relevancy score." } ;
-
 HELP: index-article "( topic -- )"
 { $values { "topic" "a help article name or a word" } }
-{ $description "Adds the tokens making up the article's title and content to the term index, with the title terms having a higher relevancy score." } ;
+{ $description "Adds the tokens making up the article to the term index." } ;
 
 HELP: term-index f
 { $description "Variable. A hashtable mapping stemmed search terms to hashtables mapping help topics to relevancy scores."