Click or drag to resize
Section Header

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

Function

Section headers serve the following purposes:

  1. Specify the section's title.

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

  3. Start a new section.

  4. Optionally, assign values to the section's attributes.

Syntax

Two header syntaxes are defined:

1. setext-Style Section Header:

  1. a line consisting of

    1. zero to three space characters, followed by

    2. 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 - (hyphen) characters, followed by,

    3. optionally, any number of space characters.

2. ATX-Style Section Header:

  1. a line consisting of

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

    2. two to six # (hash) characters, followed by

    3. one or more space characters, followed by

    4. 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;.

Examples

1. setext-style section header:

AMDL
Copy
Examples
--------

2. ATX-style section header:

AMDL
Copy
## Syntax
Example Output

  1. The Examples section.

  2. The Syntax section.

See Also Sections

If a top-level section is titled See Also (case-sensitive), its contents shall be interpreted differently, i.e.

  1. all elements other than links and sub-sections shall be ignored, and

  2. all formatting shall be ignored.

The following sub-section titles are recognized (case-sensitive):

  1. Concepts

  2. Other Resources

  3. Tasks

  4. Reference

Links contained directly in the See Also section, or in an unrecognized sub-section thereof, shall be placed in the Other Resources sub-section.

External links shall be placed in the Other Resources sub-section.

Attributes

Section attributes may be specified using the following syntax:

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

The following attributes are defined:

identifier

  • a string value to be used for resolving local links to the section. If no value is specified, a unique identifier will be assigned based on the header text; detailed algorithm TBD.

class

  • any of the following:

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

autoOutline

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

outlineDepth

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

outlineLead

  • a string value to 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.

Differences from PM

N/A.

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