Skip to content Skip to navigation

Connexions

You are here: Home » Content » Using and Troublshooting the LaTeX-CNXML Importer

Navigation

Content Actions
  • Download module PDF
  • Add to ...
    Add the module to:
    • My Favorites
    • A lens
    • An external social bookmarking service
    • My Favorites (What is 'My Favorites'?)
      'My Favorites' is a special kind of lens which you can use to bookmark modules and collections directly in Connexions. 'My Favorites' can only be seen by you, and collections saved in 'My Favorites' can remember the last module you were on. You need a Connexions account to use 'My Favorites'.
    • A lens (What is a lens?)

      Definition of a lens

      Lenses

      A lens is a custom view of Connexions content. You can think of it as a fancy kind of list that will let you see Connexions through the eyes of organizations and people you trust.

      What is in a lens?

      Lens makers point to Connexions materials (modules and collections), creating a guide that includes their own comments and descriptive tags about the content.

      Who can create a lens?

      Any individual Connexions member, a community, or a respected organization.

    • External bookmarks
  • E-mail the author

Recently Viewed

This feature requires Javascript to be enabled.

Using and Troublshooting the LaTeX-CNXML Importer

Module by: Daniel Williamson

Summary: This module is a beginner's guide to using and troubleshooting the LaTeX-CNXML importer.

Abstract

This module is a beginner's guide to using and troubleshooting the LaTeX to CNXML importer. It can be used a companion to the Connexions LaTeX Importer tutorial at cnx.org/help/UsingLaTeX.

How to use the LaTeX Importer

One of the first lessons learned when using the LaTeX importer is to abide by the rules. The importer is a rather faithful utility, but it will not function properly unless the LaTeX file is properly prepared. So, the first step to importing your LaTeX document is preparation.

Connexions has created a template that will aid you in this process. The template is available for download here.

Using the LaTeX Template

The importer uses Tralics to translate LaTeX to CNXML. Tralics supports a large number of LaTeX packages and commands, but not all of them. Using the Connexions LaTeX Template will increase your chances for a successful import. Follow the steps below to prepare your document.

  1. Begin preparing your document by pasting the body of your document between the \begin{document} and \end{document} commands in the template.
  2. Un-comment (remove the "%" sign) only the \usepackage{} commands required by your LaTeX document. These are located near the beginning of the template.
  3. If you have any "user-defined macros" you may insert these after the \usepackage{} commands.
  4. At the end of the document you may supply your .bib files. Make sure these files are at the same directory level as the file that is referencing it.

    Note:

    An issue has been noted with .bib file names containing capital letters. Ensure that your .bib files are labeled in lower-case letters (including the extensions).
  5. If your document contains images, make sure these files are at the same directory level as the file that is referencing it.
  6. Save your new template-enhanced file. Make sure to rename the files and place it in the folder with your .bib and image files.
  7. Run LaTeX (pdflatex) on the new file using only the \usepackage{} commands allowed by the template.
  8. Include the new file, all image files and .bib files in a new .zip file with the same name as your template-enhanced .tex file. Their names must match and there should not be any sub-folders!

Importing your LaTeX Document

Once you have successfully completed the steps above, your document should be properly prepared for import in to the Connexions depository. Follow the steps below:

  1. In your workspace or workgroup, create a new blank module.
  2. Then from the edit tab of that module, select LaTeX from the import drop-down list and click import.
    Figure 1
    Figure 1 (LaTeX import.png)
  3. Click browse to locate your .zip file.
  4. Click import to upload your document.

Troubleshooting your Import

This section of the module will serve as a consistently updated resource documenting typical importer issues and errors as well as known solutions.

