PSML

A complete reference of PageSeeder's markup language PSML

<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

Element categoryblock
PSML levelportable
Permitted contenttext and character-style elements
Permitted parent
HTML equivalent<h1> to <h6> 
OpenXML equivalent<w:p> with heading style
PSStandard equivalent<heading1> to <heading6>

Attributes

This element includes the following attributes

NameTypeRequiredDescription
levelheading-levelnoThe level of the heading.
numberedbooleannoIf this heading is numbered.
prefixxs:stringnoPrefix for heading (used for numbered headings).

Note

In processed PSML, level can also have an @id attribute which is referenced by <toc-part>.

@level

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

In processed PSML, the heading level may be greater than 6 once the level of headings in transcluded content has been computed. However, a portable PSML document should 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 may 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 a 10 character is usually not recommended.

Examples

Example #1

A simple 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" >
       <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.

See also

Created on , last edited on