Using Baby TeX

Extremely brief introduction to TeX

If you are new to TeX, (rhymes with the word blecchhh) you are in for a treat to find out one of the most beautiful computer programs written by a very delightful person in the name of Donald Knuth. He is widely considered the father of computer science, the author of the Bible on programming and an accomplished organist. During the past few decades, he has been writing a series of books called the Art of Computer Programming, and having been frustrated by the inadequate typesetting technology, set aside a few years to develop a digital typesetting and font-design system during the seventies(!). The TeX predates Word or Framemaker by at least a decade, and today's font technology owes much to his Metafont. The system works on any self-respecting computer systems, the output completely platform independent and superior to any other competitors. It was picked up by mathematicians and physicists early on and has become the pen and pencil for much of the scientific discourse. And it is virtually free. Sounds too good to be true? Well, the price for casual users is that it is rather difficult to master, despite the beautiful manual written by Knuth himself with illustrations by Bibby (who is poorly imitated in the picture above).
Many attempts were made to sugar-coat TeX. One of the most widely used such macros is LaTeX, made by Leslie Lamport. On Mac OS X, several implementations of TeX and macros are available. While the original TeX output was in a format called dvi, it is more convenient to have the output in pdf format these days. The most popular version capable of doing it is teTeX which includes pdftex and pdflatex written by Han The Thanh, Petr Sojka, and Jiri Zlatuska. It is a big system but is available for free. iStorm assumes that you have installed this or at least a similarly capable TeX package which can output in pdf format. If you are going to use TeX seriously on OS X, a program called TeXShop provides an elegant graphic interface to edit, process and print beautiful TeX documents.

Why Baby TeX?

