core/handbook/help.facts

   1 USING: help ;
   2
   3 ARTICLE: "help" "The help system"
   4 "The help system maintains documentation written in a simple markup language, along with cross-referencing and search. Documentation can either exist as free-standing " { $emphasis "articles" } " or be associated with words."
   5 { $subsection "browsing-help" }
   6 { $subsection "writing-help" } ;
   7
   8 ARTICLE: "browsing-help" "Browsing documentation"
   9 "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."
  10 { $subsection handbook }
  11 "Help topics are identified by article name strings, or words. You can request a specific help topic:"
  12 { $subsection help } ;
  13
  14 ARTICLE: "writing-help" "Writing documentation"
  15 "By convention, documentation is written in files with the " { $snippet ".facts" } " filename extension. Module documentation should follow a few conventions documented in " { $link "documenting-modules" } "."
  16 $terpri
  17 "A pair of parsing words are used to define free-standing articles and to associate documentation with words:"
  18 { $subsection POSTPONE: ARTICLE: }
  19 { $subsection POSTPONE: HELP: }
  20 "The " { $emphasis "content" } " in both cases is a " { $emphasis "markup element" } ", a recursive structure taking one of the following forms:"
  21 { $list
  22     { "a string," }
  23     { "an array of markup elements," }
  24     { "or an array of the form " { $snippet "{ $directive content... }" } ", where " { $snippet "$directive" } " is a markup word whose name starts with " { $snippet "$" } ", and " { $snippet "content..." } " is a series of markup elements" }
  25 }
  26 "Markup elements are therefore effectively just Factor objects, written using Factor syntax."
  27 { $subsection "printing-elements" }
  28 { $subsection "element-types" } ;
  29
  30 ARTICLE: "printing-elements" "Printing markup elements"
  31 "When writing documentation, it is useful to be able to print markup elements for testing purposes. Markup elements which are strings or arrays of elements are printed in the obvious way. Markup elements of the form " { $snippet "{ $directive content... }" } " are printed by executing the " { $snippet "$directive" } " word with the element content on the stack."
  32 { $subsection print-element }
  33 { $subsection print-content } ;
  34
  35 ARTICLE: "element-types" "Element types"
  36 "Markup elements can be classified into two broad categories, block elements and span elements. Block elements are inset with newlines before and after, whereas span elements flow with the paragraph text."
  37 { $subsection "span-elements" }
  38 { $subsection "block-elements" }
  39 { $subsection "markup-utils" } ;
  40
  41 ARTICLE: "span-elements" "Span elements"
  42 { $subsection $emphasis }
  43 { $subsection $link }
  44 { $subsection $snippet }
  45 { $subsection $url } ;
  46
  47 ARTICLE: "block-elements" "Block elements"
  48 "The following are the standard headings found in word documentation:"
  49 { $subsection $values }
  50 { $subsection $description }
  51 { $subsection $contract }
  52 { $subsection $examples }
  53 { $subsection $warning }
  54 { $subsection $notes }
  55 { $subsection $side-effects }
  56 { $subsection $errors }
  57 { $subsection $see-also }
  58 "Some additional elements:"
  59 { $subsection $code }
  60 { $subsection $curious }
  61 { $subsection $example }
  62 { $subsection $heading }
  63 { $subsection $links }
  64 { $subsection $list }
  65 { $subsection $markup-example }
  66 { $subsection $references }
  67 { $subsection $see }
  68 { $subsection $subsection }
  69 { $subsection $table } ;
  70
  71 ARTICLE: "markup-utils" "Markup element utilities"
  72 "Utility words to assist in defining new elements:"
  73 { $subsection simple-element }
  74 { $subsection ($span) }
  75 { $subsection ($block) } ;