Tutorial

A Math on the Web Publishing Process

This tutorial is intended for authors who need to include equations in their web pages.  MathType makes it easy to insert mathematical expressions into your Microsoft Word documents.  The Export to MathPage command provides the easiest way to convert Microsoft Word documents containing equations into Web pages.  We recommend reading "Tutorial 14: Creating Web Pages with Microsoft Word" on page 58 of the MathType User Manual if you have not already done so. If you do not have basic familiarity with these products, please refer to the appropriate manual, help file, or online tutorial.  In addition, while we do not assume you are an expert web page designer, you should have basic familiarity with HTML.

Before you begin, you should make sure your default web browser can properly display MathML.  If you are using Windows Internet Explorer, make sure you have MathPlayer 2 installed on your system.  Otherwise, if you are using the latest version of Netscape or Mozilla, make sure you have downloaded the additional math fonts and installed them on your system.

A primary goal when authoring Math on the Web is to make your pages viewable by the greatest number of users while also offering them the best viewing experience possible.  Not surprisingly, these two goals are somewhat at odds today.

In order to reach the greatest number of users, you would render your equations as images and include those images in your web pages.  In fact, until recently, most web pages that included math were created by using image files to display equations.  While almost all users would be able to view these web pages, there are some drawbacks to using images for equations:

• Although browsers print normal text at the full resolution of the printer, much as a word processor would, images are typically printed as bitmaps, showing no more detail than appears on the screen
• The fonts used in an image are fixed at authoring time, while the font size of the body text of the document is under the browser user's control
• It is impossible to do searches on textual characters or phrases in the equation as there is no text in an image
• It is impossible to transfer the equation to other software for manipulation as mathematics, as the mathematical structure is not preserved

In order to provide the best viewing experience, you would use MathML in your web pages and have the web browser render your equations from the MathML.  Recognizing the need to integrate math into web browsers early on, the W3C defined the initial MathML specification in 1998. In 2001, a new version of MathML was recommended and is widely supported by numerous math-oriented software vendors.  The advantages of using MathML are numerous, including:

• Better rendering quality and print resolution
• Better fit with rest of page (including fonts and colors)
• Better alignment with the rest of the page
• Searchability
• Reusability

Typically, a web browser either supports MathML natively (such as recent versions of Mozilla/Netscape) or a plug-in is required (such as MathPlayer).  However, not everyone will have a MathML-capable web browser.

So, what can be done?  This tutorial describes a process that will give you, the author, the best of both worlds.  In general, this process has the following steps:

1. Set up your directories
2. Publish a version of your web pages for MathML-capable browsers
3. Publish a version of your web pages using images for equations
4. Setting up a gateway page

While it may seem onerous to create two versions of your web pages (one with images of the equations and the other with MathML), using the MathPage functionality within MathType makes this task easy.  By using a gateway page, it is also easy to direct the audience to the best web page for their browser.

Setting Up Your Directories

The first step is to organize your workflow.  You will need to set up the following directories:

• A source directory, where all of your Microsoft Word documents will be kept.  These files will be the original content pages.
• An output directory for MathML web pages you publish
• An output directory for the web pages publish using images for equations

The names of these directories can be anything you want.  One suggestion is to use src for the source directory, xml for the MathML web pages and htm for the web pages using images for equations.  The two output directories are named after the file extension of the web pages they contain (as you will see below).  The reason for creating two output directories is that because of a limitation in Microsoft Word, you cannot save files with the same name, but different extensions, into the same directory.  If you try to do this, the following popup window will be displayed:

As you complete your pages in Microsoft Word, save them as Word (.doc) files in your source directory.

To publish a page as a web page using MathPage, either click on the Export to MathPage toolbar button

or use to the MathType menu option and select Export to MathPage...

Publishing pages for MathML-capable web browsers

To publish web pages for MathML-capable browsers, select MathML using: in the Equations section.  Next, from the drop down menu, select XHTML+MathML.  Notice that the File Name has taken the original Word file name and changed the file extension from .doc to .xml.

Make sure the File Name points to the correct output directory.  Click Browse to choose the correct directory if necessary.  Then click OK to publish your MathML web page.  A popup window will display the progress of translating the Word page into a MathML page:

Once the page has been saved, you will either return to Word or a browser will show the MathML page if you had checked Display in default browser.

Publishing pages for all other web browsers

To publish web pages using images for the equations, select Use images (GIFs) in the Equations section.  Notice that the File Name has taken the original Word file name and changed the file extension from .doc to .htm.  If you wish to take advantage of the MathZoom feature, make sure MathZoom is checked.  The MathZoom feature allows equations to be magnified in any browser so that small details such as subscripts, superscripts, hats and primes can easily be seen.

Make sure the File Name points to the correct output directory.  Click Browse to choose the correct directory if necessary.  Then click OK to publish your web page.  Again, a popup window will display the progress of translating the Word page into a MathML page.  Once the page has been saved, you will either return to Word or a browser will show the MathML page if you had checked Display in default browser.

Setting up a gateway page

As you recall, the purpose for creating two versions of your web pages was to make your pages viewable by the greatest number of users while also offering them the best viewing experience possible.  While all of the web pages have now been created, how do you direct your audience to the appropriate version?  Also, since MathML offers a superior viewing experience, how do you offer your users the option of migrating or upgrading to a MathML-capable web browser?

The answer is by using a gateway page.  A gateway page is a single, centralized destination on a web site to which readers are directed before viewing MathML content.  The gateway page has the advantage of collecting browser detection logic and setup information in one place, and frees authors from the burden of doing this in each content page. 

Depending on how elaborate you want to make your gateway page, here are some types of evaluations it might perform:

• If the users' web browser is MathML-capable, direct them to the MathML web pages.
• If the users are using Windows Internet Explorer, but do not have MathPlayer installed (or have an older version installed), ask them if they would like to install/update the MathPlayer plug-in.  If they say yes, take them to the MathPlayer download/installation page.  If they refuse, direct them to the web pages which use images for equations.
• If the users are using an older version of Netscape or Mozilla (which does not support MathML), ask them if they would like to update their browser.  If they say yes, take them to the Netscape or Mozilla download/installation page.  If they refuse, direct them to the web pages which use images for equations.
• If the users do not have a MathML-capable browser, ask them if they would like to download one.  If they say yes, take them to the appropriate download/installation page.  If they refuse, direct them to the web pages which use images for 
• The fallback option is to direct the users to the web pages which use images for equations.

A sample gateway page is available which will help get you started.  You can modify this gateway page to meet your needs.  While some familiarity with JavaScript will help, you can change a few things without knowing JavaScript.

After you have unzipped the sample gateway page, open gateway.htm in either an HTML editor or a text editor.  Near the top you will see the following lines of text:

    /*=============================================================*/
    /* Output directories for your MathML web pages and            */
    /* web pages using images for equations                        */
    /* (customize for your web site)                               */
    /*=============================================================*/

    var dirMathMLPages = "xml";
    var dirImagesPages = "htm";

You can change the names of the output directories to match the names you used above when publishing your web pages.  For example, if you named the directory with the MathML pages mathml, then you would change the following line:

    var dirMathMLPages = "mathml";

These directory paths are used near the bottom of the page in the following code:

  /*-------------------------------------------------------------*/
  /* Continue                                                    */
  /* If user can view MathML, send them to the MathML pages.     */
  /* Otherwise, send them to the pages with images for equations.*/
  /* (customize for your web site)                               */
  /*-------------------------------------------------------------*/
  var str = "";
  if (isMathMLCapable) {
    str = "<p><a href='"+dirMathMLPages+"/index.html'>Continue</a></p>";
  }
  else {
    str = "<p><a href='"+dirImagesPages+"/index.html'>Continue</a></p>";
  }
  document.write(str);

If your first web page in each output directory is not index.html, you should change that in this part of the gateway page.

Note that the actual text that appears on the gateway page is stored in JavaScript variables.  You can edit these variables, but be careful that you retain the proper quotes ("), string concatenations (+) and semi-colons (;).  For example, to change the opening line on your page to say XYZ  web site (instead of ABC web site), you would change the following variable:

    /*=============================================================*/
    /* Text templates for various conditions                       */
    /* (customize for your web site)                               */
    /*=============================================================*/
    var intro =
      "<p>Welcome to the ABC web site.</p> " +
      "<p>This web site contains pages with mathematical expressions " +
      "in them.  Your browser has been checked to see what capability " +
      "it has for displaying these equations.  Here are the results:</p>";

to:

    /*=============================================================*/
    /* Text templates for various conditions                       */
    /* (customize for your web site)                               */
    /*=============================================================*/
    var intro =
      "<p>Welcome to the XYZ web site.</p> " +
      "<p>This web site contains pages with mathematical expressions " +
      "in them.  Your browser has been checked to see what capability " +
      "it has for displaying these equations.  Here are the results:</p>";

If you are proficient in JavaScript, you can also change the other areas of the gateway page.  Always keep a backup copy of your gateway page, though, in case you need to return to a previous version.

Save your changes and then copy the gateway.htm file to your web site.  When visitors first come to your website, you should direct them to this page, which will then direct them to the appropriate version of the rest of your pages.