The Document Imports but there are Errors with the Content

  • Links to outside of the module are missing - <cnxn> tags are CNXML's version of LaTeX \ref links. When you chop a larger LaTeX document up to make modules, the \ref links pointing to objects still inside the new, smaller document will become <cnxn>'s. Those \ref links pointing to objects now outside of the modularized document will not. All non-internal links will have to be inserted manually using <cnxn> tags. Also, it is important to note that inter-module CNXNs can not be established until the modules have been published and assigned a module number.
  • Images are too large or small - The importer displays the image at the size of the originally imported image, but it is possible to manipulate the image size inside Connexions. Click on the image and discriptive information will display information. You will notice that the width is displayed in two places. Where it says <param name="width" value="the width of your image"/>, you can change the size of the image by adjusting the number.
  • Math text does not display spaces - The importer converts all math into presentation MathML. When text is written within the \begin{equation} and \end{equation} tags in the LaTeX file, the text will be interpreted as an "identifier" (<m:mi></m:mi>). The result of this error will look like the equation below.
    δ = m i n { δ i } , f o r a l l p a s s a n d s t o p b a n d s i δ = m i n { δ i } , f o r a l l p a s s a n d s t o p b a n d s i (1)
    To remedy this error, simply remove the MathML that is "writing" the text and replace it with <m:mtext>your text here</m:mtext>.
  • Two equations are referenced as a single equation - On occasion, the importer will misinterpret two consecutive equations as a single equation. This occurs quite frequently when there is nothing separating the equations. The solution to this error is to simply copy the MathML for the second equation and pasting it into a new equation box.
  • An equation has assimilated everything following it into MathMl - There is a noted bug with Tralics where the converter can not understand where certain equations end. This is especially common with conditional statements such as this:
    a ( n ) = { h(M) 0 2h(n) for n = M otherwise for 0 ≤ n ≤ M - 1 a(n)={ h(M) 0 2h(n) for n = M otherwise for 0 n M - 1 (2)
    Statements like this may LaTeX on your computer, but they often result in errors when used with Tralics. Unfortunately, this issue is not a simple fix. Follow the steps below to fix this issue.
    1. Locate the culprit equation in your .tex file and comment it out.
    2. Save the file, and place the newly saved file back in your .zip file containing your .bib and image files.
    3. Import the file again.

      Note:

      Warning, importing the content again will overwrite any work that you have done previously!
    4. Make certain that the import was successful, paying special attention to the content following the omitted equation.
    5. Manually input the MathML for the conditional statement.

      Note:

      Hint, using the <m:munderover></m:munderover> command will help you create this type of conditional statement.

The Document Does NOT Import

These errors are much more difficult to remedy. As of right now, the error message received when a file does not import is generic and gives very little information about what actually caused the import to fail, but this section will provide you with a few known issues that might result in failure.

  • Known Tralics 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.
  • Packages Supported by the Tralics importer - As mentioned previously, Tralics supports several LaTeX packages, but not all of them. For a complete list of supported packages and sub-packages, visit the Tralics website. You may wish to visit this site to determine what packages might be causing the imports failure.
  • Use only the packages you need - Occasionally, using packages that are not required by your document can result in errors. Make certain that all of the un-commented \usepackage{} commands are actually required by your document. If you locate any that are not necessary comment them out, save your file and attempt to import the file again.
  • mbox Issues - The \mbox{} command is known to cause issues, especially when more than of these commands occurs in close succession. For example the following lines of LaTeX resulted in the a module's failure to import, even though it was possible to successfully build the file on a Windows platform. 
    
\be
                    n\phi  =  2K_1i  \ \ \ \mbox{for  i = 0, 1,
                    \dots}
\label{cc24}\ee

From (\ref{cc15}), this gives

\be
             \omega_{zi} =  sn [2K_1i/n,k] , \ \ \ \mbox{i =
             0,1,\dots}
\label{cc25}\ee

This can be reformulated using (\ref{cc18}) so that $n$ and $K_1$ are not
needed. For $N$ odd, the zero locations are

\be
             \omega_{zi}  =  sn [2Ki/N,k] , \ \ \ \mbox{i = 0,1,\dots}
\label{cc26}\ee
    Fortunately, commenting out this section of code made it possible to successfully import the module. The MathML for these equations was added manually after the import of the rest of the module.
  • Empty Sections - An empty section is a portion of the LaTeX file that contains a \section{your text here} command, but lacks any content following it. This sort of empty section is permitted anywhere inside the document except as the final section if the section is followed by a bibliography file. This will break the importer. There is a simple remedy for this issue. If you do not need the section, simply comment it out and attempt to import again, but if you do need the section header resulting from the command, add text following the marker but before the bibliography. Once you import the file, you can manually delete the text from the paragraph under the section marker, but you can not delete the paragraph. This is prohibited by Connexions. A section must contain something.

Conclusion

Hopefully this short guide has been helpful. Obviously, this list does not cover all of the possible issues, but this module will serve as a living document continuing to be updated and refined as new issues and solutions become known. If you come across an error that you think is a Tralics based error, please let Connexions know using the bug submission form.

Comments, questions, feedback, criticisms?

Send feedback