diff --git a/library/help/crossref.factor b/library/help/crossref.factor index 93bd00ae56..3077107868 100644 --- a/library/help/crossref.factor +++ b/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 diff --git a/library/help/crossref.facts b/library/help/crossref.facts index 4a02d42a61..bef827090b 100644 --- a/library/help/crossref.facts +++ b/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 -- )" -{ $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: collect-elements "( element seq -- )" +{ $values { "element" "a markup element" } { "seq" "a sequence of words" } { "elements" "a new sequence" } } +{ $description "Collects the arguments of all sub-elements of " { $snippet "element" } " whose markup element type occurs in " { $snippet "seq" } "." } +{ $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" } } diff --git a/library/help/help.factor b/library/help/help.factor index 4f6a972b15..a9194d0199 100644 --- a/library/help/help.factor +++ b/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 [ % ] [ diff --git a/library/help/markup.factor b/library/help/markup.factor index 388126ec3f..b15b3f1247 100644 --- a/library/help/markup.factor +++ b/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 ; diff --git a/library/help/search.factor b/library/help/search.factor index 7e3c56d272..d4cec0e560 100644 --- a/library/help/search.factor +++ b/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 -- ) - tokenize [ >r 2dup r> nest hash+ ] each 2drop ; - -: index-article-title ( article -- ) - 3 swap dup article-title index-text ; - -: index-article-content ( article -- ) - 1 swap dup [ help ] string-out index-text ; +: index-text ( article string -- ) + tokenize [ 1 -rot nest hash+ ] each-with ; : index-article ( article -- ) - dup index-article-title index-article-content ; + dup [ help ] string-out index-text ; SYMBOL: term-index diff --git a/library/help/search.facts b/library/help/search.facts index 7d51043a9e..eeb745a318 100644 --- a/library/help/search.facts +++ b/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 -- )" -{ $values { "score" "a relevance score" } { "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." } +HELP: index-text "( topic 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." } { $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."