Sections

This is a draft specification. It is likely that changes will still be made before the final specification.

A section is a prominent logical part of a page or another section. Breaking up material into sections can help readers find information more quickly. In Mallard, sections can take part in automatic linking just as pages can.

Notes

The section element contains an optional info element, a title element, an optional subtitle element, any mixture of general block content and links elements, any number of section elements, and any number of links elements.
The section element can occur in page elements and other section elements.
The optional id attribute takes a unique identifier. It should be distinct from all other section id attributes in the same page. It does not have to be distinct from the id attribute on the containing page element.
The style attribute takes a space-separated list of style hints. Processing tools should adjust their behavior according to those style hints they understand.
The section element can have attributes from external namespaces. See External Namespaces for more information on external-namespace attributes.

Examples

Create a page with a single section:

<page xmlns="http://projectmallard.org/1.0/" id="index">
<title>A Simple Page</title>
<section id="first">
  <title>With a Section</title>
</section>
</page>

On large pages, it is sometimes useful to have a list of links to sections. Use the links element to link to the sections in a page:

<page xmlns="http://projectmallard.org/1.0/" id="index">
<title>A Simple Page</title>
<links type="section"/>
<section id="first">
  <title>First Section</title>
</section>
<section id="second">
  <title>Second Section</title>
</section>
</page>

Processing Expectations

Each section is displayed as a block. The title of a section is displayed prominently, followed by any child block content, and finally by each child section. Note that automatic links, style hints, or other special features may insert material or change the way pages are displayed. Sections should be clearly separated from their surrounding content to make the beginning and ending of each section obvious. The depth of each section should be clear, although this may not be feasible for deeply nested sections.

Sections may have links associated with them. See Automatic Links for details. Sections in guide pages have topic links automatically inserted.

Comparison to Other Formats

The section element is similar to the section element in DocBook. DocBook contains numerous sectioning elements. Some processors chunk these elements into separate pages up to a certain depth. The section element in Mallard might be used in place of DocBook elements like chapter, depending on the desired level of page granularity.

The section element is similar to nested topic elements in DITA. The Mallard section element is a structural element. This is different from the DITA section element, which is a simple formal block element.

Schema

The formal definition of the Mallard language is maintained in RELAX NG Compact Syntax in code blocks within this specification. This is the formal definition for the section element. The namespace declarations for this definition are on the page Pages.

mal_section = element section {
  mal_section_attr,

  mal_info ?,
  mal_block_title,
  mal_block_subtitle ?,
  ( mal_block | mal_links ) *,
  mal_section *,
  mal_links *
}
mal_section_attr = (
  mal_section_id ?,
  attribute style { xsd:NMTOKENS } ?,
  mal_attr_external *
)
mal_section_id = attribute id { xsd:ID }