56056 |Agent Types of markup =============== Plain text Blank lines separate paragraphs. Blocks & lists These are plain text, but use hyphens, indentation, and other elements to make lists and blocks of various sorts. Headings These are words with ASCII underlines or overlines. They indicate sections and sub-sections. Tags These are words at the beginning of a line and ending in a colon. There are a limited set of these. Directives This is text enclosed in brackets. It is used to refer to images, footnotes, and text defined elsewhere. Also used to escape blocks of text. Quoted phrase These are words in double-quotes, single-quotes, or back-ticks. They are used to format phrases and hyperlinks. Bracket options This is text enclosed in brackets, like directives, but they follow quoted phrases or headings. Configuration This is a special file that sets options and can specify a table of contents. Quoted words ============ Quoted words can be followed by bracketed markup, but does not have to be. The quotes and default processing is: "..." - Smart quotes. Default options are [qq]. '...' - Linked text. Default options are [qv ...]. `...` - Inline code. Default options are [code]. When followed by bracket options, the default processing is not done. Instead, the processing specified in the brackets is done. Bracket options are: unq - A do-nothing option. Having only this is like having no options at all. The quotes are removed and no other processing is done unless other options are present. sic - Do not remove quotes. q - Surround text with typographical single quotes. qq - Surround text with typographical double quotes. code - Use code font. term - Indicate a technical term being defined. bib - Indicates a book or article title. em - Use general emphasis font. b - Use bold font. i - Use italic font. u - Use underline. qv - The quoted text will link to the section or URL specified by the text. The text is replaced by the actual section title. toc - Same as "qv", but the linked item is also marked as a sub-topic if appropriate. qv ... - The quoted text will link to the specified section or URL, or at least render in an appropriate font. The text is not changed. This option must be last. toc ... - Same as "qv ...", but the linked item is also marked as a sub-topic if appropriate. This option must be last. If the initial quote character is escaped, no processing is done and any following bracket text is not treated as a bracket option. If the initial bracket character is escaped, the bracketed text is not treated as a bracket option, but the default quote processing is still done. Unless "sic" is specified, the original quotes are removed from around the text. These are the same: \'r' means read-only. 'r' [sic] means read-only. The quoted text is not interpreted any further. "[contents]" is rendered as [contents] not as a list of sub-topics. Blocks and Lists ================ Blocks are made with special characters at the flush-left position of a file or comment. : ... This style of block has the same effect as a [CODE] directive. > ... | ... These styles of block has the same effect as a [EXAMPLE] or [VERBATIM] directive. Lists are made of items that follow patterns. The extent of a list item is determined with indentation (initial indentation is shown with '_' for clarity). Blank lines between list items are optional. For all lists but the labeled multi-column list, the list continues until it reaches a paragraph that does not follow the list format (not including paragraphs nested inside an item). - text _text continued Bullet list. Other bullet characters are '*', '+', 'o'. n. text #. text _text continued Numbered list. If a number is given, numbering starts there. Letters can be used by typing 'a' instead of '1', for example. Other characters that can be used in place of a period are ':', ')'. Each list must begin with a number; the hash sign continues numbering within a list. phrase _definition _definition continued A definition list. The definition continues until indentation ends. A hyphen can be included in the term by quoting the term or hyphen. term - definition _def'n continued A simple two-column list. The term is a single word. "phrase" - definition _def'n continued As above, but allows multiple words in the term. The quoting is exactly the same as described in the 'Quoted words' section above, except that the "..." style defaults to the [unq] rather than the [qq] option. You can, of course, explicitly specify the [qq] option. The '...' and `...` styles have their usual effect. Escaping the initial quote has the same effect as escaping the hyphen. term column ----- ----------- item1 defn defn cont item2 defn item3 defn ----- ------------ A titled n-column list. Blank lines separate items in the list. The list continues until the second hyphen line. Headings ======== Headings mark the start of sections. Each section should ideally stand on its own as a complete topic. Headings have ASCII-art underlines or overlines or both. If both an overline and underline are used, the characters must match. The following characters can be used for underlines and overlines: = - : . ~ ^ _ * + # A new underline/overline style encountered in a file or comment block creates a new, inferior, section level. One style must be chosen to indicate the sub-section level. By default, this is an underline of "-". The heading may be followed by a bracket option that specifies a section nickname. The bracket option can be quoted to prevent this. Suppose we have a doc file with the following content: | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | About the Wonderland Library [about] | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ... | | Installation | ~~~~~~~~~~~~ | ... | | Where to Download [download] | ------------------------------ | ... | | About Us | -------- | ... | | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | Required Libraries [req] | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ... | | Installation | ~~~~~~~~~~~~ | ... | | Rabbit | ###### | ... | | Where to Download [download] | ------------------------------ | ... In this example, "About the Wonderland Library" and "Required Libraries" are the highest-level sections, the "Installation" sections are inferior to them, and the "Rabbit-hole" section is inferior to the second "Installation" section. Both "Where to Download" sections are actually sub-sections. To link to a section, use a quoted phrase containing the section's title or nickname. To link to a subsection, you must use the title or its containing section's nickname, followed by a "/" and the sub-section nickname. This means that if you want to link to a sub-section, you must ensure its containing section has a nickname. - 'About the Wonderland Library' and 'about' link to the same section. - 'about' is rendered as a hyperlink to "About the Wonderland Library." - 'required libraries', 'Required Libraries', 'req', and 'REQ' all link to the same section and all are rendered as "Required Libraries." - 'Rabbit' is a valid link. DyDoc would first search for a section with a nickname of "rabbit," and after that fails it would search for a section with the title of "Rabbit." - 'Installation' is not a valid link. There are two sections with that title. Duplicate section titles are not an error, but you would have to assign a nickname to the section of interest and use it to link. - 'About Us' is a valid link. There is only one sub-section with that title. - 'Where to Download' is not a valid link. There are two sub-sections with that title, so you must specify 'about/download' instead. The link is rendered as "Where to Download." - You cannot link to the "Where to Download" sub-section of the "Rabbit" section because that section does not have a section nickname. If you were to try 'Rabbit/Where to Download' or 'Rabbit/download', DyDoc would look for sections with those titles; since those sections don't exist, it would fail. - "...install the 'required libraries' [qv], then..." would render the link as "Required Libraries," but "...install the 'required libraries' [qv rec], then..." would render the link as "required libraries." Section Nicknames ================= Section nicknames are not case sensitive. Tags ==== These are words that start in the leftmost column and end with a colon. If escaped, they are treated as normal text. The scope of the ARGUMENTS, VALUES, NOTE, and WARNING tags is determined by indentation. The scope of the SYNOPSIS tag is one paragraph; indentation is allowed but ignored. The other tags end after one line. Underlines and overlines are allowed but ignored; they will not affect topic structure like headers do. If used, underlines must appear on the next line after the tag itself, and the content of the tag must still be indented if necessary. SYNOPSIS: paragraph A brief description of the topic. DISCUSSION: content This tag starts or continues the main body of a topic. It may be used to end a synopsis after one line without using a blank line to explicitly end the paragraph. SECTION: section Marks the topic as a child of the specified section. RELEVANT TO: 'title' | nickname ... Adds this topic to the "See Also" sections of the specified topics. The topics may be specified by title (in quotes) or nickname. The quotation here is strictly for the purposes of escaping spaces; the quote directives can't be used. SEE ALSO: 'title' | nickname | URL ... Adds the specified topics or URLs to the "See Also" section of this topic. Topics may be specified by title (in quotes) or nickname. The quotation here is strictly for the purposes of escaping spaces; the quote directives can't be used. ARGUMENTS|VALUES: _content An argument or value list. May include paragraphs and other content. Term or phrase definition lists are recognized as argument or value names. INIT-|MAKE? KEYWORDS: _content A keyword list. Similar to ARGUMENTS. The official link nickname for this section is "keywords". GENERIC FUNCTION|METHOD|CLASS|MACRO...: title Start a new reference topic of that type. This new topic is set at the same level as the previous topic. Bracket options are allowed like in headers. NOTE|WARNING: content _content Shows the text in a note or warning box. The text can have the normal markup elements. Directives ========== Some directives must be on a line of their own, others can be included inline. Directives are case-insensitive. In the syntaxes shown below, lower-case words are parameters. If the opening bracket is escaped, it is not treated as a directive. ...[IMG imagename alttext?]... Include an image inline. Scaled to line size. [FIG imagename scale%|linesX?] caption? Include a centered image. ...[n]... Refer to the corresponding [:n] or [n:] line. The scope of "n" is the current comment block or file. ... [:n] Create a reference target for the preceding line. Only recognized in verbatim blocks or comments within code blocks. [n]: ... [n:] ... Create a reference target for the following text. The text may begin on the next line. [CODE] text [END CODE?] Render "text" as code. Any documented elements in the code are made into links if possible. "[:n]" directives are recognized. [VERBATIM|EXAMPLE|DIAGRAM] text [END VERBATIM|EXAMPLE|DIAGRAM?] Render "text" as plain ASCII. No links are made. "[:n]" directives are recognized. ...[SYNOPSIS OF topic]... Shows the synopsis of a topic or documented item. [CONTENTS OF topic?] Shows the subtopics of the current or specified topic. [DITTO topic] Make identical to another topic as much as possible. ... [HTML] html markup [END HTML?] ... HTML is rendered exactly. Only applies to HTML output. ... [DITA] dita markup [END DITA?] ... DITA markup is rendered exactly. Only applies to DITA output. 3412273666 #dylan 1 |Agent /// SYNOPSIS: Builds a 'rule parser' matching a sequence of elements. /// ARGUMENTS: /// "#rest sub-rules" - A series of 'rule parser's, all of which must succeed /// for the returned parser to succeed. /// VALUES: /// rule-parser - A 'rule parser' returning a <sequence>. The sequence will /// contain the sub-rules' products. define function seq (#rest sub-rules) => (rule-parser :: <function>) ... /// Synopsis: A tree that allows unlimited child nodes, numbered from 0. /// Make Keywords: /// fill: - An instance of <object> specifying the initial value for any /// implicitly-created elements. The default value is #f. /// root: - An instance of <object> specifying the value of the root node. /// If omitted, the tree has no root node upon creation. define class <ordered-tree> ... 3412274055 #dylan