Then, why do we bother with yet another interface for TeX? Because it renders the mathematical equations in the most beautiful manner. Once you get used to typing the commands in text, most of you will agree that it is far superior to having to click-click-click....... in a typical Equation editor program. (After clicking, you will then have to spend some time ``tweaking" spaces here and there to have it look as good as a TeX output.) And we want the users of iStorm to exchange equations in their best forms. We named our module Baby TeX since we are acutely aware that we are just scratching the tip of an iceberg called TeX. We hope that the priests of TeX are not too much annoyed by it being used in this manner.

Installing the requisite TeX software

Here we will assume that you are going to install the freely available teTeX. The best way to do so is by an i-Installer program (named TeX-fat.dmg, is about 60 Mb!) created by Gerben Wierda, which you can download from here or its mirror . (Some details on TeX install on OS X can be found here .) When you run the i-Installer program, packages called TeX Foundation and TeX Programs should be chosen and installed for Baby TeX. Others ("Ghostscript" and possibly some others) are optional and you may need them for more serious TeX uses such as TeXShop. Keep the i-Installer program around as you may use it later to update or remove the packages without hassle.

The picture above shows you how i-installer program might look like. Note that it is NOT included as part of iStorm, and its latest version may look different from shown above. You may get i-installer for free from this link.

It is possible to use a different configuration of teTeX or even a completely different implementation of TeX as long as preferences are properly set.

Configuring Baby TeX

Here is what you need to do in the TeX panel of iStorm Preferences.



  • Engine (LaTeX) : This is the name of the binary which processes tex file with LaTeX. For teTeX implementation, it is called pdflatex. This is the preferred engine as LaTeX is one of the most popular macro packages and provides an easier user experience than TeX.
  • Engine (Alternative) : This is the name of alternative binary which processes tex file with different macro other than LaTeX. By default, it is texexec. This is to accommodate the users who may need to run TeX using ConTeXt macro package, which is a strong contender developed in the homeland of Vermeer.
  • Path : This is the path to the directory where both engines above are located. As of December 2002, if you had run i-Installer as recommended above to install teTeX, the path will look like the one in the picture and iStorm will initially place it as the default path. If your installation differs, you will have to modify it.
    • If you are already using TeXShop successfully, you must already have everything. You can easily find the necessary information for the three items above in TeXShop Preferences (in the TeXShop program) : they are listed under Path settings, TeX program, Latex program.
  • Flags : Most of you should know that unix applications expect flags to be set at the time the commands are issued. For example, our pdflatex engine should have its interaction mode set to "nonstopmode" to avoid it forcing iStorm to hang when a serious TeX error occurs. For pdflatex, you use
    -interaction nonstopmode mytexfile.tex
    or its equivalent if you are using something other than pdflatex. More user flags may be necessary if you are a TeXpert using some obscure options. Add those in the box following the example.

    • Using Baby TeX

    There are two ways to use Baby TeX. First, most convenient for expert users will be the in-line equation substitution mode. More casual users may want to use the Baby TeX window to compose and drag the equation onto the document. One can carry the source code attached to the graphics for others to modify. (See below)
    In-line substitution mode
    First, let us find out what we mean by in-line substitution. Open an iStorm document. Type something like : $$E = m c^2 $$ in the main document window.



    Then with the cursor still in the vicinity (say at the end of the expression or in the middle of the $$ ... $$ block), press Command-/ . You will observe that iStorm automatically detects the appropriate TeX commands and select it. After a brief moment, it will then replace the selection with an equation image generated by Baby TeX in the background.



    This automatic detection of TeX equation code works only with the following math delimiter pairs: 
    $ ... $
\( ... \)
\begin{math} ... \end{math}
    for the inline math, and 
    $$ ... $$
\[ ... \]
\begin{displaymath} ... \end{displaymath}
\begin{equation*} ... \end{equation*}
    for display math, and finally 
    \begin{eqnarray*} ... \end{eqnarray*}
    for multi-line equations.
    (* in some of these are necessary to suppress the equation numbering.)
    If you are using an alternative engine, note that delimiters other than $ and $$ may not be properly interpreted and the resulting image may not be what you want. We suggest using the standard LaTeX engine if you use in-line mode heavily. How does Baby TeX pick one if you have many of these pairs in the document? It uses the following heuristic rules: 1) First, it finds any of the delimiters closest to your current cursor position. 2) Then, it tries to find the relevant match nearby. 3) If it finds more than one possible candidate matches, it prefers the pairing which lies on the left side of your cursor than on the right side, unless your cursor is in-between. This relies on the likelihood that you would issue the command-/ after typing in the full TeX code enclosed with any of the above delimiters. Except for a few contrived trick situations, this would work most of the time. Once you figure out some obvious pitfalls to avoid, you will enjoy a good relationship with inline. One less reason to make a trip between the keyboard and the mouse .... If you need to use anything other than these common math delimiters, just manually select the code before issuing the command with Command-/ . If you manually select the block of code, Baby TeX goes through the following routine:
  • First, it tries to determined if the block is any of the valid math codes listed above. If so, it applies the appropriate algorithm to construct the tex commands before delivering it to the engine.
  • If it passes step 1), then Baby TeX uses the generic header and footer on the code. Unlike a math block, it will not try to outguess the size of the equation and will produce a box of height 4 inches. Depending on what you typed, the box may be too large or small. If you double click on the attached source or look into the Baby TeX input window, you will notice that it has appended the following two lines of code: 
    \setlength{\pdfpageheight}{4 in}
