Occurrence

This field enables you to select a tag based on its position within its parent. If we are (say) mapping a <para> tag, then setting Occurrence to first will map the first <para> in any parent element. Note that this does not mean that the <para> must be the first child of its parent, just that is the first <para> within the parent.

It is possible to define multiple mappings based on different values of this field. It is also possible that a given tag may match a number of occurrence options (say first, notlast and any). In this case the mapping with the highest precedence is chosen.

The available values, in order of precedence from highest to lowest, are as follows:

  • only — the tag is the only tag of its type in the parent;

  • first — the tag is the first of its type within the parent;

  • last — the tag is the last of its type within the parent;

  • second — the tag is the second of its type within the parent;

  • odd — the tag's position is odd numbered;

  • even — the tag's position is even numbered;

  • notlast — the tag is not the last of its type within the parent;

  • notfirst — the tag is not the first of its type within the parent;

  • any — matches any tag (the default).

The resulting mapping will show the occurrence after an exclamation mark, as in:

section/note!first

except where the option is any (in which case nothing is added to the mapping name).

It is possible to perform more complex selections based on occurrence. For example, to perform a specific action on every fifth occurrence of a tag. These selections are made in the Custom tab, and are covered in Custom tab (see in particular the sections on flow control and the {tag-occurrence} variable).

For more information on precedence, see “Priority and Precedence”.