6.5. Event Processing

6.5.1. The on Macro

The on macro allows you to execute an arbitrary piece of Perl code during document conversion. The syntax of the on macro is:

 !on type pattern; [id]; action


For example, the following statement makes every heading a hypertext target named itself:

  !on paragraph 'H\d';; $attr{'id'} = $text

6.5.2. Event Types

The types supported and the symbols available in the respective actions include:

Type Symbols
paragraph $style, $text, %attr
phrase $style, $text, %attr
macro $name, $args
filter $name, $params
table $style, %param

6.5.3. Event Patterns

Some example event patterns are given below.

Pattern Comments
'XYZ' matches a thing called XYZ
'AB|CD|E' matches things named AB, CD or E
'H1' for paragraphs, matches a level 1 normal heading
'H[1-4]' for paragraphs, matches normal headings at levels 1 to 4
'[HAP]\d' for paragraphs, matches all headings

If the pattern is an empty string, the action is executed for all entities of that type.

If multiple actions are registered for a given type, actions are executed in "last in, first out" order.

6.5.4. The off Macro

The off macro is used to cancel an event. The syntax is:

 !off type id

For example:

  !on paragraph 'H\d'; XYZ; $attr{'id'} = $text
  # lots of SDF
  !off paragraph XYZ

If two events are given the same name, the most-recently-named event will be cancelled. i.e. nested event cancelling works as expected.

6.5.5. Examples Generating Hypertext Targets

To make all level 1 and 2 headings hypertext targets:

  !on paragraph '[HAP][12]';; $attr{"id"} = $text Generating Index Entries

To make index entries for all commands (CMD character tags):

  !on phrase 'CMD';; $attr{"index"} = $text Adjusting Heading Levels

To move normal headings down one level:

  !on paragraph 'H\d';; $style =~ tr/1234/2345/ Changing Spelling

To convert selected words to North American spelling:

  !on paragraph '';; $text =~ s/colour/color/ig; \
                     $text =~ s/ise\b/ize/g

This approach uses Perl's substitute operator on the text in each paragraph: