Tutorial

Authoring Web Pages with MathML and Macromedia Dreamweaver MX 2004

NOTE: We have a separate tutorial on using Dreamweaver 8 and Dreamweaver CS3 to author XHTML + MathML pages.

When writing technical documents for the web, one of the primary considerations is how to represent the formulas or equations. Design Science produces two tools, MathType and WebEQ, either of which makes it very easy to create the equation visually, then copy it as MathML to paste into your web page. Dreamweaver MX 2004 offers features that make it easy to fine-tune the final look of the page.

This tutorial will assume you have basic familiarity with Dreamweaver MX 2004 (hereafter called simply "Dreamweaver") and either MathType 5 or WebEQ 3.5 or later. We don't assume you are an expert in MathML, but we do assume you have basic familiarity with MathML terminology. The Reference section of our web site has more information if you have further questions.

We recommend additional tutorials and articles as complements to this one:

• A Math on the Web Publishing Process
• Authoring for MathPlayer and MathML
• Authoring Web Pages with MathType 5 and Macromedia Dreamweaver MX 2004
• Tutorial 17: Working with TeX, LaTeX, & MathML in the MathType User Manual
  If you're not a MathType user, you can get a PDF copy of the MathType Manual either by downloading and installing the MathType 30-day trial, or by downloading the manual from our web site (Windows or Macintosh).

This tutorial addresses these topics:

1. MathML and Dreamweaver
2. Required processing instructions and additional statements
3. Inserting inline equations into a web page
4. Inserting display equations into a web page
5. Numbered display equations
6. Creating and editing a MathML tag library
7. Converting all the equations in a Word document to MathML

MathML and Dreamweaver

Our previous tutorial described how to use images to display equations in a web page. This tutorial deals with MathML. Recognizing the need to integrate math into web browsers early on, the Worldwide Web Consortium (W3C) defined the initial MathML specification in 1998. In 2001, a new version of MathML was recommended. 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

To incorporate MathML into your web document using Dreamweaver, you will need to do most of the authoring in Code view or Split view. You can use any MathML authoring tool for the equations. For this tutorial we will use MathType and WebEQ with Dreamweaver to create a web page discussing the roots of a quadratic equation.

Note: The screen shots in this tutorial will reflect the appearance of the Windows versions of the products. The Macintosh versions are similar in appearance and capability.

