Click or drag to resize
Topic Header

This topic details the AMDL syntax and semantics of topic headers.

Function

Topic headers serve the following purposes:

  1. Specify the topic's title.

  2. Terminate the topic's summary, if present.

  3. Optionally, assign values to the topic's attributes.

Syntax

Two header syntaxes are defined:

1. setext-Style Topic Header:

  1. a line consisting of

    1. zero to three space characters, followed by

    2. unformatted text, followed by,

    3. optionally, an attribute enclosure;

  2. a line consisting of

    1. zero to three space characters, followed by,

    2. one or more = (equals) characters, followed by,

    3. optionally, any number of space characters.

2. ATX-Style Topic Header:

  1. a line consisting of

    1. optionally, up to three space characters, followed by

    2. a # (hash) character, followed by

    3. one or more space characters, followed by

    4. unformatted text, followed by,

    5. optionally, any number of space characters followed by any number of # characters, followed by,

    6. optionally, an attribute enclosure.

In both syntaxes the text must be XML-escaped, i.e.

  • all occurrences of < must be replaced with &lt;,

  • all occurrences of > must be replaced with &gt;, and

  • all occurrences of & must be replaced with &amp;.

If a topic's title is unspecified, the topic's identifier will be used.

Examples

1. setext-style topic header:

AMDL
Copy
Topic Header
============

2. ATX-style topic header:

AMDL
Copy
# Headers
Example Output

  1. This topic's header.

  2. The header of the Block Elements topic.

Attributes

Topic attributes may be specified using the following syntax:

{#identifier .class1 .class2 name1="value1" name2="value2" ...}

The following attributes are defined:

identifier

  • a globally unique string value to be used for resolving internal links to the topic. If no value is specified, a unique identifier will be assigned based on the topic file name; detailed algorithm TBD.

class

  • any of the following:

    • autoOutline - equivalent to specifying autoOutline="true".

    • noSeeAlso - equivalent to specifying noSeeAlso="true".

autoOutline

  • a Boolean value indicating whether an automatic topic outline should be generated. If no attribute value is specified, a topic outline shall be generated for a topic with a setext-style header, and shall not be generated otherwise.

outlineDepth

  • an integer value indicating the maximum depth of the automatic topic outline, if one is generated. If no attribute value is specified, a zero-depth outline shall be generated.

outlineLead

  • a string value that will be used as the lead-in text rendered before the automatic outline, if one is generated. If an empty string is specified, the lead-in text shall be omitted. If no attribute value is specified, a default lead-in text shall be rendered.

noSeeAlso

  • a Boolean value indicating whether the See Also section will be excluded from the automatic topic outline, if both are generated. If no attribute value is specified, the See Also section shall be included if it is specified through a setext-style header, and shall be excluded otherwise.

Differences from PM

  1. No inline formatting is permitted in topic headers.

amdl2maml Support

Partial, pending parser modification.

Limitations:

  1. Attributes are unsupported.

Current Workarounds:

  1. Use different header syntaxes to affect automatic outline rendering.

See Also