Download Autoduck Tags - Literate Programming

Topic Logs
Autoduck can reference a topic log file when generating hypertext links for RTF. A topic log
file lists the set of topics available to link to. If a topic is listed in the topic log, Autoduck can
create a hypertext link to it. If the topic is not listed, Autoduck can generate alternate
formatting (like bold text).
For more information, see “Topic Logs”.
Autoduck Tags
Autoduck uses tags to identify what type of information is contained in a comment block. For
example, a tag might identify a paragraph as a description of a parameter or return value of a
function.
An Autoduck tag consists of an ampersand (@) followed by a tag name. Most Autoduck tags
are defined in a format-information file, which is required by the AUTODUCK.EXE tool.
The format-information file defines the number of fields within a tag, the formatting strings to
output for the tag, and extraction information for the tag. AUTODUCK.EXE only recognizes
tags that appear as the first item within a line of comment text.
There are three basic types of Autoduck tags:
• The @DOC tag, which signals the beginning of Autoduck information within a source file
and defines flags used to determine which Autoduck information to extract.
• Topic tags that define new Autoduck topics.
• Paragraph tags that define new types of paragraphs within Autoduck topics.
All three types of tags must conform to the following formatting conventions:
• Tag names must begin with the "@" character.
• White space is not allowed within a tag name.
• Tag names are not case-sensitive.
Topic and paragraph tags contain one or more fields of text. Fields are delimited by pipe (|)
characters. A field can contain multiple paragraphs of text (paragraphs are delimited by
consecutive newlines). For example, the following @PARM tag defines information for a
paragraph about a function parameter:
//@parm int | iType | Specifies the type.
Autoduck output combines formatting codes stored in the formatting specification file with
field text parsed from the Autoduck comments in the source file. In the above example, the
parameter name iType might be output in italics, followed by an indented paragraph
containing the third (description) field.
In addition, Autoduck provides for text tags that identify special types of paragraph text (for
example, a function or message name). The three types of @ tags, as well as the text tags, are
described in the following sections.
@DOC Tag
The @doc tag must be the first Autoduck tag encountered in the source file. The @doc
signals the beginning of Autoduck information within a source file and identifies extraction
flags, tokens used to classify Autoduck topics. For example, you can classify Autoduck
information as EXTERNAL or INTERNAL, then extract only those topics falling under the