macro macro-name
     ( (arg argument-name delimiter) | (token argument-name delimiter?))*
  is
  macro-body
  macro-end

Where:
macro-name

A macro name is either a name token or one or two punctuation characters. A name token consists of a letter or a high-order ASCII character (ASCII 128 to 255 inclusive) followed by any combination of letters, high-order ASCII characters, digits, underscores ("_"), hyphens ("-") and periods ("."). A punctuation character is anything from the following list: ( ) { } [ ] ! @ $ % ^ & * - + = | \~ : < , > . ? / Specifically, the back-quote character ("`") and the octothorpe (#) are not permitted in macro names, macro argument names, or macro argument delimiters. Punctuation characters do not need to be separated from other macro keywords by white space in the same way names need to be. White space can be added, however, to increase readability.

A single valid name that represents a replaceable argument for the macro.

One or more valid names that delimit the preceding argument or token from what follows.

One or more keywords, names, punctuation characters, quoted strings, numbers, or comments. In fact, anything which can appear in a valid OmniMark program, except the words "arg", "token", "is", and "macro-end". To include these terms, or the word "literal" itself as part of a macro, precede them with "literal".

Defines a macro.

Macros are used for two purposes -- to define constants and to extend the language. Defining constants is simple:

  macro five is 5 macro-end
  macro mary is "Mary had a little lamb%n" macro-end
  macro tom tom is "Tom, Tom, the piper's son.%n" macro-end

  find mary
     local counter x initial {five}
     output "%d(x)%n"
     output tom tom

The sample above shows that a constant defined by a macro can be used either as a text or number replacement or as a pattern. You can also include patterns in a constant to form a new pattern. This is the simplest form of extending the language. Here the pattern for finding valid SGML names is encapsulated by a macro:

  macro sgml-name is (letter [letter | digit | "-."]*) macro-end

Extending the language becomes a little more complex if you need to provide parameters to your macros. One classic language extension is the "upto" macro which matches characters up to a specified pattern. It is defined:

  macro upto (arg pat) is
     ((lookahead not (pat)) any)+
  macro-end

  process
     submit "Mary had a little lamb"

  find "Mary" upto ("little") => found-stuff
     output found-stuff

  find any  

Apart from being extremely useful, this macro illustrates several important points about macros. First of all, the name of this macro is not actually "upto", but "upto (". The parentheses are not part of OmniMark's syntax for defining macros, they are actually part of the syntax of the macro being defined.

So what about the closing parenthesis? It is the delimiter of the first (and, in this case, only) parameter, which is defined by the keyword arg. In the case of the upto macro a delimiter is needed, since the pattern passed to it could be complex and contain spaces:

  find "xyz" upto ( "@" letter+ "$" ) 

If you define a macro with multiple parameters you can do it like this, using traditional parentheses and commas for delimiters:

  macro sum ( arg n1, arg n2, arg n3) is
     n1 + n2 + n3
  macro-end

  process
     local counter n
     set n to sum (1, 2, 3)

But you can also define a macro using any delimiters you like, including ones that contain spaces:

  macro sum > arg n1 big dog arg n2 / arg n3 ! is
     n1 + n2 + n3
  macro-end

  process
     local counter n
     set n to sum >1 big dog 2/ 3!

The above code works but its meaning is not very clear. There are ways to make your language extensions clearer by using appropriate words or punctuation as delimiters:

  macro sum arg n1 and arg n2 and token n3 is
     (n1 + n2 + n3)
  macro-end

  process
     local counter n
     set n to sum 12 and 52 and 37

As its name implies, a token parameter can only be a single token -- a sequence of characters with no spaces, or a quoted string. The purpose of providing both "token" and "arg" parameterization is to allow you maximum flexibility in defining your language extensions. It has no effect on what kind on parameter you pass to a macro or how that parameter is used in the body of the macro. You are not prohibited from using a delimiter with a "token" argument, but it is not required.

There is one other important difference between "arg" and "token" parameterization. Parameters declared with arg may contain names of other macros, which will be expanded in the present macro. Parameters declared with token may be macro names, but will not be treated as such. Thus, you could pass a macro that expressed a complex pattern to the "upto" macro:

  macro at-dollar is ("@" letter+ "$") macro-end

  find "xyz" upto ( at-dollar ) 

  macro upto token pat is
     ((lookahead not (pat)) any)+
  macro-end

  macro at-dollar is "@" letter+ "$" macro-end

  find "xyz" upto at-dollar  ;error!

The following restrictions apply to macro use: Where two macros have names which start with the same word or words, the longer name will always be matched if possible. Thus, given:

  macro go ...
  macro sleep ...
  macro go to ...
  macro to sleep ...

  process
     go to sleep
     go sleep

Macros cannot represent partial names. Consider a program that uses long counter names like chapternumber, figurenumber, and contains the following macro definitions:

  macro chp is chapter macro-end
  macro num is number macro-end

The name chpnum is not a substitute for chapternumber.

Macros cannot be redefined. Once a macro name has been defined, another macro cannot be defined with the same name in the same OmniMark program. Attention has been paid to this requirement when an include declaration is used to combine macro definitions from different sources in a single OmniMark program.

Versions of OmniMark prior to V3 allowed you to use the back-quote character in macro names. If your program uses the back-quote character you must:

• change or remove the back-quote character,
• add the declare heralded-names declaration, or
• run the program with the "-herald" command-line option