You are here: Home » Help » Authoring » Using LaTeX to Create Modules

Using LaTeX to Create Modules

How to use the LaTeX template to create modules that can be easily imported and converted to the CNXML format.

Overview:

Using this importer, you can generate CNXML from a LaTeX document that has been specifically prepared for import.

Getting Started

For experienced LaTeX users, the LaTeX importer provides the easiest path for writing modules with sophisticated mathematical expressions. The LaTeX document is translated into the CNXML markup language with presentation MathML encoding the mathematics. The fidelity of the mathematical translation is quite high for even the most complicated expressions. Here, we will show you how to use LaTeX to properly prepare your document for importing into the repository.

The first thing you need to do before you start creating documents, is to obtain a copy of the LaTeX Template. Using this template you can create modules that preserve formatting from your LaTeX document.

Downloading the LaTeX Template

Click the link below to download a copy of the LaTeX Template.

Latex Template

Preparing Your Document for Import

The LaTeX-to-CNXML conversion tool is built around the open-source Tralics LaTeX-to-XML converter. Tralics supports a large but not complete subset of LaTeX; thus, LaTeX documents must be prepared for conversion into CNXML according to certain guidelines. By inserting the body of your LaTeX source into the template file provided above, you will maximize your chances of a successful import.

Authoring with the LaTeX Template

The template file contains the list of LaTeX packages supported by the importer. Using the template and your original .tex file, the steps to importing are as follows:

  1. Format your original LaTeX source using the template:
    • Copy the body of the LaTeX document you wish to import and paste it into the template between the \begin{document} and \end{document} statements.
    • Un-comment any of the \usepackage{} statements required by your LaTeX content, insert any user-defined macros required, and supply your .bib file as directed by the template file comments.
    • Make sure all required image files are included in either .eps or .pdf formats at the same directory level as the .tex file.
    • Save the document as a new .tex file ("myFile.tex" for the purposes of these instructions).
  2. Ensure that you can run latex (pdflatex) on myFile.tex to produce a .dvi (.pdf) file using only the packages supported in the template file. For an alphabetical listing of all LaTeX commands supported by Tralics, see the "HTML documentation of all TeX commands, in alphabetic order" section on the Tralics homepage.
  3. Include myFile.tex, all necessary image files, and all necessary .bib files in a .zip file named myFile.zip. The name of the zip file must match the name of the .tex file, and all files must appear in the root directory of the .zip file --- that is, there may be no folders or sub-folders in the .zip file.

LaTeX Importer Don'ts

Certain practices allowed by LaTeX in general are not supported through Tralics. These must be avoided, as they will break the importer. They include:

  • Placing tables within other tables
  • Ommitting braces for LaTeX commands when they take a single argument. As an example, consider use of the \sqrt{} command without braces, as in \sqrt\pi instead of \sqrt{\pi}. The latter usage is the only supported technique.
  • Using different capitalizations on the filenames in \includegraphics{} statements than are used in the actual files they reference in the .zip folder. Though this may work in development on a Windows platform, it will cause an error in the Linux-based importer.
  • Using \mbox{}. This has no correspondence in CNXML and will result in a failure to import.

LaTeX Importer Do's

Though LaTeX offers an almost endless number of ways to any one task, Tralics' restricted package support requires us to adhere to certain conventions with common tasks. We recommend the following LaTeX code for common tasks.

  • Inserting an Image - when you wish to include an image file (say, myImage.eps) with a certain size parameter (say, 50% scale factor), you should use the graphicx pacakge notation for the \includegraphics command, as in:

    \begin{figure}
    \includegraphics[scale=0.50]{myImage.eps}
    \caption{This is my caption.}
    \label{fig:myFigure}
    \end{figure}

Importing Your LaTeX Document

Once your .tex file has been properly prepared according to the template and you have put all your files in a .zip file as directed above, you are ready to import your LaTeX document. First, you must create a blank module in your personal workspace or shared workgroup (see Editing Modules). Then, from the Edit tab of that module, the follow these steps to import your LaTeX document:

  1. Select LaTeX from the Import drop-down list and click Import. (Figure 1)
  2. Click Browse to locate the .zip (here, myFile.zip) as shown in Figure 2.
  3. Click Import to upload your document.
Import a LaTeX document into a new (empty) module.

Figure 1: The import/export screen in the editing interface.


Browse to your saved file.

Figure 2: The import file selection box.


Importing Results and Post-Import Editing

As you examine your document after import, you may notice that not all of the original LaTeX commands have analogs in your module. This can happen for one of two reasons.

First, the LaTeX importer is only capable of producing CNXML for the LaTeX commands supported by Tralics. These commands consist of the base LaTeX as well as the series of add-on packages Tralics supports. Additionally, not all packages included by Tralics are supported in their entirety. A description of supported packages can be found at this link. The LaTeX template attempts to track the packages listed there.

Tralics also maintains a complete alphabetical listing of all LaTeX commands it supports. To access these links, you can visit the "HTML documentation of all TeX commands, in alphabetic order" section on the Tralics homepage. As you examine your module after import, these links are a valuable resource in determining which subset of LaTeX could pass through the import.

Second, not all Tralics-supported LaTeX commands have analogs in CNXML (to see a complete list of CNXML tags, click here). If you find an example of Tralics-supported LaTeX that should have a CNXML translation but does not, please let us know using the bug submission form.

Finally, there are tags in CNXML which have no analog in LaTeX but may prove useful in your module. Examples of these include notes, exercises, links between modules, etc. These must be added after import, either using the Edit-in-Place interface (recommended) or full-source editing.

It is important when using the LaTeX importer that you finish preparing the document to your satisfaction in LaTeX before importing and editing the CNXML. Any re-import of the LaTeX document will erase the changes you make using Edit-in-Place or full-source editing.

My Account