# Documentation of Tralics

Content: A first example, a second example, interpretation of the transcript file and parameterisation.

## Introduction

This web page is assumed to explain how to read the Tralics documentation, and gives some examples. In general, LaTeX input is written \like{this} and the XML output <like>that</like>. You run Tralics on a file myfile.tex via the command tralics myfile. You can provide some options, before or after the file name. This may produce errors or other messages.

## Standard example

Let's consider a TeX file, named hello1.tex that consists of the following lines.

\documentclass{article}
\begin{document}
Hello, world!
\end{document}


You compile this file by saying tralics hello1.tex; the extension may be omitted. If you think that the output is too verbose, you can use the silent option: say tralics hello1 -silent. Then you will see the following 8 lines on the terminal

This is tralics 2.15.4, a LaTeX to XML translator, running on maclaurin
Licensed under the CeCILL Free Software Licensing Agreement
Starting translation of file hello1.tex.
Document class: article 2011/05/09 v1.2 Article document class for Tralics
Output written on hello1.xml (176 bytes).
No error found.


The fifth line might be Dummy default configuration file used; this indicates that Tralics is unable to find the configuration. The fifth line may be missing; this means that the article.clt file was not found. Note that Tralics never reads the file article.cls, and does not complain if class files or packages are missing. You can use the option -confdir=bar to indicates that the configuration file or class file is located in the bar directory; this option can be given more than once, in order to specify more than one location.

In some cases, when Tralics thinks you are compiling the Raweb, a fatal error may be signaled before the transcript file is opened. In all other cases, it writes some information on the transcript file (in the example above, the file hello1.log has 186 lines; in verbose mode, this could be 1071). In particular all errors appear in this file. In some cases, a file foo.img is created: it holds some information about graphic files when \includegraphics is used. Generally, an XML file is produced, it looks like the following

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE std SYSTEM 'classes.dtd'>
<!-- Translated from latex by tralics 2.15.4, date: 2015/08/20-->
<std>
<p>Hello, world!
</p>
</std>


## Small example

Assume that your document source contains the lines that follow.

% Example file tralics-ex1.tex $Revision: 1.1$
\begin{xmlelement}{preview}
This is a test. An \unknown command. A math formula $a^$.
\def\test#1#2?{#1,#2.}\test ok?\typeout{A message}
\end{xmlelement}
% EOF


If you run Tralics on the document, you will see the following on the terminal:

This is tralics 2.2 (pl2), a LaTeX to XML translator
% (some lines omitted here)
Error signaled at line 3 of file tralics-ex1.tex:
Undefined command \unknown.
Error signaled at line 3 of file tralics-ex1.tex:
Math formula should not finish with ^.
A message
% (lines omitted here)


We indicated with colors some omissions. We left the identification line (this is a very old version), the error messages, the result of \typeout, and the last line. Note that everything that is printed on the screen is also printed in the transcript file.

Four lines are printed because Tralics noticed two errors on the third line. The fourth line is OK, but the \test macro has a weird syntax. There is no \documentclass, no \begin{document} and no \end{document}: these commands are useful, but there absence is not an error. The xmlelement environment allows you to put XML elements of any name in the result file.

The XML code generated by Tralics is the following:

<?xml version='1.0' encoding='iso-8859-1'?>
<!DOCTYPE unknown SYSTEM 'unknown.dtd'>
<!-- translated from latex by tralics 2.2 (pl2)-->
<unknown>
<p><preview>This is a test. An <error l='3' c='Undefined command '/>command. % CR added
A math formula <formula type='inline'><math xmlns='http://www.w3.org/1998/Math/MathML'>% CR added
<mi>a</mi>[/itex]</formula>.
o,k.
</preview>
</p></unknown>


Some comments: in TeX, a newline character is equivalent to a space (unless followed by another newline character, the result being \par). In some cases, spaces disappear (in particular after a space); if a line is terminated by a space and a new line, and the next line starts with a space, the translator sees only one space, the newline character; its translation is a newline character. As a result most line breaks are the same in the input file and in the resulting XML document. On the other hand, spaces are ignored in math mode, and all math formulas produce long lines. In our examples, we have edited all these formulas, but for the example above, we have indicated (via blue comments) the places where new line characters have been added.