basis/help/help-docs.factor

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