TeXSave Internals and Improvements

P.J. Hinton
Mathematica Programming Group
Wolfram Research, Inc.

Internals

Calling Syntax

From the kernel  (Documented)

Supply nothing at all

TeXSave["filename.tex"] converts the current notebook selection into .tex file with the supplied filename.

Supply an external, unopened notebook

TeXSave["filename.tex", "notebookfile.nb"] converts a notebook named  notebookfile.nb into a .tex file with the supplied filename.

Supply a NotebookObject

TeXSave["filename.tex", notebookobject] converts the specified NotebookObject into a .tex file with the supplied filename.

From the kernel  (Undocumented)

Supply a Cell expression

TeXSave["filename.tex", cellexpression] converts the specified Cell or list of Cell expressions into a .tex file with the supplied filename.

Supply a BoxData expression

TeXSave["filename.tex", boxdata]converts the specified BoxData expression into a .tex file with the supplied filename.

Supply a FrontEnd`FileName object

TeXSave["filename.tex" , frontendfilenameobject] converts the notebook contained in the FrontEnd`FileName object into a .tex file with the supplied filename.

From the front end

Use the front end menu command sequence File -> Save As Special -> TeX. This action invokes the front end token FrontEndExecute[ToExpression["FrontEnd`DoTeXSave[]"]].  Special options must be given in by a kernel SetOptions[TeXSave, ...] command

Optional Arguments

EmbeddedGraphics -> False

This option specifies whether TeXSave should include converted PostScript images directly in the document or write them out to a external files.

DocumentStyle -> "article"

This option specifies what LaTeX document style should be used.  This is passed on directly to the .tex file.

ConversionRulesName -> "TeX"

This option allows the user to select from a collection  of conversion rules that may be defined in a notebook style sheet.

StyleDefinitions -> List of cells with StyleData expressions

This option allows a user to specify conversion rules for cell styles.  The conversion rules contain information about markup codes as well as what formatting rules to apply to the cell's contents.

The format is a list of Cell expressions which have StyleData in them.  TeXSave looks to three places for this information -- user-supplied options, the notebook's style sheet, and then the default list of rules in the TeXSave source code.

Specifications for text style cells should have a conversion rule that contains a list of two items: an opening markup code and a closing markup code.

Cell[StyleData["Title"], 
     NotebookDefault,
     ConversionRules -> {
       "TeX" -> {"\\Title{", "}\n"}
     }
]

Specification for box style cells should have a conversion rule that contains a list of two sublists.  The first sublist is used for inline cells, and the second is used for standalone (displaymath) cells.  Each sublist contains three items: an opening markup code, a format rule, and a closing markup code.

