Creating techexplorer Documents

techexplorer supports a large subset of TeX, LaTeX, and AMS-LaTeX, as well as MathML. In this section we discuss the markup you use to create documents. In the Compatibility section we describe how techexplorer compares to the full markup supported by these languages.

Overview

techexplorer supports a large subset of TeX, LaTeX, and MathML. It adds features for hypertext, multimedia, pop-up menus, and other extensions so that you can produce sophisticated electronic scientific and technical documents for Internet distribution.

Once you have installed the techexplorer plug-in, you will be able to view a number of examples directly. These are indicated below by

This is not active, but look for these in the text.

in the text.

You can determine if techexplorer is installed by choosing About Plug-ins from the Netscape Navigator Help menu item. Alternatively, click the following button to determine whether the Introductory Edition or the Professional Edition is installed. (This test may not work in Microsoft Internet Explorer.)

We do not review the definitions of common TeX and LaTeX features; refer to your TeX and LaTeX documentation for details. Excellent sources on the web for information about TeX and LaTeX are the The TeX Users Group and the American Mathematical Society.

We also do not review the definitions of the MathML markup elements. Detailed descriptions of these elements can be found in the Mathematical Markup Language (MathML) 1.0 Specification.

Guidelines for effective techexplorer documents

When you create a techexplorer document, you should use an editor that can save your file in plain text. That is, if you use a word processor, make sure that you choose to save the file in ASCII format.

In this release of techexplorer, very long documents may not format correctly and, even if they do, may process very slowly. You should break longer documents into smaller ones and then add hypertext links and hierarchical document support. In fact, this is a good general practice for Internet document distribution, since users of your documents can quickly receive and view document sections on demand. See Cross References for some tips on adding hyperlinks and references between the smaller documents.

You should build flexibility into your techexplorer documents so that they can display on a variety of users' screens. Avoid thinking in terms of a fixed page width. Also, one document is one web page and so control sequences that do page ejects, set running titles, and do similar page-oriented things are usually accepted by techexplorer but have no effect. In later releases, techexplorer may interpret author-supplied style parameters when rendering for the screen and printed page.