\setlength{\pdfpagewidth}{7 in}
  • You can modify the height and the width to appropriate sizes after examining the output. Now issue command-/ again on the modified code to get the right size.

    • A word of acknowledgement is in order.
    In developing the in-line substitution mode, one of the stumbling blocks we had to clear was to generate the equation pdf file with its size precisely determined around the given equation. We benefited from communication with Doug Rowland (dougrowland@mac.com), author of the shareware program Equation Service, who kindly offered some TeXnology to do so. His Equation Service provides a similar capability system-wide. If you like our in-line sub and would like to have a similar functionality within other applications, you should look into his Equation Service. As of Jan 2003, it can be obtained from his web page.
    Full Document Processing Mode
    While Baby TeX is mainly intended to produce short equations inserted and shared in an iStorm document, it is sometimes necessary to process a full blown TeX document, especially in conjunction with syncPDF which allows synchronized viewing and annotation of the processed pdf file. To do that, you may have the full text source (beginning with \documentclass [11pt]{article} and ending with \end{document} as most TeX files do) in the main iStorm doc window. Before you do anything, first select the Full TeX Document option in the Options drawer of the Baby TeX module. Many users get unpleasant result because they forget to select this. Then select the whole TeX code in the main document window and press Command-/ as you normally do for an in-line TeX. The result will replace the code with an embedded pdf view, which you can browse. Or you can double click the pdf view to bringing up in the syncPDF (this works with OS10.3 or later) module to be annotated and shared across network.
    Baby TeX Mode
    In the Tools menu, choose "Baby TeX"(Cmd-Shft-E). It will open up a small window. The upper panel displays the equation you create. The lower panel is where you type in the TeX or LaTeX commands for creating math equations and arrays. You may instead type in any valid TeX commands to get something other than an equation. (see Hacking below) Type in some TeX code in the bottom panel of the window and click the Do Baby TeX button (or press the Command-Return). After a moment, the window should look like this:



    Double click on the equation window, and depending on the code ($$ or $ for example), Baby TeX puts an appropriate selection rectangle around the equation. Generally, for $...$ (or \(...\) or \begin{math}...\end{math} blocks, the selection will be tightly around the equation, while for display math ($$...$$, \[...\] and \being{equation*}...\end{equation*} as well as the \begin{eqnarray*}...\end{eqnarray*}, the selection will span the whole page in width. If you process Baby TeX without any of the math delimiters listed above, it will process the code you type in as a normal text input. In that case, a whole page (7 inch across) will be the default size.
    If you want only a part of the equation, drag your mouse diagonally to redefine the selection. You can now drag the selection into the iStorm main document. For most people, this will be one of the main reasons to use this window at all.
    If for some reason your Baby TeX configuration is not correct, you should have gotten a message. Carefully follow the steps described earlier to install the requisite TeX system and try again.
    The drop down menu at the bottom-center of the window is to further save you from typing the usual markers for equations.
    You may have noticed a small panel next to the input panel. It contains a brief summary of math commands available in LaTeX mode, that is the default engine. Those new to TeX will find this very handy, while self-conscious grads students will generally prefer to have it shut, especially when a colleague is looking over their shoulder.

    Accessing more controls of Baby TeX

    More options are accessible in the drawer.
  • Low Resolution: By default, when you drag a selected area in the processed equation, Baby TeX uses the pdf data. This is good for high-resolution printing. However, even a simple equation is sizable (tens of kb) compared to a compressed Tiff format (a few kb). If you do not plan to print the document out, choosing the low resolution option here will be much efficient in exchanging equations with your collaborators.
  • Large Equation: One can choose appropriate size for generated equations. Default is set to Large as we find it easier for the eye.
  • Drag Equation into Keynote:With iStorm 2.01 and later, you may drag a selection from the BabyTeX window into Keynote or any other program which accepts a pdf image into its document. Note, however, that dragging from the iStorm document window into Keynote will work only for the text.
  • Export x4 tiff: So, you can drag the equation into the iStorm document either in neat pdf format or low resolution Tiff. What if you want to use Baby TeX to make equations for Word or Powerpoint? Currently, it seems neither of them take pdf bits. As a temporary solution, we offer an option to export a high resolution tiff image. Just select this option, generate an equation, and drag the image into MS products. The resulting image will be disturbingly large, but the mighty programmers at Seattle provide a way to reduce the size if you double click on the image. Choose 25 % with aspect ratio preserved. It may look ugly on the screen, but the print out will look almost as good as the pdf. (Given this much hassle, you may stick to their Equation Editor module, after all...)
  • Attach Code: You may occasionally spend 30 minutes to code a complex equation array which takes up a whole page. You think you do not want to see it again for the rest of your life. Alas, your collaborator just informs you that the equation is just one character short of revealing the secret of the universe! Since iStorm by default attaches the code to the equation, you are saved! If your equation in the document has a round gray figure at its end , you may double click either the equation cell or the gray symbol to bring up the original TeX codes to examine or copy into the equation editing panel. (See figure below) If you do not like this symbol next to your equation, you may delete them, but you will then lose the attached code.
  • Use AMS TeX Macro: Mathematicians are strange breeds. Many of them were not quite satisfied with the overwhelming degree of control the original TeX/LateX provided. So Dr. Spivak developed an extension called AMS TeX geared toward higher mathematics. In fact, some of it is quite handy for lower mathematics as well. As it takes slightly longer to load them all, we suggest you keep this option unchecked unless you need AMS TeX.
  • Full TeX Document: With iStorm 3.0 and later, it is now possible to process a long (multi-page) TeX document and share/annotate it within iStorm. Just drag in a TeX source file (.tex) into the main iStorm document window. It will show up as an icon initially. Double click on it, and the icon will be replaced by the full text TeX source, which you can edit. Select the whole source, and make sure that you have checked this option, and press Cmd-/ to process it. (You could have copied the source into the BabyTeX input module and processed it too.) Now the icon will be replaced inline by the processed pdf document. If you are under Panther (OS 10.3) or later, you can then double click the embedded pdf document to view and annotate it under SyncPDF viewer. [As of Dec 2004, with iStorm 3.0, TeX document which reads in external image files or input sources will not be properly processed and may yield confusing results. Please comment out the problematic region before you try this.]



    • The small panel in the drawer displays the message from the (La)TeX binary. The hefty message TeX normally generates may contain some information to improve the look of the output or the nature of error if you made a mistake in typing the code. For the sake of speed, we have suppressed most of it by using the command \batchmode in the header files (see section on Hacking below). To restore the message in glorious detail, you may comment out that line in the header files. If what appears on the equation window looks satisfactory, just don't bother with it. It is pretty verbose even when everything went well. Even so, being tucked inside the drawer, you will find it much easier to ignore than the Helper guy in MS Word.

    Exporting rendered equations for other programs

    It is very unfortunate that some popular programs do not yet allow simple copy-paste to work with pdf images, as output by Baby TeX by default. We did our best to provide as many ways for users to use the Baby-TeX rendered equation images as we can. Some may prefer being offered all options for conversion at the time of copy and paste, while others find it tiresome having to choose when they have 100 equations to be made and exported in the same format for Powerpoint. Here is the summary of various ways tailored for some popular situations:

    First, note that with iStorm 2.61 and later, there is a new options item called Copy Automatically which automatically copies the rendered equation into the clipboard either in PDF or in RTFD format. (You can disable it by chooing None)
    Keynote
    If you choose PDF here, go to Keynote program as soon as the equation is rendered either in BabyTeX or in the main document. In a Keynote slide, just paste. The equation will settle in the slide without any hassle. It will be beautiful, scalable, and with transparent background. This should come handy when you need to prepare a Keynote presentation with lots of equations. Should you need to keep all sources, use the inline mode to archive all equations and sources in an iStorm document along with the slide file.
    Powerpoint, Word
    Some powerful programs have not caught up yet. Powerpoint would not accept the pdf. In this case, do not expect to use Copy Automatically feature. Instead, you will manually select the portion of or the whole equation in the BabyTeX module, and copy. Go to Word or Powerpoint and paste. You will have a Tiff image, which looks fine on screen. However, it will look jagged when scaled up. If you intend to print the document, check Export x4 for Tiff option item in the BabyTeX module before rendering the equation. Select the rendered equation, copy and paste in the MS program. Now you will have a Tiff image, blown up four times. Adjust the size of the image in Powerpoint by double clicking on it, (say to 25 %) and you will have the equation with good enough resolution for printing.
    Rich Text Editor
    Just choose RTFD format for Copy Automatically. The rendered equation will now be copied automatically as a RTFD item, which has an embedded pdf file containing the image. (It may also have the source file attached depending on your setting) You can paste into any rich text editor such as iStorm or Text Edit. If you intend to convert the document into an html file, using programs such iBlog, you may do either of the following:

    Choose PDF for Copy Automatically, and just paste the automatically copied equation into the text editor. In this case, you will have a Tiff rendition of the image embedded in the document. This will be smaller in size but with low resolution. When iBlog converts the file into an html file, the equation will be displayed properly in the web page.

    If you choose RTFD for Copy Automatically on the other hand, you are essentially adding a link to the pdf image file in the web page. Therefore, if iBlog process it, it may now appear as a link to the equation image file, and the equation itself may not be displayed correctly. This may not be what you want to do, unless you want users to download the pdf file of the equation.

    Hacking Baby TeX

    Caution: Reading the following section without a compelling reason may unnecessarily complicated your life. Choose a simpler life whenever you can!

    For those of you (very) familiar with TeX, if you would like to try all kinds of things other than making just neat equations, iStorm may bend its ways to a degree. First, let us describe the basic process by which Baby TeX runs TeX or LaTeX on your code. It creates a temporary .tex file by combining the header and the modified version of the text you typed in and the footer. Imagine a typical tex document which contains an equation in the middle of it. The header portion is the part of the document up to the equation, the footer is the rest of the document after the equation. Normally, the header should contain documentclass declaration (if used with latex) and some preambles.
    Middle (body) part is largely based on what you type as the input but is generated differently depending on what type of equations and engine you use:
    For example, if you choose Large equation size, and if the formula is an array using LaTeX, 
    \Large \newlength{\myfont}\setlength{\myfont}{16pt}
\newcommand{\putstuff}
{ Your formula }
    For a single line equation using LaTeX, ($..$ or $$...$$ or \begin{equation}...\end{equation} ), iStorm generates the following body part: 
    \newcommand{\putstuff}
{ Your formula }
\newcommand{\whatsize}{\Large\newlength{\myfont}\setlength{\myfont}{16pt}}
    By modifying the header and the footer content, you may attempt further manipulation given the constraint hard-coded in making the body part described above. The question is: where are they? They are included as part of the iStorm application package. If you have administrator's privilege, you can access them by control-clicking the iStorm application itself. Choose "Show Package Content" to view the innards of iStorm. Inside the Contents/Resources directory, you will find the following text files among others:
    latexEqHeader, latexEqFooter, latexArrayHeader, latexArrayFooter, amstexEqHeader, amstexArrayHeader, altEqFooter, altEqHeader, altArrayHeader, altArrayFooter, genericHeader, genericamsHeader, genericFooter.
    The first six are used for pdflatex (or other LaTeX processor) and the next four for conTeXt (or potentially other base-TeX processor). The last three are for more general TeX commands outside the math mode. For example, when you process a block of commands which is not enclosed in any of the math delimiters, ($..$, \[ ... \], etc) then these generic Header and Footer files will be used sandwiching what you provide as the body. You may want to use this, for example, if you need to access the \newtheorem environment from AMS TeX theorem package.

    Examine the content of each file carefully. If you do not understand what you find there, maybe you should re-adjust your ambition. Find a seasoned theoretical physicist. About 87 % of the time, he or she will be free and glad to spend a few minutes to help you out. Mathematicians will be even more accommodating. Even if you piece together what is going on in the header-body-footer construction, note that room for tinkering may be limited by the hard-coded body portion except for the genericHeader/Footer. For one, any tex commands which introduce or define new variable will have trouble as they are executed twice in cases where \putstuff is called.
    An exception to this is the generic files, which literally sandwiches your command between header and footer and thus involves no hard-coded manipulation. Here your hacking task will be very straightforward.

    Further adventures

    You may get away without poring seriously into a TeX manual to make neat equations for an iStorm collaboration. Brief survey of some of the online resources given below for LaTeX should satisfy most casual need. However, for completeness, we also offer links of general nature. The most comprehensive resource available on TeX is TeX User Group (TUG). Almost every piece of software written for TeX may be found in CTAN . To become a serious user of TeX on OS X, the best vehicle would be TeXShop by Richard Koch. There is a nice TeX on OS X web site maintained by Gary L. Gray and Joe Slater which offers links to various TeX programs and utilities for Mac users.

    There are several excellent online manual for TeX and LaTeX. We offer a few links for LaTeX here:
  • Getting Started with Latex by David R. Wilkins.
  • Hypertext help with Latex offered from Goddard Institute, NASA.
  • Introduction to using TeX (LaTeX) in the Harvard Math Department.
  • (La)TeX Navigator with several links to Formats info.
  • ConTeXt: Home page for the modern challenge to LaTeX.
  • If you'd like to purchase a book on LaTeX, make it the one by its creator: "LaTeX: A Document Preparation System" by Leslie Lamport, 2nd Edition, Addison-Wesley.
  • If you think an excellent site for reference is missing, please let us know.

    • If you are having these problems:

    When I click the Do BabyTeX button, I have an error message.


    You get this message since Baby TeX could not run the (La)TeX engine. Either its name is not correct or the path to the binary is not set correctly. Please open the iStorm preferences, and correct the information. You may have to retrace carefully what we described earlier about configuring Baby TeX. Your version of iStorm may display more options such as downloading the TeX packages. Be brave and go ahead!
    Nothing happens....
    You may have typed something TeX does not understand at all. Open the drawer of Baby TeX (click More Options button) to examine the message from the engine.
    Where can I find the files generated by the TeX engine?
    Baby TeX creates transient tex files (_istormEquation.tex, .aux, .log, .pdf) in the directory [Your Home Directory]/Library/Application Support/iStorm/TeX/Temporary/ . This directory is automatically created and maintained by iStorm. If you suspect something wrong, check and make sure that you have the read/write privilege for the folder.
    I cannot think of any equation to write?
    Maybe you are a Geometry person unfortunately dragged into a group of Algebraics. Try instead iChalk to draw what's on your mind rather than fighting your true genius.
    My Equation is too long and gets truncated?
    We cannot speculate on what you are up to, but all correct equations in the universe are short. Very short. If you insist, one way to solve it would be to cut the equation into pieces. Baby TeX does not support multiple pages output. If the generated pdf file has many pages, unpredictable result may follow.
    Where can I access the temporary TeX files such as .log, .aux, .pdf as well as the source .tex files used in generating the equation?
    They are stored in the directory :
    (Your Home)/Library/Application Support/iStorm/TeX/Temporary
    with the names "_istormEquation" and extensions .aux, log, pdf, tex, tmp, tui, and tuo if these mean anything to you. When another equation is processed, they are overwritten.
    Can I save the whole iStorm document in text format with equation sources in tact ?
    Yes. In the File menu, you will find Export Text/TeX which saves it into a text file, with the following features. The equations with sources attached will be replaced with the TeX sources. The BabyMath results with sources will be replaced with the appropriate commands. The graphics will be replaced by simple tags with their names. They are preceded by the usual TeX comment sign %% so that they do not interfere with TeX when you import the file into TeXShop for example.
    I keep getting the image rendered from a previous TeX source.
    This happens when your current TeX source (either selected inline or in the BabyTeX input window) has an error and therefore prevents TeX engine from successfully completing the process. Examine carefully to find errors and remove them.
    I understand that BabyTeX is mainly for short equations and not meant for a full TeX document processing. But how do use iStorm to share a full TeX document, and collaborate on its content, such as adding annotations?
    With iStorm 3.0, you can do it! First, to process a full TeX document, you need to switch off the intelligent source bracketing behavior (by turning on Full TeX Document in the BabyTeX Options drawer). Then drag and drop the full tex source file into iStorm document and double click on the resulting icon in the view to reveal the text content. (Or you may simply paste in the source text.) Make sure that you comment out the parts where external files are read in (such as \input or \includegraphics for example) since they are not compatible with current BabyTeX (as of iStorm 3.0). The select the whole region of TeX and press Command-/ to inline process it. It will then be replaced by the pdf document, which can then shared and sync-viewed in the PDF viewer module. (complete with hared annotations and laser pointer! Ð refer to the SyncPDF section of this document.)
    Give up on TeX?
    OK. You tried but decided TeX is not your cup of tea. You can always fall back on the Equation Editor program and click-click away! As far as iStorm is concerned, you should not let visual aesthetics come before creativity. But during a coffee break, examine the quality of a paper written with Word + Equation Editor and another one with TeX. Then ask yourself the hard question: Are you so sure of your genius that you don't have to worry about how it looks to your colleagues? We bet you will come back to tackle this section again sooner or later.

    Although the http-links in this document were all active as of Dec, 2002, some of them may become stale in the future. If you find any, please let us know so that we can update them in the future version of iStorm.