24.5.2 Designating DITA ancestor elements

For block elements such as <li> 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. Specify a parent only if it is required to prevent incorrect output. If you find “Parent Error” comments in the resulting XML, first try commenting out any related parent assignment in [DITAParents].

To specify required ancestors of elements mapped from formats (for example):

[DITAParents]
; Frame para format (wildcards OK) = required parents
Title = topic
Heading* = section
Numbered1 = ol li
Numbered = ol li
Bulleted = ul li
Figure Title = fig
Syntax = refsyn
Example = example

In this example a Numbered1 paragraph (which is mapped to <p> in [DITAParaTags]) must have these ancestors:

<ol>...<li>...</li>...</ol>

Therefore, each Numbered1 paragraph starts a new <ol> if and only if an <ol> is not already open; and starts a new <li> if and only if an <li> under the <ol> is not already open. To force a new <ol><li> for Numbered1 paragraphs, you must also give the Numbered1 paragraph format first-child status under both parent and grandparent elements; see §24.5.6 Avoiding invalid ancestries

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

Use this mapping for formats such as lists, in which <li> elements are needed under <ul> or <ol> in addition to the <p> elements mapped in [DITAParaTags].

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 [DITAParents] assignment for a given instance of a paragraph format, place a DITAParent PI marker in the paragraph. Make the content of the marker the name(s) of the ancestor element(s), in hierarchical order. A DITAParent PI marker specifies the required ancestry for the current block element, overriding whatever is specified in [DITAParents].

See also:

§24.7.1 Designating ancestors for <image> and <fig> elements

Previous Topic:  24.5.1 Understanding how DITA2Go determines element nesting

Next Topic:  24.5.3 Fixing up interpolated ancestries

Parent Topic:  24.5 Nesting DITA block elements

Sibling Topics:

24.5.1 Understanding how DITA2Go determines element nesting

24.5.3 Fixing up interpolated ancestries

24.5.4 Deciding when to fully specify ancestry

24.5.5 Specifying alternate ancestries for the same element

24.5.6 Avoiding invalid ancestries

24.5.7 Specifying first-child status for nested elements

24.5.8 Configuring nested lists

24.5.9 Closing DITA ancestor elements

24.5.10 Opening DITA ancestor elements

24.5.11 Configuring multi-paragraph list items

24.5.12 Specifying DITA element levels

Table of ContentsIndex