factor/library/help/topics.facts

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: no-article "( name -- )"
{ $values { "name" "an article name" } }
{ $description "Throws a " { $link no-article } " error." }
{ $error-description "Thrown by " { $link help } " if the given help topic does not exist, or if the help topic being dispayed links to a help topic which does not exist." } ;

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" "an object" } { "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: 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 "( 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 children } "." } ;

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-help } ;

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 an article to the " { $link parent-graph } " graph." }
$low-level-note ;

HELP: unxref-article "( topic -- )"
{ $values { "topic" "an article name or a word" } }
{ $description "Removes an article to the " { $link parent-graph } " graph." }
$low-level-note ;

HELP: xref-help "( -- )"
{ $description "Update the " { $link parent-graph } ". Usually this is done automatically." } ;