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