Page Wizard Features and Capabilities

Source Files and Output Files

The first thing you need to understand about preparing HTML files with the Page Wizard is that you will be dealing with two versions of your HTML file: the original file that you write, and the new file that the Wizard creates by processing the original file. We'll call the one that you write the "HTML source" file, and the one that the Wizard generates the "HTML output" file.

The HTML source file is an ordinary HTML file, with markup for math interspersed with the text. In the HTML output file, the Wizard replaces the math markup with applet or image tags. It is this HTML output file that you post to the Web or view with a browser. Whenever you need to make a change to your document, you should make the change in the original HTML source file, then run the Wizard on it again to produce a new output file.

Although this may seem confusing at first, it's analogous to the way many document preparation systems work. For example, when using TeX, you write a file containing TeX source, run the TeX processor on it, and then view or print the resulting DVI file. The attraction of this model is that it allows you to write much cleaner, simpler documents than would otherwise be possible, and it allows you to reprocess your source documents at a later date, as display and browser technology changes.

The Page Wizard can process HTML source files with either WebTeX or MathML markup embedded in them. For authors that want to enter commands directly by hand in their source files, the WebTeX markup language will be the most convenient choice. However, the Wizard can process source files with MathML markup in it as well, which will be the most conventient choice if you use an equation editor -- you can just cut and paste MathML code directly from the editor into your source file.

The source and output file are specified on the Page Wizard main panel. If you specify no output file, a window will pop-up containing the output. On the main panel, you also specify the type of output file, and whether or not to generate fallback images (when allowed).

Marking Equations in the Source File

In order for the Page Wizard to automatically convert equation markup into images or applet code, the equation markup must be set off from the rest of the HTML input by equation delimiters. The Wizard recognizes two kinds of equation delimiters. WebTeX equations in the HTML source file can be delimited with either of the two standard LaTeX delimiters for mathematical expressions:

Displayed equations appear centered and set off by vertical space from the surrounding text. The top-level MathML <math> ... </math> tags can also be used to delimit equations. However, in this case, displayed equations must be explicitly marked up by the author using <P> and <CENTER> tags.

Here's an example showing a simple HTML source fragment illustrating the use of WebTeX delimiters, and the resulting HTML output. If you were in doubt about the advantages of a simple HTML source file vs. the inconvenience of running the Wizard, this should put your mind to rest.

You specify whether he Page Wizard should process WebTeX or MathML, and what kind of equation delimiters to look for on the Options panel. In most cases, both of these settings should be the same.

Generating Math Viewer Applet Tags

Writing WebEQ Math Viewer applet tags is difficult, in part, because there are many parameters that must be entered each time. On top of that, coding applet tags by hand is slow and tedious. To remedy this situation, the Page Wizard will write out all the applet tags for you, based on your settings in the Options panel.

The Page Wizard scans through the source file looking for embedded math markup between equation delimiters When it finds an equation, the Wizard computes or looks up all the necessary information, and writes out WebEQ applet tags in the HTML output file. For example, in an HTML source file, a WebTeX author might write:

The area of a circle is given by $A = \pi r^2$, where r is the radius.

The area of a circle is given by
<applet codebase="classes" code="WebEQ.Main" height=28 width=87>
<param name=eq value="A= \pi r^2">
</applet>, where r is the radius.

Note that the Page Wizard writes out the height and width of the applet, since Java applets must specify in advance how large they should be. Unfortunately, it is difficult to specify one set of dimensions that yield visually acceptable results on all Java systems. As a result, the Wizard will usually write out applet dimensions that are a few pixels too large, though occasionally, an equation may be clipped as well. By changing the Wizard options you can control how much padding the Wizard allows, if you are getting unacceptable results.

In addition to tweaking the dimensions, there are a number of settings in the Option panel for enabling or disabling various MathViewer features, like mouse selections, a font size control panel, and linebreaking. You can also specify the relative locations of all the MathViewer class and archive files.

