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

where:

type specifies the event type
pattern is a Perl regular expression string, anchored at both ends, which specifies which styles (or names) the action is to be executed for
id is optionally used to name an event for later disabling via the off macro
action is the block of Perl code to execute.

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

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

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

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.

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.

To make all level 1 and 2 headings hypertext targets:

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

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

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

To move normal headings down one level:

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

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: