Priority and Precedence

For each tag encountered in the input TopLeaf looks for a mapping to apply. At most one mapping will be applied for each tag.

It is possible for a single tag to match a number of your defined mappings (for example title, chapter/title and title[level="2"]). The following describes how TopLeaf decides which mapping to use for a tag.

TopLeaf chooses the most appropriate mapping by searching based on mapping priority. For mappings with the same priority it applies a set of precedence rules and then selects the mapping that has the highest precedence.

The first mappings searched are the ones with priority 1. If no match is found, the search continues with priority 2, and so on down to priority 5. All newly-created mappings have a default priority of 3.

Within a priority level, precedence is based on the content of the four fields: Tag in context, Occurrence, Attribute selector, and Page context. Each rule is tested in the order given; the first one that applies is used to determine the precedence.

  1. Mappings with a page context of $note, $float or $headfoot have a higher precedence than those with $document context.

  2. Mappings with a higher number of parents or ancestors in their Tag in context field have precedence over those with fewer parents/ancestors.

  3. Mappings with a smaller number of // (ancestor) relationships in their Tag-In-Context field have precedence over those with a greater number. In other words, parent relationships (a/b) take precedence over ancestor relationships (a//b).

  4. A tag mapping that specifies an attribute selector has precedence over a tag mapping that does not specify an attribute selector.

  5. Mappings have precedence based on their Occurrence field as follows (from highest to lowest): only, first, last, second, even, odd, notlast, notfirst, any.

  6. Plain unqualified mappings have the lowest precedence.

  7. If TopLeaf cannot locate a mapping for a tag, then it will map the tag using an internally defined $implied tag mapping. The behavior of the $implied tag mapping cannot be adjusted by the editor.

By default mappings are grouped by target tag with higher priority/precedence mappings first. You can set an option in the General preferences dialog to display them in alphabetic order by name instead.

You can run the typesetting engine in debug mode to see which mapping rule is selected for each tag. If TopLeaf is applying a mapping that you did not expect, then you may need to define additional, more specific mappings, or create a single mapping that uses internal custom markers to trigger specific effects (see Custom tab).

Examples:

  • $note//title has precedence over chapter/title (rule 1)

  • chapter/title has precedence over book//title (rule 3)

  • book//title has precedence over title[visible="yes"] (rule 2)

  • title[visible="yes"] has precedence over title!notfirst (rule 4)

  • title!notfirst has precedence over title (rule 5)

  • chapter/title[visible="yes"] has precedence over title[type="major"] (rule 2)

  • $note//title has the same precedence as $headfoot//title, but this is not a problem since each applies only to its own unique context.

  • title[visible="yes"] and title[type="major"] have the same precedence, and it is not defined which mapping will be chosen. Situations such as this can be resolved by assigning different priority levels to the two mappings.