And finally, as you create techexplorer documents, be sure that all contained document names mentioned are absolute (for example: http://...) or relative to the current document (for example: \includegraphics{mylogo.bmp}). techexplorer and your browser will work together to find the files when your viewers request them.

Setting window mode or full-screen mode

techexplorer can display a mathematical or scientific expression within a window in the display of an HTML document. It also can show an entire document in the browser display area.

When you install the techexplorer plug-in, it is automatically registered with your browser and the operating system to handle Web documents with the following MIME types and corresponding file extensions:

MIME type Corresponding File Extensions
application/x-tex *.tex, *.bbl
application/x-latex *.latex, *.ltx
application/x-techexplorer *.tcx
text/mathml *.mml

(The MIME type is a standard description of the type of content in the document.)

Notes:

  1. Very important! Netscape Navigator uses the file extension for local files and the MIME type for files retrieved from the web. Some of the file extensions/MIME types registered by techexplorer may not work for files from the web until the web server is properly configured. This means that the web server must be configured to associate the MIME type with the file extension. We describe how to do this for the most popular web servers in Installing and configuring techexplorer.
  2. On most platforms the above MIME type and extension registrations are done automatically for the browser. See Installing and Configuring techexplorer for important remarks about when you might need to manually register this information.
  3. The ActiveX control is identified by a unique ID when inserted into a document using the <OBJECT> tag.

For full-screen mode, your browser uses the techexplorer plug-in when it is asked to link to a file with the above file extensions or MIME types. The techexplorer plug-in itself can link to other documents on the network in this way, even if they are not techexplorer documents.

When the Professional Edition of techexplorer is installed you have a choice of using either the plug-in or ActiveX control to display a document in Window mode when using Internet Explorer.

To set a fixed window size for the display of a document containing mathematical or scientific expressions using the techexplorer plug-in, use the EMBED HTML tag to define the size of the window and the source file containing the techexplorer expression or document to be displayed. For example:

<EMBED SRC="math.tex" WIDTH=500 HEIGHT=200>

Or to embed a MathML file:

<EMBED SRC="math.mml" WIDTH=500 HEIGHT=75>

producing:

The quadratic formula

The SRC attribute gives the relative or absolute URL (location) of the file to be displayed. The WIDTH and HEIGHT attributes assert the desired size of the plug-in window, in pixels.

Note that the SRC attribute name is used to tell the web browser where to obtain the source markup. If you are using Netscape Navigator 3.0 or a compatible browser, you can also specify the TeX or MathML markup directly inline. The code:

<EMBED TYPE="application/x-techexplorer"
TEXDATA="$$\pmatrix{2&\sqrt{3}&\alpha\cr\beta&4&5}^T$$"
HEIGHT=100 WIDTH=200>

produces the following results:

INLINE TEX

Or using MathML content tags:

<EMBED TYPE="text/mathml"
 MMLDATA="<math><apply><transpose/><matrix>
   <matrixrow>
     <cn>2</cn><apply><root/><cn>3</cn></apply><ci>a</ci>
   </matrixrow>
   <matrixrow>
     <ci>&beta;</ci><cn>4</cn><cn>5</cn>
   </matrixrow>
 </matrix></apply></math>"
 HEIGHT=75 WIDTH=200>

you can obtain:

A matrix transpose using MathML content tags

The <OBJECT> tag is used to embed an instance of the techexplorer ActiveX control in an HTML document and will only work in Internet Explorer. For example: 

<OBJECT ID="matrix" HEIGHT=100 WIDTH=200
    CLASSID="clsid:5AFAB315-AD87-11D3-98BB-002035EFB1A4">
    <PARAM NAME="AutoSize" VALUE=TRUE>
    <PARAM NAME="DataType" VALUE="1">
    <PARAM NAME="Data" VALUE="
    <math>
        <mrow>
            <mi> x </mi>
            <mover>
                <mo> → </mo>
                <mtext> maps to </mtext>
            </mover>
            <mi> </mi>
        </mrow>
    </math>">          
</OBJECT>

produces:
A maps to using MathML presentation tags

The CLASSID parameter is used to specify the class identifier for the techexplorer ActiveX control (always clsid:5AFAB315-AD87-11D3-98BB-002035EFB1A4). The Data parameter gives the URL or the actual data of the document to be displayed. The DataType parameter specifies the value of the Data parameter, possible values include:

The AutoSize parameter can be used to indicate that techexplorer should only allow enough space for the displayed expression.

When creating techexplorer content that can be scripted by both Netscape and Internet Explorer, the <EMBED> tag must be wrapped by an <OBJECT> tag. This way the ActiveX control will be used for the Internet Explorer web browser and the plug-in will be used for Netscape. For example: 

<OBJECT ID="matrix" HEIGHT=100 WIDTH=200
    CLASSID="clsid:5AFAB315-AD87-11D3-98BB-002035EFB1A4">
        <PARAM NAME="AutoSize" VALUE=TRUE>
        <PARAM NAME="DataType" VALUE="1">
        <PARAM NAME="Data" VALUE="<math> ... </math>"> 
            <EMBED TYPE="text/mathml"
                MMLDATA="<math> ... </math>"
                HEIGHT=100 WIDTH=200 NAME="matrix">
            </EMBED>           
</OBJECT>

There are just some things you cannot do very well with any browser plug-in today. These include:

For these reasons, we recommend that you use techexplorer to display the full text of your document if there is math embedded within paragraphs or there are more than a few display math expressions. That is, do not use EMBED but rather link directly to a .tex or .tcx file for techexplorer to display.

Note that techexplorer draws opaquely on the browser window. This means that if you are using a background image or color in your HTML page, the techexplorer-drawn math expression might look strange because it is drawn on a white background by default. However, if you use \pagecolor to set the background color of the techexplorer window, your document may look better. Note that you can also use \backgroundimage to tile the techexplorer window with an image, but it probably will not align correctly with your HTML page's background image.

The feature described is only available in the Professional Edition of techexplorer.

By using the techexplorer ActiveX control in Internet Explorer and scripting in Netscape you can create web pages that automatically determine the alignment and correct size of techexplorer rendered mathematical equations. As a result you can author web pages that dynamically set each techexplorer window's height and width based on screen resolution and current font size.

Click to see an HTML page with correctly sized techexplorer windows.

Document structure

We suggest you follow the LaTeX 2.09 or LaTeX 2e recommended document structure for all your files. Here is an example for LaTeX 2.09: 

\documentstyle{article}
% use \input to include files here
\begin{document}
% document content goes here
\end{document}

Here is the corresponding example for LaTeX 2e:

\documentclass{article}
% use \input to include files here
\begin{document}
% document content goes here
\end{document}

The standard reference for LaTeX is LaTeX: A Document Preparation System by Leslie Lamport, copyright 1994, 1983 by Addison-Wesley Publishing Company, Inc.

techexplorer tends to be very forgiving in what it accepts and renders. Style parameters that are not handled currently are silently accepted and not displayed. However control sequences and symbols that are not understood are displayed in red so that you can try to decipher the original meaning.

Even though it may ignore them now, in the future techexplorer will likely look closely at the \documentstyle, \documentclass, and \package commands so that it can emulate a range of styles and packages.

Note that while it may appear to be optional, the \begin{document} command is necessary if you use \maketitle.

The techexplorer style file

Although the Professional Edition of techexplorer allows you to print selected parts of documents, you may wish to use "real LaTeX" to print your documents and use techexplorer to view them on screen. For this purpose, we have provided a LaTeX style file that provides definitions for almost all commands added by techexplorer. See the information contained in this file for information on its use. Note that current restrictions include:

Including TeX and LaTeX symbols

These symbols are obtained from the symbol font set you are using. A symbol that is not available is displayed in red in the document, as in \hookrightarrow. Under Microsoft Windows, techexplorer provides fixed-size, fixed-color bitmaps for several of the most commonly used symbols that are missing from the standard Microsoft Windows Symbol and WingDings fonts. Fonts containing all needed symbols are provided for UNIX versions of techexplorer and the Professional Edition.

Note that the techexplorer symbol font set shipped with the Professional Edition contains all the core LaTeX and AMS symbols. We do not list most of the AMS symbols below, but see the compatibility section to see a full list of supported symbols.

Click to see techexplorer render symbols.

Greek lowercase

\alpha \beta \chi \delta \epsilon \eta \gamma \iota \kappa \lambda \mu \nu \omega \phi \pi \psi \rho \sigma \tau \theta \upsilon \varepsilon \varphi \varpi \varrho \varsigma \vartheta \xi \zeta

Greek uppercase

\Delta \Gamma \Lambda \Omega \Phi \Pi \Psi \Sigma \Theta \Upsilon \Xi

Arrow symbols

\Downarrow \Leftarrow \Leftrightarrow \Longleftarrow \Longleftrightarrow \Longrightarrow \Rightarrow \Uparrow \Updownarrow \downarrow \hookleftarrow \hookrightarrow \leadsto \leftarrow \leftharpoondown \leftharpoonup \leftrightarrow \longleftarrow \longleftrightarrow \longmapsto \longrightarrow \mapsto \nearrow \nwarrow \rightarrow \rightharpoondown \rightharpoonup \rightleftharpoons \searrow \swarrow \uparrow \updownarrow

Binary Operation symbols

\amalg \ast \bigcirc \bigtriangledown \bigtriangleup \bullet \cap \cdot \circ \cup \dagger \ddagger \diamond \div \land \lor \lhd \mp \odot \ominus \oplus \oslash \otimes \pm \rhd \setminus \sqcap \sqcup \star \times \triangleleft \triangleright \unlhd \unrhd \uplus \vee \wedge \wr

Relation symbols

\approx \asymp \bowtie \cong \dashv \doteq \equiv \frown \geq \gg \in \Join \leq \ll \mid \models \neq \ni \parallel \perp \prec \preceq \propto \sim \simeq \smile \sqsubset \sqsubseteq \sqsupset \sqsupseteq \subset \subseteq \succ \succeq \supset \supseteq \vdash

Miscellaneous symbols

\"A \"E \"I \"O \"U \"a \"e \"i \"o \"u \AA \AE \Box \Diamond \Im \O \OE \P \Re \S \Vert\aa \ae \aleph \angle \backslash \beth \bot \cents \clubsuit \copyright \dag \daleth \ddag \diamondsuit \digamma \ell \emptyset \exists \flat \forall \gimel \hbar \heartsuit \iff \imath \impliedby \implies \infty \jmath \langle \lceil \ldots \lfloor \lvert \lVert \mho \nabla \natural \neg \o \oe \partial \pounds \prime \rangle \rceil \registered \rfloor \rvert \rVert \sharp \spadesuit \ss \surd \thorn \Thorn \THORN \top \trademark \triangle \varkappa \varnothing \vert \wp

Variable-sized symbols

\bigcap \bigcup \bigodot \bigoplus \bigotimes \bigsqcup \biguplus \bigvee \bigwedge \coprod \int \oint \prod \sum

AMS Greek and Hebrew

\digamma \varkappa \beth \daleth \gimel

Including hypertext links and multimedia

Links are "hot spots" in your document that cause something to happen when you click on them---like jumping to another page, running some application, and so on. When the cursor passes over a link, it turns into the familiar "pointing hand", indicating a hot spot. In techexplorer, a visible link is executed when you click the left mouse button when the mouse cursor is over the link. Links are not underlined in techexplorer, because any text can be contained in the hot spot, even a complicated mathematical expression. By default, links are displayed in blue, but you can change this in the Color options page.

Links are also used with pop-up menus and can be executed in response to user actions in dialog boxes created by \inputboxLink and \yesNoLink.

Hypertext Links

Use \docLink to jump to another network document and \labelLink to jump to another location within the same document.

\docLink[frameName]{documentURL}[label]{textToDisplay}

\labelLink{label}{textToDisplay}

\label{label}

\index{indexExpression}

Hierarchical document support

A techexplorer document itself may contain information that places itself within a hierarchy of network documents. For example, the displayed document might be a section within a chapter within a series of textbooks.

A hierarchy within a book.

In this example, the above topic for Sections 1.1, 1.2, and 1.3 would be the Chapter 1 document. The previous topic for Section 1.2 would be Section 1.1, and for Section 1.3 it would be Section 1.2. The next topic for Section 1.1 would be Section 1.2, and for Section 1.2 it would be Section 1.3. No other "topics" are defined for any of the documents.

You link to one of these topics by right clicking on an empty area of the plug-in window and then choosing Above topic, Previous topic, or Next topic from the pop-up menu

Default document pop-up menu

or by using the pseudo:aboveTopic, pseudo:nextTopic, or pseudo:previousTopic as the documentURL within \docLink. For example,

Click \docLink{pseudo:nextTopic}{here} to view the next section.

\aboveTopic{topicName}

\nextTopic{topicName}

\previousTopic{topicName}

Cross references

Rather than working with a single large document, techexplorer is optimized to work with a series of hyperlinked documents that move quickly to your desktop and onto your screen. When a reference is given to an object in another document, techexplorer needs to know the document location. Use \docLink to jump to another document and \labelLink to jump to another location within the same document.

Current Restriction: In this release, techexplorer does not handle automatic numbering of sections, figures, and so on. The \ref, \eqref, and \pageref control sequences always display as "???". Note, however, that if the reference is in the same document, clicking on the "???" scrolls the page to referenced location.

We suggest that you now manually label these items and create macros for expressions containing labels and referencing labels. These macros can be changed later if numbering support is enabled. For example, 

\def\Section#1#2#3{\section{#1\quad#2}\label{#3}}
\def\SectionRef#1#2#3{\docLink{#2}(#3){\S~#1}}

The \Section macro accepts a section number (#1), a section title (#2), and a label (#3). It creates a standard heading with a label. The \SectionRef macro accepts a section number (#1), the name of the document containing the section (#2), and the label of the section within the document (#3).

Here are some additional, similar macros that you may find useful in converting larger files to smaller, cross referenced ones: 

\def\refGeneral#1#2#3#4{\docLink{#3.tex}(#1){#4 #2}}%ref label, number, file
\def\refCorollary#1#2#3{\refGeneral{#1}{#2}{#3}{Corollary}}
\def\refDefinition#1#2#3{\refGeneral{#1}{#2}{#3}{Definition}}
\def\refLemma#1#2#3{\refGeneral{#1}{#2}{#3}{Lemma}}
\def\refProposition#1#2#3{\refGeneral{#1}{#2}{#3}{Proposition}}
\def\refRemark#1#2#3{\refGeneral{#1}{#2}{#3}{Remark}}
\def\refSection#1#2#3{\refGeneral{#1}{#2}{#3}{\S}}
\def\refTheorem#1#2#3{\refGeneral{#1}{#2}{#3}{Theorem}}

You may find it helpful to create versions of these macros that work with local references (within the same file) and \labelLink.

Multimedia

Audio and video are presently only available for Microsoft Windows and Macintosh versions of techexplorer. These features are only available if your computer provides the necessary hardware support.

\audioLink{audioFileName}{textToDisplay}

\backgroundimage{imageFileName}

\backgroundsound{audioFileName}
\includeaudio{audioFileName}

\includegraphics[lowerLeft][upperRight]{imageFileName}
\includegraphics*[lowerLeft][upperRight]{imageFileName}

\includevideo{autostart}{alternateText}{videoFileName}

\videoLink{videoFileName}{textToDisplay}

Other link types

\altLink{secondDisplay}{firstDisplay}

\appLink{commandLine}{textToDisplay}

\inputboxLink[responseLink]{controlSequence}{inputboxText} {dialogBoxDescription}{dialogBoxCaption}{textToDisplay}

\popupLink{popupText}{popupCaption}{textToDisplay}

\yesNoLink[responseLink]{controlSequence} {dialogBoxQuestion}{dialogBoxCaption}{textToDisplay}

Including MathML within a LaTeX file

techexplorer allows you to include MathML expressions in HTML web pages and in LaTeX source files. The section on Setting window mode or full-screen mode describes how to incorporate MathML expressions in HTML web pages, using either external MathML files, or inline MathML expressions. This section describes how to accomplish the same results using LaTeX source files.

\includeMathML{mmlFileName}

\begin{MathML}
\end{MathML}

Pop-up menus

techexplorer allows you to define and use nested pop-up menus (sometimes called context menus). A pop-up menu appears when you click the alternate mouse button which is, for most users, the right mouse button. For this reason, we refer to clicking the alternate mouse button as "right-clicking." Every techexplorer document has a default pop-up menu. This menu is fixed and you, as the document author, cannot modify it. Other menus may appear if you right-click over elements of the text. We'll now show you how you can define and attach pop-up menus to any element of the text. You also might want to look at the example of user-defined pop-up menus.

\newmenu{menuName}{menuDefinition}

\usemenu{menuName}{menuScope}}

Including colors

techexplorer provides the following control sequences for adding color to a document: \backgroundcolor, \color, \colorbox, \colorbuttonbox, \fcolorbox, \gradientbox, \pagecolor, \rgb, and \textcolor. All except \gradientbox, \rgb and \colorbuttonbox are defined by LaTeX 2e. The following color names can be used when needed within these control sequences:

black, blue,cyan, darkgray, gray, green,
lightgray, magenta, red, white, yellow,
maroon, olive, navy, purple, teal, silver,
lime, fuchsia, and aqua.

Some of these colors are not available in LaTeX 2e. Use the Colors options page to change the default colors of document elements.

If you have already installed techexplorer, you can see examples of these color commands.

Click to see techexplorer handle colors.

Current restriction: The LaTeX 2e feature \definecolor is not supported.

\color{colorName}

\colorbox{colorName}{text}

\colorbuttonbox[invert ]{colorName}{text}

\fcolorbox{lineColorName}{backgroundColorName}{text}

\gradientbox[v]{startColorName}{endColorName}{text}

\backgroundcolor{colorName}
\pagecolor{colorName}

\rgb{red}{green}{blue}

\textcolor{colorName}{text}

Conditional evaluation

techexplorer has very basic support for the TeX \if...\else...\fi facility. The \newif construct is currently ignored, as is \techexplorertrue and \techexplorerfalse. This allows you to add

\newif\iftechexplorer \techexplorerfalse

to your TeX document and include or exclude techexplorer markup for processing by using

\iftechexplorer blah blah blah \else nah nah nah\fi

The first condition will be processed only by techexplorer and the second only by real TeX (assuming you have done the \newif above).

The \ifmmode construct is available to allow you to selectively do things based on whether or not you are in math mode. For example, "x squared" will be properly displayed by \xsq independent of whether it is used in a math environment.

\def\xsq{\ifmmode x^2\else $x^2$\fi}

The LaTeX style file for techexplorer includes \newif\iftechexplorer \techexplorerfalse for you, so there is no need to enter it again.

Features and their versions

Documents, input files, add-ins, and scripts may wish to indicate that they provide features that documents need. One example is the version of techexplorer itself: you may want to indicate to your readers that at least a certain version of techexplorer is needed to properly handle your document. The \ProvidesFeature and \RequiresFeature commands allow you to define features and then indicate special markup to be inserted into your document if the feature is not present or is present in too old a version.

Note that features may be defined via the scripting or add-in interface and not just via \ProvidesFeature.

\ProvidesFeature{featureName}{majorVersion}{minorVersion}

\RequiresFeature{featureName}{majorVersion}{minorVersion} {missingFeatureText}{oldVersionText}

Including other elements

Directory lists

\begin{dirlist}[format]... \end{dirlist}

Bibliographies

\bibfile{bibliographyFileName}

Button boxes

\buttonbox[invert]{text}
\dialogbox[invert]{text}

Footnotes

\footnote{footnoteText}

Input boxes

\inputbox[width]{controlSequence}{initialContents}

Document contents

\inputonce{documentName}

List of figures

\listoffigures

List of tables

\listoftables

TrueType fonts

\TrueTypeTextFont{fontName}

Click here to to view the previous section. Click here to to view the next section.

IBM techexplorer Hypermedia Browser is a trademark of the IBM Corporation.
Send comments and questions to techexpl@us.ibm.com.
Visit the official techexplorer home page at http://www.software.ibm.com/techexplorer/.