(Click for larger image (99 KB). Use your browser's Back button to return here.)

Note: Many of the steps discussed below will also apply to earlier versions of the products, but some will not. Since this tutorial only concerns MathType 5, WebEQ 3.5 and later, and Dreamweaver MX 2004, we will not point out differences between these products and earlier versions.

Required processing instructions and additional statements

As our companion tutorial (A Math on the Web Publishing Process) points out, the first step is to make sure your target browser is capable of displaying MathML. Even assuming a MathML-capable browser, there are still some additional lines of code you need to include in your web page to tell the browser what to do when it encounters MathML. These processing instructions and additional statements vary, depending on whether the target browser is Internet Explorer or Netscape. (The Mozilla and Firefox browsers are also capable of displaying MathML. Since these browsers require the same markup as Netscape, and fall into the same category as that browser, whenever we refer to Netscape in this tutorial, we mean all 3 browsers.)

These required processing instructions and header statements are outlined in our companion article, Authoring for MathPlayer and MathML. This article gives several options, but MathPlayer 2.0 makes the choice easy by letting you author the page as if your only target browser were Netscape. If the page is viewed in Internet Explorer (IE) with MathPlayer 2.0 installed, MathPlayer transforms the page into one that IE can display. This is done with no additional action on the part of the person viewing the page, other than installing MathPlayer.

A note about filename extensions: Although the extensions .xml and .xht will both work for XHTML + MathML web pages, we recommend saving XHTML + MathML files with the .xht extension because it's more specific and less likely to confuse your browser and other software on your computer. However, be aware that if you use .xht, you will be unable to edit the file in Dreamweaver in Design or Split views unless you make a few changes. To edit XHT files "normally", follow these steps (note that these are Windows-specific instructions, and the files below may not work on Macintosh computers):

1. Locate the file extensions.txt. The default location for this file is
   C:\Documents and Settings\{username}\Application Data\Macromedia\Dreamweaver MX 2004\Configuration
2. Open this file in Notepad. The first list of file extensions applies to All Documents. The second list applies to HTML Documents. The end of the list reads, "...HTC,XHTML:HTML Documents". Add a new entry to the end of the list before the colon, so that the end of the list now reads: HTC,XHTML,XHT:HTML Documents. Save and close the file.
3. Download these 3 files, and save them in the folders indicated. NOTE: You will get a warning message asking if you want to replace the existing file with the new file. You need to answer "Yes", but if you want to be safe, you can first back up the existing file by re-naming it. For example, rename documenttypes.xml to olddocumenttypes.xml or documenttypes-old.xml.
   1. documenttypes.xml. Right-click, "Save Link As..." or "Save Target As...", then save it here:
      C:\Program Files\Macromedia\Dreamweaver MX 2004\Configuration\Strings
   2. Default.xht. Save this file in the folder
      C:\Program Files\Macromedia\Dreamweaver MX 2004\Configuration\DocumentTypes\NewDocuments
   3. MMDocumentTypes.xml. Save this file in the folder
      C:\Program Files\Macromedia\Dreamweaver MX 2004\Configuration\DocumentTypes
   4. If you have installed Dreamweaver to a folder other than the default folder, the folders to which you save the above files will be different.
4. If you follow the steps above, you will be able to edit XHT files in Default, Split, or Code view. In addition, there will be a new entry on the New Document dialog that you can use to create new XHTML + MathML documents. This will create a new document with the required processing instructions and additional statements already installed:

NOTE: Performing the steps in item 3 above won't add "XHTML + MathML" as a "Create New" item on the Dreamweaver welcome screen. In order to create a new XHTML + MathML document, you must click "More" on the welcome screen, which will bring up the New Document dialog you see above.

Inserting inline equations into a web page

We will discuss inserting inline equations before we consider display equations. An inline equation is an equation that flows with the text of a paragraph, and looks and acts like part of the paragraph. A display equation is an equation which is on a line by itself, usually centered. They are sometimes numbered. In web documents using MathML, inserting inline equations is easier than inserting display equations.

To insert an inline equation into your document:

Note: If you will be using our sample document, go ahead and begin the document on your own, up to the point where we need to insert our first equation. This will be after the word "form" in the first sentence.

1. In MathType, create the equation y = ax² + bx + c. We need to select a translator before we go on. (We'll use MathType for this equation. We discuss WebEQ below.)
2. In MathType's Preferences menu, click Translators.
3. In the Translators dialog, there are 8 translators to choose from. We won't go into the differences between the translators here. The one you should choose is "MathML 2.0 (namespace attr)". Notice there are two check boxes below the word "File". Check these as well. Click OK.
   
4. Since this is an inline equation, we need to set the Inline Equation property in MathType. Select Format > Inline Equation.
5. MathType performs all translation operations when you copy an equation to the clipboard. You've already created the equation, so select it either by dragging the mouse over the equation or by choosing Edit > Select All, and copy it to the clipboard (Edit > Copy).
6. When MathType translates an equation, it will verify the translation with a Status Bar message. If there are any errors in the translation, it will show an error dialog.
   
7. In Dreamweaver, make sure your cursor is in the document where you want the equation to go, then paste the equation. Important: You must paste the equation into Code View (or into the Code section of Split View).
   
8. Note the section of the MathML markup beginning with the tag <annotation encoding='MathType-MTEF'>. This is not MathML. It is MathType's own internal representation of the equation, and is optional. By including it, you allow readers to copy equations from your web pages and re-use them in documents of their own. If your readers are using IE + MathPlayer, they can open the equation in MathType simply by clicking the right mouse button and choosing the "Open with MathType" command.

Using WebEQ as your MathML editor

For most of this tutorial we'll be using MathType to create the MathML for our web page. If you'll be using WebEQ as your MathML authoring tool, there are some things you'll need to keep in mind.

1. Make sure WebEQ's MathML Export Preferences are set. The two preferences that matter the most are "Markup type", which should be set to "Presentation markup", and "Include namespace declaration", which should be checked. "Use namespace prefix" should be unchecked. These last two preferences should be reversed if authoring a web page for IE + MathPlayer only. Since we're authoring a page to be readable in both Netscape and IE + MathPlayer, we need it set this way:
   
   You may want to check "Set as default clipboard format" as well.
2. If the equation you are copying will be a display equation, click the <math> tag in the MathML ancestry. Select Properties > Layout Properties. In the Layout Properties dialog, under "Layout in Display Style", select "true". Click Done.
3. To copy the equation as MathML, select the equation by clicking the <math> tag in the MathML ancestry, then copy to the clipboard. If you selected the default format above, a simple copy will do. It's a good idea though, to always select Copy Special from the Edit menu. If you do that, and choose Copy As MathML, you'll get a chance to verify your copy preferences, as shown in the screen shot to the right above.
4. WebEQ doesn't use application-specific markup (like MathType's MTEF, discussed above). You can copy any MathML equation and paste it into WebEQ for editing or re-use.

Inserting display equations into a web page

The only reason MathML display equations are more difficult to insert than MathML inline equations is because of the center alignment and the equation numbers that are sometimes included. There are basically three methods of center-aligning an equation:

• Inserting the equation into a paragraph of its own, with center-alignment on the paragraph.
• Inserting the equation into a table, with center-alignment applied to the table cell containing the equation.
• Using a pure-CSS approach

The last method has the disadvantage that it's more difficult to understand if you don't know CSS, but has the advantage that it produces a more "accessible" page, in terms of being able to be more easily read by screen-reading software, and navigable in a pure-text browser. This is the only method we will discuss in this tutorial.

To insert a CSS-centered display equation into your document:

1. Either insert the applicable styles into the head of your document or into an external style sheet. We will use an external style sheet with these styles added:

div.pos {
width:100%;
margin-bottom:-18pt;
} /* full screen width */

p.dispeq {text-align:center} /* aligns to center of the page */

2. To insert the display equation, create a <div> with a paragraph inside, assigning the above styles to them:

<div class="pos">
  <p class="dispeq"></p>
  <br />
</div>

3. To insert the equation, paste it inside the paragraph, making sure to de-select the Inline Equation property in MathType (Format > Inline Equation).
4. If you're working with our sample document, continue typing and inserting equations until it looks similar to the sample. Be sure to use an .xht (preferred) or .xml extension when you save the document, since we're authoring a "universal" document (i.e., displayable in Netscape and IE + MathPlayer).

Actually, we'd like this last equation to be numbered so we can refer to it in the document's text. The next section will cover numbering.

Numbered display equations

You don't necessarily need to number every display equation in your document, but if you need to refer to a display equation in your document's text, the best way to do it is to number the equation.

To insert a numbered display equation using CSS:

1. To add a numbered equation, we follow exactly the same steps as we did in the section above, but we need to add one more style and one more line to our code.
2. Add this style:

p.right-number {
float:right;
margin-top:-28pt;
} /* floats content to rhs, and doesn't affect the
other <p> tag */

3. Add this line inside the <div> between the <p> and <br> tags:

<p class="right-number"><a name="eqn11" id="eqn11"></a>equation 1.1</p>

4. Go ahead and add the next paragraph to the document, making sure your new paragraph begins after the </div> that contains your equation. Now your document should look like this. Notice that our sample document doesn't use MathML when styled text will do, as in "x = –2 when y = 0". Whether or not this is a good idea will depend on your document and your readers. In cases where the math won't need to be interpreted by a computer algebra system or converted to content MathML markup, using styled text is a good idea because it produces less code, making a smaller (and faster-loading) document.

Creating a snippet for numbered display equations:

Dreamweaver lets you save often-used chunks of code as a "snippet". Since we will be inserting several numbered display equations, both in this document and in the future, creating a snippet will be a huge time saver. You can use the same snippet for an unnumbered display equation, or you can create a separate one -- just don't include an equation number when you use it.

1. In the Dreamweaver Code panel group, make sure the Snippets tab is showing. Click on the New Snippet icon.
2. In the Snippet dialog, enter the information below. Click OK.

3. For the next numbered display equation you need to insert, all you need to do is to go to the Snippet tab on the Code panel group, find the snippet you just saved. and either double-click it (Windows) or drag it to where you want it in your document (Win or Mac).
4. To enter equations into this code snippet, paste the MathML code block immediately prior to the first </p> tag. Enter the equation number (if any) immediately prior to the second </p> tag.
5. Make sure the referenced styles are included either in an external style sheet or in the head of the document.

Creating and editing a MathML tag library

As good as MathType and WebEQ are at creating MathML markup, there is no MathML authoring tool that can accurately guess 100% of the time exactly how you want your finished page to look. For this reason, you will no doubt have to manually add or edit MathML attributes at one time or another. Dreamweaver has built-in "tag libraries" for most of the markup languages you will be likely to use -- HTML, ASP, PSP, and others -- but it doesn't include a tag library for MathML. A tag library is helpful because it helps maintain proper syntax, and knows which attributes are valid with each element.

You can create or edit a Dreamweaver Tag Library by selecting Edit > Tag Libraries. We have created a MathML Tag Library that you can download and use with Dreamweaver by following these steps (Windows only):

1. Download the tag library (mathmltags.zip).
2. The file mathmltags.zip contains one folder and one file. Extract the zip file so that the folder "mathml tags" and the file "MathMLTagLibraryInfo.txt" are placed into the folder
   C:\Documents and Settings\{username}\Application Data\Macromedia\Dreamweaver MX 2004\Configuration\TagLibraries.
   
   Note: If the "Application Data" folder isn't visible, you may need to adjust your view settings to show hidden files (Control Panel > Folder Options > View > Hidden files and folders > Show hidden files and folders).
    
3. Also in the \Configuration\TagLibraries folder is a file named "TagLibraries.vtm". This file contains information about all of Dreamweaver's tag libraries. Open this file in Notepad or another suitable text editor. Open the file "MathMLTagLibraryInfo.txt" (from step 2 above). Copy the entire contents of this file and paste into the contents of TagLibraries.vtm. The pasted data should go at the end of TagLibraries.vtm, immediately above the </taglibraries> tag. Save and close the file TagLibraries.vtm.
4. When you re-start Dreamweaver, your MathML Tag Library should now appear at the bottom of the list of Tag Libraries when you open the Tag Libraries dialog, but you don't need to open the dialog in order to use the library.
5. To use the MathML Tag Library, simply enter MathML elements or attributes into the Code view of your document. For example, if we have an existing equation y = 2x, and we want the 2x to be blue, we could "wrap" an <mstyle> around the 2x, and apply an attribute of mathcolor='0000FF' to the <mstyle>:
   1. Select the elements containing "2x". Click the right mouse button and choose "Insert Tag":
      
   2. When the Tag Chooser opens, click on "MathML Tags" and "mstyle". Click Insert.
      
   3. Click just before the closing bracket on the <mstyle> tag and press the spacebar. The attribute dropdown box appears. Choose mathcolor, either by highlighting it and pressing Enter, or by double-clicking it with the mouse. From the color palette that pops up, choose the color you want.
      

Converting all the equations in a Word document to MathML

If you have an existing document in Microsoft Word that you are planning to put on the web, one thing you should consider is using the Export to MathPage feature in MathType 5. If you would rather do the HTML editing yourself, there is still an attractive feature available in Word's MathType menu. By using the Export Equations feature, you can convert all the equations in your Word document into MathML for use in your web page. Refer to Tutorial 18 in the MathType 5 manual for full instructions.

We hope this tutorial has been useful to you. If you would like to see similar tutorials in the future, or have suggestions for improving this tutorial, please e-mail our Director of Training, Bob Mathews.