When you only have one or two applets on a page, you can directly type the equation into the Page Wizard main panel. Note: equations processed in this way must still be surrounded by equation delimiters. Hitting "Go" will generate an applet tag that you can then cut-and-paste.

The Math Viewer in Internet Explorer 5

In IE5, it is possible to set up the Math Viewer as a rendering behavior for embedded MathML. An IE behavior uses a style sheet and JavaScript to automatically replace MathML expressions with Math Viewer applets. Behaviors also allow the Math Viewer to automatically adjust its size to match the surrounding font size and colors scheme.

Note: At present, using a Math Viewer rendering behavior is the only commercially supported way of render strict MathML in HTML and XML documents in IE5. WebEQ rendering behaviors allow you to publish standards-compliant documents for IE5, as well as for Amaya, e-Lite, Mozilla and other MathML capable browsers.

You can tell the Page Wizard to generate the necessary stylesheet and script headers by checking a box in the Options panel. In addition, you will have to be sure that the behavior file mml.htc and associated JavaScript file webeqResize are present in the same directory with your HTML file. You can find these files in the ./scripts subdirectory of your WebEQ 2.5 installation.

Embedding MathML in XML and attaching rendering behaviors requires that the <math> element be prefixed with a label, which is declared in the header of the document and in the <math> tag. This prefix identifies what is called a namespace for the math markup. You can turn namespaces on and off, as well as pick the prefix (which is arbitrary but must be unique in the document) in the Options panel.

One drawback with producing a page for use in IE5 is that it will not render correctly in other browsers, except Mozilla beta versions with MathML enabled. At present, it is probably best to produce another version of your document for other browsers. However, methods of providing fallback images for MathML in older browsers are under discussion at W3C, and this shortcoming is likely to be addressed in future versions of WebEQ.

Generating Images for HTML files

When you aren't using the Page Wizard to generate applet tags, chances are you will be using it to generate image files. In many situations, where interactivity is not very important, images will be faster and more satisfactory than many separate applets. Images also allow WebEQ pages to be printed in older browsers. Images print quality leaves something to be desired, but low resolution images are at least a workable solution.

The Wizard can generate two types of images: JPEGs and PNGs. The PNG format is much better suited for this images of equations than JPEG. PNG is a relatively new image format, similar (and in many ways superior to) GIFs. Recent browsers (Internet Explorer 4.x and Navigator 4.x and higher) support PNGs, although there are some problems printing them in some of the older 4.x browsers. If you are concerned about readers having older browsers, JPEGs may be used as an acceptable compromise in most cases.

Note: to be able to generate PNGs, you must be running the Wizard under Java 1.1 or later. This will only affect you if you chose to use your own Java installation, instead the WebEQ distributions which include a Java VM (the default).

In some cases, you may wish to specify a subdirectory to hold the images, or to specify a base name for the images. Both of these settings can be specified in the Options panel. Images are given the basename with a number appended in the sequence they are encountered in the document. The first image, however, has no number appended, since it is handy to use the Page Wizard to generate a single image with exactly the name you specify.

Translation and Macro Expansion

Another useful feature of the Page Wizard is its ability to process document-wide macro definitions, so that WebTeX authors can introduce shorthand commands for their commonly used notations. In the Options panel, you can also specify the location of macro files for processing, and specify settings for whether they are included in the applet parameters, or whether they are expanded in advance.

You may also specify that the Page Wizard translate WebTeX into MathML. This is an easy way to generate documents in this newly standardized format for authors familiar with TeX. Encoding equations in MathML format has many advantages, including inter-operability with computer algebra systems and accessibility software, and the guarantee that your data will be in a format that will be supported for years to come.

There are also Page Wizard settings in the Option panel that determine how errors are handled. By default, errors go to a pop-up panel. However, you can redirect them to a file, or have them included in HTML format in the output.

Special Characters

Dollar signs require special attention when you use them in a Wizard source file. To get $ to show up in the HTML output file, use \$ in the input file.

Comments