basis/help/help-docs.factor

   1 USING: help.markup help.crossref help.stylesheet help.topics
   2 help.syntax definitions io prettyprint summary arrays math
   3 sequences vocabs strings ;
   4 IN: help
   5
   6 ARTICLE: "printing-elements" "Printing markup elements"
   7 "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."
   8 { $subsection print-element }
   9 { $subsection print-content } ;
  10
  11 ARTICLE: "span-elements" "Span elements"
  12 { $subsection $emphasis }
  13 { $subsection $strong }
  14 { $subsection $link }
  15 { $subsection $vocab-link }
  16 { $subsection $snippet }
  17 { $subsection $slot }
  18 { $subsection $url } ;
  19
  20 ARTICLE: "block-elements" "Block elements"
  21 "Paragraph break:"
  22 { $subsection $nl }
  23 "Standard headings for word documentation:"
  24 { $subsection $values }
  25 { $subsection $description }
  26 { $subsection $class-description }
  27 { $subsection $error-description }
  28 { $subsection $var-description }
  29 { $subsection $contract }
  30 { $subsection $examples }
  31 { $subsection $warning }
  32 { $subsection $notes }
  33 { $subsection $side-effects }
  34 { $subsection $errors }
  35 { $subsection $see-also }
  36 "Elements used in " { $link $values } " forms:"
  37 { $subsection $instance }
  38 { $subsection $maybe }
  39 { $subsection $or }
  40 { $subsection $quotation }
  41 "Boilerplate paragraphs:"
  42 { $subsection $low-level-note }
  43 { $subsection $io-error }
  44 "Some additional elements:"
  45 { $subsection $code }
  46 { $subsection $curious }
  47 { $subsection $example }
  48 { $subsection $heading }
  49 { $subsection $links }
  50 { $subsection $list }
  51 { $subsection $markup-example }
  52 { $subsection $references }
  53 { $subsection $see }
  54 { $subsection $subsection }
  55 { $subsection $table } ;
  56
  57 ARTICLE: "markup-utils" "Markup element utilities"
  58 "Utility words to assist in defining new elements:"
  59 { $subsection simple-element }
  60 { $subsection ($span) }
  61 { $subsection ($block) } ;
  62
  63 ARTICLE: "element-types" "Element types"
  64 "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."
  65 { $subsection "span-elements" }
  66 { $subsection "block-elements" }
  67 { $subsection "markup-utils" } ;
  68
  69 IN: help.markup
  70 ABOUT: "element-types"
  71
  72 ARTICLE: "browsing-help" "Browsing documentation"
  73 "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. Help topics are identified by article name strings, or words. You can request a specific help topic:"
  74 { $subsection help }
  75 "You can also display the main help article for a vocabulary:"
  76 { $subsection about } ;
  77
  78 ARTICLE: "writing-help" "Writing documentation"
  79 "By convention, documentation is written in files whose names end with " { $snippet "-docs.factor" } ". Vocabulary documentation should be placed in the same directory as the vocabulary source code; see " { $link "vocabs.loader" } "."
  80 $nl
  81 "A pair of parsing words are used to define free-standing articles and to associate documentation with words:"
  82 { $subsection POSTPONE: ARTICLE: }
  83 { $subsection POSTPONE: HELP: }
  84 "A parsing word defines the main help article for a vocabulary:"
  85 { $subsection POSTPONE: ABOUT: }
  86 "The " { $emphasis "content" } " in both cases is a " { $emphasis "markup element" } ", a recursive structure taking one of the following forms:"
  87 { $list
  88     { "a string," }
  89     { "an array of markup elements," }
  90     { "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" }
  91 }
  92 "Here is a more formal schema for the help markup language:"
  93 { $code
  94 "<element> ::== <string> | <simple-element> | <fancy-element>"
  95 "<simple-element> ::== { <element>* }"
  96 "<fancy-element> ::== { <type> <element> }"
  97 }
  98 { $subsection "element-types" }
  99 { $subsection "printing-elements" }
 100 "Related words can be cross-referenced:"
 101 { $subsection related-words }
 102 { $see-also "help.lint" } ;
 103
 104 ARTICLE: "help-impl" "Help system implementation"
 105 "Help topic protocol:"
 106 { $subsection article-name }
 107 { $subsection article-title }
 108 { $subsection article-content }
 109 { $subsection article-parent }
 110 { $subsection set-article-parent }
 111 "Boilerplate word help can be automatically generated (for example, slot accessor help):"
 112 { $subsection word-help }
 113 { $subsection word-help* }
 114 "Help article implementation:"
 115 { $subsection article }
 116 { $subsection articles }
 117 "Links:"
 118 { $subsection link }
 119 { $subsection >link }
 120 "Utilities for traversing markup element trees:"
 121 { $subsection elements }
 122 { $subsection collect-elements }
 123 "Links and " { $link article } " instances implement the definition protocol; refer to " { $link "definitions" } "." ;
 124
 125 ARTICLE: "help" "Help system"
 126 "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."
 127 { $subsection "browsing-help" }
 128 { $subsection "writing-help" }
 129 { $subsection "help.lint" }
 130 { $subsection "help-impl" } ;
 131
 132 IN: help
 133 ABOUT: "help"
 134
 135 HELP: $title
 136 { $values { "topic" "a help article name or a word" } }
 137 { $description "Prints a help article's title, or a word's " { $link summary } ", depending on the type of " { $snippet "topic" } "." } ;
 138
 139 HELP: print-topic
 140 { $values { "topic" "an article name or a word" } }
 141 { $description
 142     "Displays a help topic on " { $link output-stream } "."
 143 } ;
 144
 145 HELP: help
 146 { $values { "topic" "an article name or a word" } }
 147 { $description
 148     "Displays a help topic."
 149 } ;
 150 HELP: about
 151 { $values { "vocab" "a vocabulary specifier" } }
 152 { $description
 153     "Displays the main help article for the vocabulary. The main help article is set with the " { $link POSTPONE: ABOUT: } " parsing word."
 154 } ;
 155
 156 HELP: :help
 157 { $description "Displays documentation for the most recent error." } ;
 158
 159 HELP: $subsection
 160 { $values { "element" "a markup element of the form " { $snippet "{ topic }" } } }
 161 { $description "Prints a large clickable link to the help topic named by the first string element of " { $snippet "element" } "." }
 162 { $examples
 163     { $code "{ $subsection \"sequences\" }" }
 164 } ;
 165
 166 HELP: $index
 167 { $values { "element" "a markup element containing one quotation with stack effect " { $snippet "( quot -- )" } } }
 168 { $description "Calls the quotation to generate a sequence of help topics, and outputs a " { $link $subsection } " for each one." } ;
 169
 170 HELP: ($index)
 171 { $values { "articles" "a sequence of help articles" } }
 172 { $description "Writes a list of " { $link $subsection } " elements to " { $link output-stream } "." } ;
 173
 174 HELP: xref-help
 175 { $description "Update help cross-referencing. Usually this is done automatically." } ;
 176
 177 HELP: sort-articles
 178 { $values { "seq" "a sequence of help topics" } { "newseq" "a sequence of help topics" } }
 179 { $description "Sorts a sequence of help topics." } ;
 180
 181 { article-children article-parent xref-help } related-words
 182
 183 HELP: $predicate
 184 { $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
 185 { $description "Prints the boilerplate description of a class membership predicate word such as " { $link array? } " or " { $link integer? } "." } ;
 186
 187 HELP: print-element
 188 { $values { "element" "a markup element" } }
 189 { $description "Prints a markup element to " { $link output-stream } "." } ;
 190
 191 HELP: print-content
 192 { $values { "element" "a markup element" } }
 193 { $description "Prints a top-level markup element to " { $link output-stream } "." } ;
 194
 195 HELP: simple-element
 196 { $class-description "Class of simple elements, which are just arrays of elements." } ;
 197
 198 HELP: ($span)
 199 { $values { "quot" "a quotation" } }
 200 { $description "Prints an inline markup element." } ;
 201
 202 HELP: ($block)
 203 { $values { "quot" "a quotation" } }
 204 { $description "Prints a block markup element with newlines before and after." } ;
 205
 206 HELP: $heading
 207 { $values { "element" "a markup element" } }
 208 { $description "Prints a markup element, usually a string, as a block with the " { $link heading-style } "." }
 209 { $examples
 210     { $markup-example { $heading "What remains to be discovered" } }
 211 } ;
 212
 213 HELP: $subheading
 214 { $values { "element" "a markup element of the form " { $snippet "{ title content }" } } }
 215 { $description "Prints a markup element, usually a string, as a block with the " { $link strong-style } "." }
 216 { $examples
 217     { $markup-example { $subheading "Developers, developers, developers!" } }
 218 } ;
 219
 220 HELP: $code
 221 { $values { "element" "a markup element of the form " { $snippet "{ string... }" } } }
 222 { $description "Prints code examples, as seen in many help articles. The markup element must be an array of strings." }
 223 { $notes
 224     "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."
 225     $nl
 226     "If you want to show code along with sample output, use the " { $link $example } " element."
 227 }
 228 { $examples
 229     { $markup-example { $code "2 2 + ." } }
 230 } ;
 231
 232 HELP: $nl
 233 { $values { "children" "unused parameter" } }
 234 { $description "Prints a paragraph break. The parameter is unused." } ;
 235
 236 HELP: $snippet
 237 { $values { "children" "markup elements" } }
 238 { $description "Prints a key word or otherwise notable snippet of text, such as a type or a word input parameter. To document slot names, use " { $link $slot } "." } ;
 239
 240 HELP: $slot
 241 { $values { "children" "markup elements" } }
 242 { $description "Prints a tuple slot name in the same way as a snippet. The help tool can check that there exists an accessor with this name." } ;
 243
 244 HELP: $vocabulary
 245 { $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
 246 { $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." } ;
 247
 248 HELP: $description
 249 { $values { "element" "a markup element" } }
 250 { $description "Prints the description subheading found on the help page of most words." } ;
 251
 252 HELP: $contract
 253 { $values { "element" "a markup element" } }
 254 { $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." }
 255 { $examples
 256     { $markup-example { $contract "Methods of this generic word must always crash." } }
 257 } ;
 258
 259 HELP: $examples
 260 { $values { "element" "a markup element" } }
 261 { $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." }
 262 { $examples
 263     { $markup-example { $examples { $example "USING: math prettyprint ;" "2 2 + ." "4" } } }
 264 } ;
 265
 266 HELP: $example
 267 { $values { "element" "a markup element of the form " { $snippet "{ inputs... output }" } } }
 268 { $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." }
 269 { $examples
 270     "The input text must contain a correct " { $link POSTPONE: USING: } " declaration, and 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:"
 271     { $markup-example { $unchecked-example "2 2 +" "4" } }
 272     "However the following is right:"
 273     { $markup-example { $example "USING: math prettyprint ;" "2 2 + ." "4" } }
 274     "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."
 275 } ;
 276
 277 HELP: $markup-example
 278 { $values { "element" "a markup element" } }
 279 { $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." }
 280 { $examples
 281     { $markup-example { $markup-example { $emphasis "Hi" } } }
 282 } ;
 283
 284 HELP: $warning
 285 { $values { "element" "a markup element" } }
 286 { $description "Prints an element inset in a block styled as so to draw the reader's attention towards it." }
 287 { $examples
 288     { $markup-example { $warning "Incorrect use of this product may cause serious injury or death." } }
 289 } ;
 290
 291 HELP: $link
 292 { $values { "element" "a markup element of the form " { $snippet "{ topic }" } } }
 293 { $description "Prints a link to a help article or word." }
 294 { $examples
 295     { $markup-example { $link "dlists" } }
 296     { $markup-example { $link + } }
 297 } ;
 298
 299 HELP: textual-list
 300 { $values { "seq" "a sequence" } { "quot" { $quotation "( elt -- )" } } }
 301 { $description "Applies the quotation to each element of the sequence, printing a comma between each pair of elements." }
 302 { $examples
 303     { $example "USING: help.markup io ;" "{ \"fish\" \"chips\" \"salt\" } [ write ] textual-list" "fish, chips, salt" }
 304 } ;
 305
 306 HELP: $links
 307 { $values { "topics" "a sequence of article names or words" } }
 308 { $description "Prints a series of links to help articles or word documentation." }
 309 { $notes "This markup element is used to implement " { $link $links } "." }
 310 { $examples
 311     { $markup-example { $links + - * / } }
 312 } ;
 313
 314 HELP: $see-also
 315 { $values { "topics" "a sequence of article names or words" } }
 316 { $description "Prints a heading followed by a series of links." }
 317 { $examples
 318     { $markup-example { $see-also "graphs" "dlists" } }
 319 } ;
 320
 321 { $see-also $related related-words } related-words
 322
 323 HELP: $table
 324 { $values { "element" "an array of arrays of markup elements" } }
 325 { $description "Prints a table given as an array of rows, where each row must have the same number of columns." }
 326 { $examples
 327     { $markup-example
 328         { $table
 329             { "a" "b" "c" }
 330             { "d" "e" "f" }
 331         }
 332     }
 333 } ;
 334
 335 HELP: $values
 336 { $values { "element" "an array of pairs of markup elements" } }
 337 { $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 is either a single class word, or an element. If it is a class word " { $snippet "class" } ", it is inserted as if it were shorthand for " { $snippet "{ $instance class }" } "." }
 338 { $see-also $maybe $instance $quotation } ;
 339
 340 HELP: $instance
 341 { $values { "element" "an array with shape " { $snippet "{ class }" } } }
 342 { $description
 343     "Produces the text ``a " { $emphasis "class" } "'' or ``an " { $emphasis "class" } "'', depending on the first letter of " { $emphasis "class" } "."
 344 }
 345 { $examples
 346     { $markup-example { $instance string } }
 347     { $markup-example { $instance integer } }
 348     { $markup-example { $instance f } }
 349 } ;
 350
 351 HELP: $maybe
 352 { $values { "element" "an array with shape " { $snippet "{ class }" } } }
 353 { $description
 354     "Produces the text ``a " { $emphasis "class" } " or f'' or ``an " { $emphasis "class" } " or f'', depending on the first letter of " { $emphasis "class" } "."
 355 }
 356 { $examples
 357     { $markup-example { $maybe string } }
 358 } ;
 359
 360 HELP: $quotation
 361 { $values { "element" "an array with shape " { $snippet "{ effect }" } } }
 362 { $description
 363     "Produces the text ``a quotation with stack effect " { $emphasis "effect" } "''."
 364 }
 365 { $examples
 366     { $markup-example { $quotation "( obj -- )" } }
 367 } ;
 368
 369 HELP: $list
 370 { $values { "element" "an array of markup elements" } }
 371 { $description "Prints a bulleted list of markup elements." }
 372 { $notes
 373     "A common mistake is that if an item consists of more than just a string, it will be broken up as several items:"
 374     { $markup-example
 375         { $list
 376             "First item"
 377             "Second item " { $emphasis "with emphasis" }
 378         }
 379     }
 380     "The fix is easy; just group the two markup elements making up the second item into one markup element:"
 381     { $markup-example
 382         { $list
 383             "First item"
 384             { "Second item " { $emphasis "with emphasis" } }
 385         }
 386     }
 387 } ;
 388
 389 HELP: $errors
 390 { $values { "element" "a markup element" } }
 391 { $description "Prints the errors subheading found on the help page of some words. This section should document any errors thrown by the word." }
 392 { $examples
 393     { $markup-example { $errors "I/O errors, network errors, hardware errors... oh my!" } }
 394 } ;
 395
 396 HELP: $side-effects
 397 { $values { "element" "a markup element of the form " { $snippet "{ string... }" } } }
 398 { $description "Prints a heading followed by a list of input values or variables which are modified by the word being documented." }
 399 { $examples
 400     { $markup-example
 401         { { $values { "seq" "a mutable sequence" } } { $side-effects "seq" } }
 402     }
 403 } ;
 404
 405 HELP: $notes
 406 { $values { "element" "a markup element" } }
 407 { $description "Prints the notes subheading found on the help page of some words. This section should document usage tips and pitfalls." } ;
 408
 409 HELP: $see
 410 { $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
 411 { $description "Prints the definition of " { $snippet "word" } " by calling " { $link see } "." }
 412 { $examples
 413     { $markup-example { "Here is a word definition:" { $see reverse } } }
 414 } ;
 415
 416 HELP: $definition
 417 { $values { "element" "a markup element of the form " { $snippet "{ word }" } } }
 418 { $description "Prints a heading followed by the definition of " { $snippet "word" } " by calling " { $link see } "." } ;
 419
 420 HELP: $curious
 421 { $values { "element" "a markup element" } }
 422 { $description "Prints a heading followed by a markup element." }
 423 { $notes "This element type is used by the cookbook-style introductory articles in the " { $link "handbook" } "." } ;
 424
 425 HELP: $references
 426 { $values { "element" "a markup element of the form " { $snippet "{ topic... }" } } }
 427 { $description "Prints a heading followed by a series of links." }
 428 { $notes "This element type is used by the cookbook-style introductory articles in the " { $link "handbook" } "." } ;
 429
 430 HELP: HELP:
 431 { $syntax "HELP: word content... ;" }
 432 { $values { "word" "a word" } { "content" "markup elements" } }
 433 { $description "Defines documentation for a word." }
 434 { $examples
 435     { $code
 436         ": foo 2 + ;"
 437         "HELP: foo"
 438         "{ $values { \"m\" \"an integer\" } { \"n\" \"an integer\" } }"
 439         "{ $description \"Increments a value by 2.\" } ;"
 440         "\\ foo help"
 441     }
 442 } ;
 443
 444 HELP: ARTICLE:
 445 { $syntax "ARTICLE: topic title content... ;" }
 446 { $values { "topic" "an object" } { "title" "a string" } { "content" "markup elements" } }
 447 { $description "Defines a help article. String topic names are reserved for core documentation. Contributed modules should name articles by arrays, where the first element of an array identifies the module; for example, " { $snippet "{ \"httpd\" \"intro\" }" } "." }
 448 { $examples
 449     { $code
 450         "ARTICLE: \"example\" \"An example article\""
 451         "\"Hello world.\" ;"
 452     }
 453 } ;
 454
 455 HELP: ABOUT:
 456 { $syntax "ABOUT: article" }
 457 { $values { "article" "a help article" } }
 458 { $description "Defines the main documentation article for the current vocabulary." } ;
 459
 460 HELP: vocab-help
 461 { $values { "vocab-spec" "a vocabulary specifier" } { "help" "a help article" } }
 462 { $description "Outputs the main help article for a vocabulary. The main help article can be set with " { $link POSTPONE: ABOUT:  } "." } ;