#### 26.5.4 Deciding when to fully specify ancestry

You do not need to map paragraphs in [DocBookParents] for elements that can have only one possible ancestry, or for cases where DITA2Go can determine heuristically which of the possible ancestors fits the context best. Specify ancestry in [DocBookParents] when more than one lineage is possible in the context of use. This is especially important if your document includes nested section elements; see §26.5.7 Specifying full ancestry for nested sections.

Include as many ancestors as necessary to fully specify ancestry for the element to which a paragraph format is mapped in [DocBookParaTags]. If your document includes actual instances of different ancestries for the same element, use sets of ancestors to specify the alternatives; see §26.5.5 Specifying alternate ancestries for the same element. In some cases you might have to include all ancestors up to the topic level, and you might have to determine this necessity by trial and error; that is, list them all whenever not including all ancestors causes unwanted nesting.

When DITA2Go encounters a set of ancestors specified either in [DocBookParents] or in a DocBookParent PI marker, DITA2Go tries to nest the ancestor hierarchy in the current element. If the entire hierarchy is valid in that position, that is where it stays. This means that if your document uses paragraph format Body (for example) for all text that is not nested in a list, and you map Body to DocBook element <para>, you must also specify non-list parents for Body, because <para> can nest in <listitem>; in fact, in almost any block element. Unless you can make sure every block element that could precede a Body paragraph gets closed (see §26.5.8 Closing DocBook ancestor elements), the Body <para> is likely to be nested in the preceding element.

Previous Topic: 26.5.3 Fixing up interpolated ancestries

Next Topic: 26.5.5 Specifying alternate ancestries for the same element

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.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 Contents • Index