Cell[StyleData["StandardForm"], 
     NotebookDefault,
     ConversionRules -> {
       "TeX" -> {
         {"\(", 
          ToString[#, FormatType->TeXForm]&, 
          "\)"
         }, 
         {"\[\n", 
          ToString[#, FormatType->TeXForm]&, 
          "\n\]\n"
         }
       }
     }
]

Basic Algorithm

Initialization Code

Responsible for setting up variables that are global with respect to subordinate functions.  Open .tex file stream.  Get notebook expression from the front end.

Shared Notebook Conversion Code

Extracts conversion rules from style sheet data and applies cell conversion functions to notebook expression elements.  Much of this code is used also by HTMLSave.

Cell Conversion Rewrite Rules

Responsible for turning Cell contents into valid TeX syntax.  Rules can be divided into TextData, BoxData, and GraphicsData types.

BoxData expressions are passed off to TeXForm or front end internal PostScript conversion functions.  A new feature for Mathematica 3.0 was the ability  of TeXForm to communicate with the front end via MathLink to get line break information.  Two cell styles do not immediately pass boxes to TeXForm  -- Message and Print.

TextData expressions are handled directly by TeXSave's own processing rules.  The primary function of these rules is to replace any escapable characters with a LaTeX equivalent.  Manyunicode characters are mapped to special macros that are defined in notebook.sty.

GraphicsData expressions are handled by front end internal PostScript conversion functions.  This accounts for why only PostScript-based graphics can be exported by Mathematica as EPS.

Wrap-up code

Close output file stream.

Break long lines generated by conversion of cells with TextData.

Improvements

Improved conversion rules for TeXForm

We have gathered together several examples provided by users which illustrate cases where TeXForm does not properly convert a BoxData expression. These examples have been used to refine the robustness of both the formatting and linebreaking of formulas.

Broader support for StyleBox conversion

We have added support for StyleBoxes which use Helvetica and InputForm.

Better conversion for Message and Print cell styles

Message and Print cell styles are problematic hybrids.  A user sees them as a form of text cell but the front end stores them internally as BoxData expressions.

Since all BoxData expressions are handled by the same TeXForm rules regardless of cell style, they wind up getting converted as math mode expressions.  This means that all text will appear in an italic font with no spaces between words.

Moreover, there are troubles with Message cells because they can contain strings with embedded box expressions.

More complete notebook.sty file

The LaTeX package file that contains definitions for TeXSave-specific macros has been expanded to account for more cell styles.  The mapping of Mathematica characters to TeX commands is more complete.

New flexible newline translation selection

LiteralNewline -> Automatic

This option specifies how newline characters in a TextData string should be translated.

Control over the width of display math formulae

DisplayMathPageWidth -> PaperWidth

This option sets the page width for linebreaking of BoxData expressions.    Can be set to the notebook's window width or a numerical value in printer's points.

Support for LaTeX2ε

TeXVersion -> "LaTeX2e"

This option specifies what dialect of LaTeX to use.  In Mathematica 3.0, the .tex files were LaTeX 2.09. Under version 3.1,  the default will be LaTeX2ε.

Some Exhortations

Unless you're an expert TeX programmer, it's best to stick with the Default.nb style sheet for creating exportable documents, or at least use common cell styles.

Using stylesheets with lots of custom styles can generate unusual macro names.  The macro names will need to be added to notebook.sty if they are to be processed without errors.

The notebooks used by the help browser are machine generated.  They have lots of deeply nested box structures that cannot be converted easily using TeXForm.

LaTeX package files (.sty files) may be released with sufficient demand.

Select a newline translation mechanism that reflects your style of entering text in notebooks.

If you want newlines in a text cell to denote actual linebreaks, use LiteralNewline -> True.

If you newline in a text cell to translate into a new paragraph, set LiteralNewline -> Automatic.

If you want linebreaks to be ignored altogether, then use LiteralNewline -> False.

Be fiercely consistent in your application of styles and styleboxes.

If you want to change fonts within a cell, find a supported means of specifying this in a notebook and make sure you stick with it througout.  It can lead to inconsistent appearance if you don't.

StandardForm and InputForm cells are converted by totally different rules.  Make sure that your cells aren't a mix -- otherwise you will get a nonuniform appearance of your input and output cells.

Bear in mind that TeXSave is a translation algorithm between a WYSI(A)WYG environment to a markup language.

Not every option that you add to a cell (e.g. cell background color) has an immediate equivalent in LaTeX, so there will some aspects of your notebook's appearance that don't appear

There is no built in function for the front end that allows the front end to pass the value generated by a ValueBox or CounterBox.  Hence these values may not get preserved.

Tabbing to create an aligned appearance may look fine in a notebook, but it won't translate very well into LaTeX since the tabs are ignored in most environments.  Stick with translatable structuring mechanisms like GridBoxes.

Troubleshooting

Catastrophic event happens during TeXSave

What to note?

Observe the nature of the crash.  Is it in the kernel or front end?  Does a link get severed?

You may need to extract the notebook cell by cell to find whether it is one particular cell that is inducing the crash.

Known problems

Under Windows, general protection faults occur in the kernel library (MATHDLL.DLL) almost immediately during the notebook conversion process.  This is due to a bug in Dispatch that was exposed in optimized versions of the Windows 3.0 kernel (namely 3.0.1.0 and later).  Get the latest TeXSave sources from ftp site to fix this problem.

On all platforms, low level MathLink error messages followed by an apparent hang in the conversion process may be due to a problem in  TeXForm attempting to get linebreak information.  There is no workaround for this problem.  You may be able to manually run TeXForm on the BoxData expression in a standalone kernel session and paste the result in the .tex file.

Another source is the presence of an InterpretationBox which contains a number stored in the new exponential notation (e.g. 9.3*^6).  Sometimes manually editing the interpretation box will fix the problem.

Conversiontime error messages

What to note?

Get the exact wording of the error message.

Front End assert errors

Diagnosis

These are caused by the front end's typesetting algorithms as they attempt to compute line break information from TeXForm.   This is usually a benign problem.

Known problems

Pathological structures like Input cells which have consecutive newline characters and large grid box structures are common culprits.

Sometimes the output of such a conversion may still have its box expression wrapper.  The user may need to edit the source file to get the desired result.

Get::noopen error messages

Diagnosis

Very early within the notebook conversion process, an error message reports not being able to find a style sheet.

Resolution

Add the style sheet directory to the kernel's $Path variable.  This has been fixed for Mathematica 3.1 because the kernel now queries the front end for the style sheet path and proceeds to look in those directories instead.

StringJoin::string error messages

Diagnosis

At any given time during the conversion process, an error message reports that a StringJoin has non-string arguments.  The occurence of this problem is detrimental to the .tex file since unsuccessful concatenation can usually result in raw Cell expressions being written as output.

Resolution

Get the latest version of TeXSave sources from the ftp site.  The error message is occurring as strings are being concatenated together to form macros.  The new sources have better logical constructs for ensuring that only strings get fed to StringJoin.

File won't process with LaTeX

What to note?

Open exported LaTeX file in a text editor to see what the syntax looks like in the neighborhood of the error message.  Find the portion of the corresponding region of the Mathematica notebook that gives rise to the bad syntax.

Known problems

TeXForm can botch the conversion of BoxData in several ways:

1) Grid boxes will get converted to array structures that have bogus justification syntax. This means that you may get "runaway argument" error messages.

\dispSFinmath{\MathBegin{MathArray}[c]{ll[c]llllllll}

Most of these problems have been addressed for Mathematica 3.1.

2) Juxtaposing a Greek character and a Latin character for a variable name can cause syntax problem because TeXForm fails to properly close off bracketed expressions.  This has been fixed in Mathematica 3.1.

If you use Message or Print style cells in your convertible notebooks, it is a good idea to get a copy of the latest TeXSave sources from the ftp site.

Getting help

Joe Kaiping's TeXSave Help page

Hints on troubleshooting problematic TeXSave output can be found at URL

http://www.wolfram.com/~kaiping/TeXSave/

TeXSave FTP Update Site

Latest TeXSave source code and notebook.sty can be obtained from ftp site URL:

ftp://mathsource.com/pub/outgoing/TeXSave/