Macros

Steven J Zeil

Last modified: Jul 19, 2016

Contents:

The first stage in processing a CoWeM document is to pass it through a macro processor. The macro processor allows extension of the notation supported by CoWeM beyond the basics of Markdown.

Nearly all of the Markdown extensions described here rely on the macro processor. CoWeM provides a standard set of macros for this purpose, but document authors can add their own.

1 The Macro Commands

The macro processor provides the following commands:

%define: declares new macros. The use of this command is the subject of the remainder of this document.
%if…%else…%endif

2 Defining and Using Macros

Macros are defined using the <tt>%</tt><tt>define</tt> command, which has the form:

%define { name } { parameters } { body }

The { } brackets can be replaced by [ ], ( ), or < >, whichever is convenient.
The name can be any ASCII string not inclduing blanks, control characters, or either of the bracketing characters surrounding the name.
The parameters is a comma-separated list of zero or more parameters - names that will be replaced in the body based upon how the macro was called.
The body is the text that will be inserted in place of the macro call. The body can span multiple lines, and can contain any characters except the ones used for the outer bracket (which is why it is useful to be able to choosethe characters actually used for bracketing.

A macro is used by simply writing the macro name followed immediately by a bracket pair (same options as above) contining a comma-separated list of parameter strings. These may contain any character except a comma and the slected bracketing characters. If a macro is declared to take no parameters, it is called by simply writing its name.

Example 1: A Macro With No Parameters

One of the predefined macros is \firstterm, which is declared as

%define <\firstterm> {newterm} {<span class="firstterm">newterm</span>}

and called as \firstterm{something} or \firstterm[something] or \firstterm<something> or \firstterm(something) to produce “something”. More precisely, it produces an HTML span element with CSS class “firstterm”. The Markdown processor will pass this HTML content through unchanged, and the standard CoWeM dictates the appearance of “firstterm” class elements.

Example 2: A Macro with Multiple Parameters

Another predefined macro is \picOnRight, which typsets a .png graphic on the right of the screen with a stipulation that it grow no wider than a specified percentage of the total width of the document.

It is defined as:

%define <\bPicOnRight> (file,pctwidth) {<div class="noFloat"> </div> <img src="file.png" style="float: right; max-width: pctwidth%;"/>}

Examining the body, you can see how both the file and pctWidth paramters are inserted into the generated HTML.

Example 3: A Macro with No Parameters

The macro \co1 is used to insert a “callout symbol” containing a “1” : ➀ .

It is declared as

%define <\co1><> [<span>➀</span>]

Because this macro is delcared to take no parameters, it is called by writing it without a following bracket: \co1 produces ➀ .

3 Adding New Macros

Macros can be added to a document by simply typing the %define command into the document.

A file of macros can be added by listing it in the metadata for a document, e.g.,

Title: My Document
Author: John Doe
Macros: myMacros.md

# Introduction