{ $values { "element""a markup element of the form " { $snippet "{ string... }" } } }
{ $description "Prints code examples, as seen in many help articles. The markup element must be an array of strings." }
{ $notes
"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."
$nl
"If you want to show code along with sample output, use the " { $link $example } " element."
}
{ $examples
{ $markup-example { $code "2 2 + ." } }
} ;
HELP:$vocabulary
{ $values { "element""a markup element of the form " { $snippet "{ word }" } } }
{ $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." } ;
HELP:$description
{ $values { "element""a markup element" } }
{ $description "Prints the description subheading found on the help page of most words." } ;
HELP:$contract
{ $values { "element""a markup element" } }
{ $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." }
{ $examples
{ $markup-example { $contract "Methods of this generic word must always crash." } }
} ;
HELP:$examples
{ $values { "element""a markup element" } }
{ $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." }
{ $values { "element""a markup element of the form " { $snippet "{ inputs... output }" } } }
{ $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." }
{ $examples
"The 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:"
"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."
} ;
HELP:$markup-example
{ $values { "element""a markup element" } }
{ $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." }
{ $values { "element""an array of arrays of markup elements" } }
{ $description "Prints a table given as an array of rows, where each row must have the same number of columns." }
{ $examples
{ $markup-example
{ $table
{ "a""b""c" }
{ "d""e""f" }
}
}
} ;
HELP:$values
{ $values { "element""an array of pairs of markup elements" } }
{ $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 can be an element of any form." } ;
HELP:$list
{ $values { "element""an array of markup elements" } }
{ $description "Prints a bulleted list of markup elements." }
{ $notes
"A common mistake is that if an item consists of more than just a string, it will be broken up as several items:"
{ $markup-example
{ $list
"First item"
"Second item " { $emphasis "with emphasis" }
}
}
"The fix is easy; just group the two markup elements making up the second item into one markup element:"
{ $markup-example
{ $list
"First item"
{ "Second item " { $emphasis "with emphasis" } }
}
}
} ;
HELP:$errors
{ $values { "element""a markup element" } }
{ $description "Prints the errors subheading found on the help page of some words. This section should document any errors thrown by the word." }
