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. Begin preparing your document by pasting the body of your document between the \begin{document} and \end{document} commands in the template. Un-comment (remove the "%" sign) only the \usepackage{} commands required by your LaTeX document. These are located near the beginning of the template. If you have any "user-defined macros" you may insert these after the \usepackage{} commands. 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. 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). If your document contains images, make sure these files are at the same directory level as the file that is referencing it. Save your new template-enhanced file. Make sure to rename the files and place it in the folder with your .bib and image files. Run LaTeX (pdflatex) on the new file using only the \usepackage{} commands allowed by the template. 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: In your workspace or workgroup, create a new blank module. Then from the edit tab of that module, select LaTeX from the import drop-down list and click import.

Click browse to locate your .zip file. 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 smallThe 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 ]]>, you can change the size of the image by adjusting the number. Math text does not display spacesThe 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" (]]>). 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 To remedy this error, simply remove the MathML that is "writing" the text and replace it with your text here]]>. Two equations are referenced as a single equationOn 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 MathMlThere 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 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. Locate the culprit equation in your .tex file and comment it out. Save the file, and place the newly saved file back in your .zip file containing your .bib and image files. Import the file again. Warning, importing the content again will overwrite any work that you have done previously! Make certain that the import was successful, paying special attention to the content following the omitted equation. Manually input the MathML for the conditional statement. Hint, using the ]]> 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'tsCertain 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 importerAs 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 needOccasionally, 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 IssuesThe \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 SectionsAn 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.