Creating MathML Web Sites

When publishing web pages, it is good practice to make is as easy as possible for readers to view your content. With MathML web pages, this is a matter of clearly informing your readers about any browser setup they may need to do, and configuring your web server to minimize interoperability problems.

• Web Server Configuration
• Gateway Pages
• Server-side Content Negotiation
  • The User Agent Field
  • Content Negotiation with Apache
  • Content Negotiation with Microsoft Internet Information Server
  • Content Negotiation via Scripts

Web Server Configuration

While support for MathML and interoperability between browsers has been steadily improving, several issues remain for publishers of web sites with MathML content. MathPlayer is required for viewing MathML pages with Windows Internet Explorer, and while MathPlayer is distributed with some new computers, most Windows Internet Explorer users must install MathPlayer separately. Firefox users may need to install extra math fonts on their computers in order to view MathML pages properly. Moreover, in many situations, content providers may want to hide these considerations from a reader and automatically tailor content to his or her browser's capabilities.

The Gateway Page is a good way of informing readers about browser requirements. 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.

The technique of sending different content to different readers based on their browser configuration is called Server-side Content Negotiation. Content negotiation is a very powerful technique, but it generally requires advanced web programming skills, and the ability to modify your web server's configuration. The most common use of content negotiation with MathML content is to automatically direct readers without MathML capable browsers to either a browser setup page, or content in an alternative format.

Gateway Pages

When publishing MathML web pages, you need to inform readers about browser requirements, and provide set up instructions for those that need them. A good way to do this is to create a centralized gateway page. A gateway page should tell Internet Explorer users how to get MathPlayer if they need it, typically by linking to MathPlayer downloads as described in the MathPlayer Distribution Options below. Similarly, a gateway page should inform Firefox users about how to obtain and install the fonts required for MathML display in their browsers. See Fonts for MathML-enabled Mozilla for further information. For users without MathML-capable browsers, a gateway may encourage them to use a different browser or provide links to content in an alternative format.

Some content providers choose to link back to the gateway page from all pages with MathML content. This is a good plan when many readers will enter your site by following links directly to content pages from search engines, etc. In other cases, for example when content is password protected, a content provider may be able to dependably funnel readers through the gateway page without linking directly to it from pages with MathML content.

A basic version of a gateway page can consist of plain text and links. More sophisticated gateway pages tailor their contents to the viewer's browser, using JavaScript. For example, the following JavaScript code indicates how you might check if a reader is using Internet Explorer and already has MathPlayer installed:

function checkForMathPlayer() {
  // first test platform, as the MathPlayer-specific code only works in IE
  if( isIEWindows()) {
    // check browser version since MathPlayer 2 requires IE 6
    if (ieVersion() >= 6.0) {
      if (isMPInstalled()) {       
        var start = navigator.appVersion.indexOf("MathPlayer");
        if (start != -1) { 
          // notify reader their browser is properly set up
        }
        else {             
          // notify reader they need to upgrade to MathPlayer 2
        }
      }
      else {               
        // direct reader to MathPlayer installation page
      }
    }
    else { 
      // notify reader they need to upgrade IE 
    }
  }
  else { 
    // direct reader to information about other browsers 
  }
}

// returns True if MathPlayer is installed
function isMPInstalled()
{
  try {
    var oMP = new ActiveXObject("MathPlayer.Factory.1");
    return true;
  }
  catch(e) {
    return false;
  }
}

// returns True if running on any version of IE Windows
function isIEWindows()
{
  return( (navigator.appName=="Microsoft Internet Explorer") && 
    (navigator.appVersion.indexOf("Windows") != -1) );
}

// returns version of Internet Explorer
function ieVersion()
{
  var ieVer = 0;
  var start = navigator.appVersion.indexOf("MSIE "); 
  if (start != -1) { 
    ieVer = parseFloat(navigator.appVersion.substring(start+5)); 
  }
  return ieVer;
}

Server-side Content Negotiation

MathPlayer 2.1 can display MathML in both HTML and XHTML pages. However, the Firefox browsers only display MathML in XHTML pages. To further complicate matters, Firefox relies exclusively on the MIME type of a page to determine whether it is HTML or XHTML, whereas Internet Explorer also "sniffs" into the header of a document. To negotiate these interoperability pitfalls, it is best to set up your web server to ship your XHTML + MathML web pages with the MIME type

• 'application/xhtml+xml'

It is also acceptable to serve them as any of the following three types:

• 'text/xml' 
• 'text/xml; charset=utf-8',
• 'text/xml; charset=iso-8859-1'

However, use of these MIME types for XHTML has been deprecated, and are supported in MathPlayer by backward compatibility only. Documents served with these MIME types may not work with Netscape or Mozilla, unless you have also set up your page to use an XSL stylesheet. On some computer systems, they may also fail to be recognized by MathPlayer.

On most web servers, the MIME type is determined by the file suffix, so your pages may ship with the proper type if you name them ending in .xht or .xhtml (or .xml for the deprecated MIME types). However, you may need to modify your server configuration, especially if you have an older server, since older MIME type tables typically won't contain entries for XHTML. Note that MathPlayer requires the value for the Content-type field in the HTTP head to match one of the four values listed above exactly (ignoring case, but not whitespace) so care should be taken when modifying server configuration files, etc.

To specify a document encoding other than utf-8 or iso-8859-1, content providers will need to use one of the accepted methods of specifying this information in the document itself, e.g. adding an "encoding" attribute to the XML processing instruction that must begin an XML document. Also, due to Internet Explorer's sniffing algorithms for MIME type determination, MathPlayer processing will not take place if you append a charset to 'application/xhtml+xml'. For this MIME type, the encoding must be specified within the document to work properly.

The User Agent Field

For browsers that do not support XHTML + MathML, some content vendors may want to do server-side content negotiation. By examining the HTTP request sent by a browser, server-side logic can send back a page tailored to the browser's capabilities. For example, the server might send an XHTML + MathML page with MIME type application/xhtml+xml to recent Firefox and Internet Explorer browsers with MathPlayer installed, but redirect to an HTML page with equation images for all other browsers.

To facilitate server-side content negotiation, MathPlayer identifies itself in the USER_AGENT field of the HTTP request. In general, the format of the USER_AGENT string is 'product (comment) ...' as per RFCs 1945 and 2616 which define the HTTP 1.0 and 1.1 protocols. The comment part of the USER_AGENT string is a semicolon separated list in the case of Internet Explorer. When MathPlayer is installed, one item in the comment list will be "MathPlayer 2.1". For example, a typical USER_AGENT string for Internet Explorer with MathPlayer installed might be:

Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0; MathPlayer 2.1; .NET CLR 1.1.4322)

Future versions of MathPlayer will insert a string of the form "MathPlayer <major>.<minor>" into the USER_AGENT field, where <major> and <minor> denote the major and minor version numbers respectively.

Content Negotiation with Apache

Content providers using an Apache 2.0 or later web server might implement a simple server-side content negotiation scheme as follows. On the server, files containing XHTML+MathML could be identified by a .xht file extension. For Firefox browsers and Internet Explorer browsers with MathPlayer, the server should send these documents with MIME type application/xhtml+xml which the the default for an .xht extension. For all other browsers, the files will be served as text/html, which will allow them to at least partially render.

To achieve this, one can use the mod_rewrite Apache module. In the http.conf file for the server, mod_rewrite must be loaded. Then, in the relevant per server or per directory area of the configuration file, one could add the lines:

     RewriteEngine On
     RewriteCond %{HTTP_USER_AGENT} !MathPlayer 
     RewriteCond %{HTTP_USER_AGENT} !^Mozilla/5.*
     RewriteRule \.xht$  - [T=text/html,L] 

Content Negotiation with Microsoft Internet Information Server (IIS)

Content negotiation is slightly more involved for content providers using the Microsoft Internet Information Server. Serving content with different MIME types depending on the kind of browser making the request involves using an Internet Server Extension. Programmers can create their own extensions using Microsoft's ISAPI directly. Alternatively, there are many commercially available extensions that offer functionality similar to Apache's mod_rewrite module, and which can be used to do content negotiation as described above. Some examples of such server extensions are ISAPI_Rewrite 2.0 and PageXchanger for IIS.

Content Negotiation via Scripts

For content providers that are not willing or able to modify their server configuration, it is worth keeping in mind that it is also possible to do content negotiation using standard web technologies such as CGI, PHP, ASP and JSP. The HTTP request header is available to most standard web scripting technologies. Similarly, the ability to set the MIME type of the response generated by a script is almost always possible. Therefore, with most web scripting technologies, setting up content negotiation is relatively straightforward. However, since web programming is required, and because the use of scripts is generally much less efficient than modifying the server configuration as a whole, using scripts is probably not the best solution in general.