26.5.11 Specifying DocBook element levels

Generally speaking, you should not specify element levels unless there really is no other way to properly nest an element; hard-coded levels can cause obscure damage to the output.

To specify the level at which a block element should appear in DocBook output, you can assign a level number to any paragraph formats that are mapped to the element (see §26.4.2 Mapping paragraph formats to DocBook elements). However, for most nesting issues, you should use settings that specify ancestry rather than level; see §26.5.2 Designating DocBook ancestor elements. Assign levels only for the following purposes:

To specify the level of a DocBook block element:

[DocBookLevels]
; para format (wildcards OK) = level in DocBook file
;  required for the DocBookParaTag specified for this element.
FmtName = N

The lower the level number, the higher the level; <set> is level 0, the root. You cannot put anything else at level 0. The set title is at level 1. The first book title in the set is at level 2 (a title below <set> and <book>).

For example:

[DocBookLevels]
Title=1
GlossItem=1
Heading1=3
DefTerm=5
ParamTerm=5

In this example the element levels would be <body> = 1, <section> = 2, the title under <topic> (mapped implicitly from paragraph format Title) = 1, and any title under <section> (mapped explicitly from a Heading1 format) = 3. GlossItem is assigned level 1 because this format is mapped to <glossterm>, which is the first element in a glossary topic (equivalent to <title> in other topic types).

To override the assigned level of a particular paragraph, place a DocBookLevel PI marker in the paragraph. A DocBookLevel PI marker specifies the level at which the current block element should appear in the DocBook file, overriding whatever is specified for the format in [DocBookLevels]. The content of a DocBookLevel PI marker is a single integer.

Previous Topic:  26.5.10 Configuring multi-paragraph list items

Next Topic:  26.6 Designating ancestors for table elements

Parent Topic:  26.5 Nesting DocBook block elements

Sibling Topics:

26.5.1 Understanding how DITA2Go determines element nesting

26.5.2 Designating DocBook ancestor elements

26.5.3 Fixing up interpolated ancestries

26.5.4 Deciding when to fully specify ancestry

26.5.5 Specifying alternate ancestries for the same element

26.5.6 Specifying first-child status for nested elements

26.5.7 Specifying full ancestry for nested sections

26.5.8 Closing DocBook ancestor elements

26.5.9 Opening DocBook ancestor elements

26.5.10 Configuring multi-paragraph list items