Up: The Wizard

The Page Wizard: Using Macros

Authors familiar with TeX know that macros can greatly simplify coding documents containing a lot of math notation. Macros give authors a way of defining new key words for notations and expressions they use frequently. Although MathML does not presently support macros, WebTeX does support LaTeX-style macros, and the Page Wizard can be used to process these macros in various ways.

WebEQ Macro Processing

When using the Math Viewer to handle all the math in a Web page, each piece of notation is being handled by a separate applet. Applets can communicate with each other and with the browser, but only in somewhat limited ways. As a consequence, in practice, the Page Wizard must specify what macros should be used when processing input in each set of applet tags.

WebTeX macro definitions can either be specified once at the beginning of a document, or in a separate file so they can be referenced in many documents. (As hinted at above, macro definitions are ultimately specified as a parameter in the applet tags of a single applet, but in this section our focus is on document-wide macros.) The Page Wizard facilitates both kinds of document-wide macro definitions.

For macros specified in the document header, the Page Wizard can either expand the macros in each equation before writing the applet tags, or it can distribute macro definitions to the appropriate parameter in each applet tag for the Math Viewer applet to expand later at run time. Since it is faster for the reader to have the Wizard expand the macros, most authors will want to enable the Wizard option to expand macros.

For macros specified in a separate file, the Page Wizard just includes the URL of the file in each applet tag. This URL is determined by the Page Wizard "URL to macro file" option. Note that the macro file must actually be at the location specified by this option in order for the Math Viewer applet to expand the macros when a reader looks at the page. As with macros specified in the document header, macros defined in a file can also be expanded by the Wizard during processing.

In order to process macros in a file (to compute equation sizes, expand them, etc.) the Wizard program itself must also be able to locate the macro file. Consequently, when using external macro files, you must always set the "Local Macro file" option in the Wizard to specify where it should look for its "local" copy of the macro file while it is running.

To reiterate: the "Local Macro file" option is typically an absolute URL pointing to the macro file on the local file system for use during processing. The "URL to Macro File" option is generally a relative URL that the Wizard writes out in the applet tags to instruct the Math Viewer applet where to look for a copy of the macro file on the server. Separating these two options is particularly convenient in situations where you need to process files in a temporary directory before moving them into their final locations on a Web site.

Specifying Macros in the Document Header

When the Wizard runs, it looks for WebTeX macro definitions in a special comment block in the HTML source file header. The syntax of this comment block is illustrated below:

<HTML>
<HEAD>
<TITLE>An Example</TITLE>

<!-- webeq
\define{\gump}{x^2}
-->

</HEAD>
<BODY>

This is a test $\gump = 9$.

</BODY>
</HTML>

Note: The comment block must exactly match this format, including whitespace characters. Assuming that the Wizard "Expand Macros" option is set to true, the Wizard might generate an HTML output file something like this:

<HTML>
<HEAD>
<TITLE>An Example</TITLE>
</HEAD>
<BODY>

This is a test
<applet code="webeq.Main" height=30 width=54>
<param name=eq value="x^2 = 9">
<applet>

</BODY>
</HTML>

If the "Expand Macros" option is set to false, the Wizard would generate an HTML output file like this:

<HTML>
<HEAD>
<TITLE>An Example</TITLE>
</HEAD>
<BODY>

This is a test
<applet code="webeq.Main" height=30 width=54>
<param name=macros value="\define{\gump}{x^2}">
<param name=eq value="\gump = 9">
<applet>

</BODY>
</HTML>

To experiment with using the Wizard to process macros in a document header, try processing the file macros.wiz in the templates directory of the WebEQ distribution.

Specifying Macros in File

If an author wishes to use a large collection of macros, or wishes to share macros between a number of HTML files, it will probably be more convenient to specify macro definitions in an external file. A macro file can be used in conjunction with macro definitions given in the document header, for example, to extend a base set of macros in an external file. Again, to make processing faster for readers, it is usually better to expand macros with the Wizard.

Suppose an author creates a macro file named macros.txt containing the single line

\define{\gump}{x^2}

Suppose further that this author wishes to use this same macro file with three HTML files:

/u/html_files/page1.html

/u/html_files/examples/page2.html
/u/html_files/examples/page3.html

If macros.txt is located in /u/html_files/, the "URL to Macro File" option should be set to "macros.txt" and the "Local Macro file" option should be set to "/u/html_files/macros.txt" when processing page1.html.

On the other hand, when processing page2.html and page3.html, it will be necessary to set "URL to Macro File" to "../macros.txt" since the macro file is in the parent directory relative to page2.html and page3.html. However, the "Local Macro file" option should still be set to "/u/html_files/macros.txt" during processing.

WebEQ 2.5 Documentation Table of Contents