<heading>

Summary

The <heading> element is the structural object that logically groups paragraphs in a document. It is also the primary object for generating a Table of Content (ToC).

Hierarchically, the position of the heading content in the ToC is determined by the value of the @level attribute and how the document that contains the heading is processed by the Publication. Allowable values for @level range from 1 (higher) to 6 (lower).

Numbering headings can be automatic, using the @numbered attribute, or manual, using the @prefix attribute. As a matter of best practice, where documents start with heading, they should start with a <heading level="1">. The level can then be managed using the references document, the document-type or document labels and the publication-config.

For further information about processing the <heading> element, see Publications and publication types.

Usage context

Attributes

This element includes the following attributes

@level

The level of heading, the heading level ranges from 1 to 6.

In processed PSML, the heading level might be greater than 6 once the level of headings in transcluded content has been computed. However, a portable PSML document must not include heading levels exceeding 6.

@numbered

A boolean flag to indicate whether the heading level is automatically numbered.

The actual number of a numbered heading is computed when documents are processed. In the PageSeeder interface, numbered headings are prefixed with ‘x.’ to indicate that their numbering has not been computed. This is because the actual number might vary depending on transclusions and cross-references.

@prefix

A fixed prefix for the heading.

This is an alternative to auto-numbered headings in cases when the heading requires a prefix that does not vary. Although there is no maximum length on the prefix, a value exceeding 10 characters is usually not recommended.

@id

Only allowed in processed PSML.

It has the format [URI ID]-[position]-[fragment ID]-[index] where:

• position is the position of the document in the publication (if the same document has been embedded or transcluded multiple times).
• index is the number of preceding <heading> or <para> elements in the fragment + 1.

Examples

Example #1

A heading appearing as a heading level 1.

<heading level="1">Great title!</heading>

This would be converted in HTML as:

<h1>Great title</h1>

Example #2

Headings level 2 with auto numbering.

<heading level="2" numbered="true">First chapter</heading>
<heading level="2" numbered="true">Second chapter</heading>
<heading level="2" numbered="true">Third chapter</heading>

These would typically be converted in HTML as:

<h2 class="numbered">First chapter</h2>

<h2 class="numbered">Second chapter</h2>

<h2 class="numbered">Third chapter</h2>

Using CSS counters, they could be displayed with numbering; or directly as:

<h2><span class="autonumber">1.1</span> First chapter</h2>
<h2><span class="autonumber">1.2</span> Second chapter</h2>
<h2><span class="autonumber">1.3</span> Third chapter</h2>

Or even as:

<h2 data-prefix="1.1">First chapter</h2>
<h2 data-prefix="1.2">Second chapter</h2>
<h2 data-prefix="1.3">Third chapter</h2>

Example #3

Heading with a fixed prefix.

<heading level="4" prefix="(b)">Special clause</heading>

This would typically be converted as:

<h4><span class="prefix">(b)</span> Special clause</h4>

Or:

<h4 data-prefix="(b)">Special clause</h4>

Schema

XML Schema

<xs:element name="heading" >
  <xs:complexType mixed="true">
    <xs:group ref="character-style-group"
              minOccurs="0" 
              maxOccurs="unbounded" />
    <xs:attribute name="level" use="required">
      <xs:simpleType>
        <xs:restriction base="xs:integer" >
          <xs:pattern value="[1-6]" />
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>

    <xs:attribute name="prefix" type="xs:string" />
    <xs:attribute name="numbered"
                  type="xs:boolean"
                  use="optional"
                  default="false" />
  </xs:complexType>
</xs:element>

Relax Schema

element heading {
  attribute level    { xs:integer },
  attribute prefix         { text }?,
  attribute numbered { xs:boolean }?,
  character-style-group
}

Compatibility

This element was introduced in the first draft of PSML and is well supported from PageSeeder 5.1.