26.5.2 Designating DocBook ancestor elements

For block elements such as <listitem> that can have more than one possible ancestry, map any paragraph formats to the intended (required) parent element, and if necessary, grandparent element, even great-grandparent element. List ancestors in hierarchical order. For example:

[DocBookParents]
; para format (wildcards OK) = required parents
Heading* = section
Numbered1 = orderedlist listitem
Numbered = orderedlist listitem
Bulleted = itemizedlist listitem
TableTitle = table
Figure Title = mediaobject
Example = example

These settings specify, for example, that a Numbered1 paragraph (which is mapped to <para> in [DocBookParaTags]) has these ancestors:

<orderedlist>...<listitem>...</listitem>...</orderedlist>

Therefore, each Numbered1 paragraph starts a new <orderedlist> if and only if an <orderedlist> is not already open; and starts a new <listitem> if and only if an <listitem> under the <orderedlist> is not already open. To force a new <orderedlist><listitem> for Numbered1 paragraphs, you must also give the Numbered1 paragraph format first-child status under both parent and grandparent elements; see §26.5.6 Specifying first-child status for nested elements

Note:  For list items that can include more than one paragraph, map the paragraph format to <para>, then designate its including list element as a parent.

Use this mapping for formats such as lists, in which <listitem> elements are needed under <itemizedlist> or <orderedlist> in addition to the <para> elements mapped in [DocBookParaTags].

List ancestors in hierarchical order

If a parent element has more than one possible parent, and only one of those parents can be a grandparent of the paragraph format in question, list both the grandparent and parent, in hierarchical order.

Override individual ancestries

To override the [DocBookParents] assignment for a given instance of a paragraph format, place a DocBookParent PI marker in the paragraph. Make the content of the marker the name(s) of the ancestor element(s), in hierarchical order. A DocBookParent marker specifies the required ancestry for the current block element, overriding whatever is specified in [DocBookParents].

Previous Topic:  26.5.1 Understanding how DITA2Go determines element nesting

Next Topic:  26.5.3 Fixing up interpolated ancestries

Parent Topic:  26.5 Nesting DocBook block elements

Sibling Topics:

26.5.1 Understanding how DITA2Go determines element nesting

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

26.5.11 Specifying DocBook element levels

Table of ContentsIndex