TRALICS : a LaTeX to XML translator

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>.

In TeX, there is a difference between a dimension and a glue. In some cases, we use the LaTeX denomination: rigid length and rubber length.

Standard example

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

This is tralics 2.10.7, a LaTeX to XML translator, running on macarthur
Copyright INRIA/MIAOU/APICS 2002-2007, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Starting translation of file hello1.tex.
Document class: article 2006/08/19 v1.0 article document class for Tralics
Output written on hello1.xml (181 bytes).
No error found.
(For more information, see transcript file hello1.log)

If the line with `Document class' is 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 say tralics foo -confdir=bar if the class file is located in the bar directory (more than one confdir option can be given, and the current directory is always searched first).

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 111 lines; in verbose mode, this could be 765). 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

Small example

Assume that your document source contains the lines that follow. We sometimes use colors for comments that may appear in the source file, and could be added in this HTML page for emphasize.

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) 
(For more information, see transcript file tralics-ex1.log)

The output of Tralics is black and white, lines in color are changes (additions, omissions, etc) to it. In this example we have selected seven lines: the first lines says: ``this is tralics etc.'', and the last that says ``see transcript file XX''. 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 need to insert a \documentclass, or a document environment (they are implicit). The xmlelement environment allows you to put XML elements of any name in the result file.

<?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></math></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.

You can invoke Tralics with the -noxmlerror flag, in this case no <error> element is inserted in the XML. You can invoke Tralics with the -noundefmac flag, in the case, the XML file will contain \unknown instead of the <error> element. You can invoke Tralics with the -nomathml flag, in the case, the XML file will not contain MathML elements. Using these two switches gives

We have designed an XSLT style sheet (named `preview.xsl') whose purpose is to remove from the XML output everything but the <preview> elements. It is possible to process the resulting document like any other XML document, in this case, we convert it to XSL-fo, via the `simplefo.xsl' style sheet then to dvi and PostScript. We hacked the `fotex.sty' file, so that the following command \RequirePackage[active]{preview} (preview package by David Kastrup) is activated. As a result, lots of code inserted by the `simplefo.xsl' style sheet becomes useless, and only <preview> elements are used. As a consequence, the PostScript contains only the translation of the two lines of code. Converting to an image, it is preview example

In the documentation, all images are obtained in this fashion. If you call Tralics with the -verbose switch, or if you say \tracingall, then the transcript file will contain lines like these.

    Trace of tralics 2.2 (pl2) for file tralics-ex1.tex
%L0 This is tralics 2.10.7, a LaTeX to XML translator, running on macarthur
    Using iso-8859-1 encoding (idem transcript).%L1 
    Left quote is ` right quote is '%L2 
    ++ file .tralics_rc does not exist.%L3 
% lines omitted
    No \documentclass in source file
% lines omitted
    {\countdef \count@=\count255}%L4 
    [1] %% Begin bootstrap commands for latex
    [2] \def\lq{`}\def\rq{'}\def\lbrack{[}\def\rbrack{]}%
% lines omitted
    [63] %% End bootstrap commands for latex
%L5 [52] %% End bootstrap commands for latex
    [1] % Example file tralics-ex1.tex $Revision: 1.1 $
    [2] \begin{xmlelement}{preview}
    {\begin}
    {\begin xmlelement}
    +stack: level + 2 for environment
%L6 +stack: level + 2 for environment entered on line 2
    {xmlelement}
    {Push argument 1}
    Character sequence: preview.
    {Text:preview}
    {Pop 1: document_v argument_v}
    {Push p 1}
    {Push ELT 2}
    [3] This is a test. An \unknown command. A math formula $a^$.
    Character sequence: This is a test. An .
    Error signaled at line 3 of file tralics-ex1.tex:
    Undefined command \unknown.
    {Text:This is a test. An }
    Character sequence: command. A math formula .
    {math shift character $}
    {Text:command. A math formula }
    +stack: level + 3 for math
    +stack: level - 3 for math
    Math: $a^$
    Error signaled at line 3 of file tralics-ex1.tex:
    Math formula should not finish with ^.
    Character sequence: . .
    [4] \def\test#1#2?{#1,#2.}\test ok?\typeout{A message}
    {\def}
    {\def \test #1#2?->#1,#2.}
%L7 {changing \test=undefined}
%L7 {into \test=macro:#1#2?->#1,#2.}
    \test#1#2?->#1,#2.
    #1<-o
    #2<-k
    Character sequence: o,k..
    {\typeout}
    A message
    Character sequence:  .
    [5] \end{xmlelement}
    {\end}
    {Text:.
    o,k.
    }
    {\end xmlelement}
    {\endxmlelement}
    {Pop 2: document_v p_v ELT_h}
    {\endgroup (for env)}
    +stack: killing \test
    +stack: ending environment xmlelement; resuming document.
    +stack: level - 2 for environment
%L6 +stack: level - 2 for environment from line 2
    Character sequence:  .
    [6] % EOF
% lines omitted
    (For more information, see transcript file tralics-ex1.log)

We have indicated with red comments the difference between the original version and the new one. If the comment is on the end of line, it is a new feature, if it is at the beginning, it is a modification to the preceeding line. We have indicated for intance on line L1 the new header, on line L5 that that number of bootstrap commands depends on the version. We have shown some typical lines (for instance how left and right quotes are translated, the value of the current output encoding, etc. lines L1, L2). Whenever Tralics tries to open a file, a new line is added to the transcript file. In the example shown above, you can see on L3 that the configuration file (.tralics_rc) is not found in the current directory, the full transcript shows that it is found elsewhere. Commands like \countdef are always traced, even in silent mode, line L4. Debugging has been improved, for instance on lines L6, you can see the input line of the start of the environmen, and on line L7, you can see that when a cmmand is defined, its old definition is shown.

Whenever a line a text is read, it is printed in the transcript file, with the line number in square brackets. There are two lines numbered one: this is because some commands are executed in any case.

There are lines of the form: Character sequence: This is a test. An . This means that Tralics has seen some characters, and the logger keeps them in a buffer; the buffer is flushed when needed, namely when something else has to be printed on the transcript file; the space after the colon and the last dot are not part of this string; in TeX, you would see {the letter T}, but only the first letter of a sequence is shown by TeX. Spaces were not shown in previous versions. Another buffer contains characters translated, but not yet added to the XML tree; when the buffer is flushed, a line of the form {Text:preview} is printed.

There are lines of the form +stack: level + 3 for math. This means that a new level has been entered in the semantic nest (here because of the math formula, but a \begin command, a \begingroup, an open brace, a dollar sign, a \hbox, can increase the level).

There are lines of the form {Push p 1} and {Push ELT 2}. These indicate what is pushed on the XML stack. (element 0 is the document, after that comes a p (paragraph) and a ELT (an xmlelement). To each push corresponds a pop, like this {Pop 2: document_v p_v ELT_h}. The suffix corresponds to the current mode, vertical mode in the example.

You can see the macro-expansion: \test#1#2?->#1,#2., notice that \typeout is a primitive.

You can study the lines associated to the \end command: the buffer is flushed, the argument is read, and printed, and the command is executed. After that, \endgroup unwinds the stack; it restores the old definition of the \test command, and switches back to the global environment (remember \begin{document} is implicit).

Parameterisation

You can change the name of some elements. For instance, consider the following input.

\documentclass{article}
% Example file tralics-ex2.tex $Revision: 1.1 $
\begin{document}
\begin{itemize} \item [A] B \end{itemize}
\begin{glossaire} \glo{x}{y}\end{glossaire}
\part{A}\chapter{B}\section{C} \subsection{D}
\subsubsection{E}\paragraph{F} \subparagraph{G}
\begin{motscle}first,second \end{motscle}
\mbox{$a$}
\declaretopic{10}{foo}\caption[opt]{ok}
\footnote{anote} \includegraphics{x.ps}
\begin{figure}\includegraphics{y.ps}\end{figure}
\end{document}

<list type='simple'><label>A</label>
<item id='uid25'><p>B </p>
</item></list>
<list type='gloss'><head>Glossary</head><label>x</label><item><p>y</p>
</item></list></div3></div2></div1></div0>
<div0 id='uid26'><head>A</head>
</div0>
<div0 id='uid27'><head>B</head>
</div0>
<div0 id='uid28'><head>C</head>
<div1 id='uid29'><head>D</head>
<div2 id='uid30'><head>E</head>
<div3 id='uid31'><head>F</head>
<div4 id='uid32'><head>G</head>
<keywords><term>first</term>
<term>second</term>
</keywords><p><mbox><formula type='inline'><simplemath>a</simplemath></formula></mbox>
<topic num='10'><t_titre>foo</t_titre></topic>
<caption>ok</caption>
<note id='uid33' place='foot'>anote</note> <figure file='x'/>
</p>
<figure file='y' id='uid34'></figure>

## This is an example of a configuration file for tralics
## Copyright 2006 Inria/apics, Jose' Grimm
## $Id: doc-start.html,v 1.13 2007/11/05 09:43:02 grimm Exp $
## tralics ident rc=unused.tcf  $Revision: 1.1  $

  xml_labelitem_name = "Xlabel"
  xml_gloitem_name = "Xglolabel"
  xml_item_name = "Xitem"
  xml_div0_name = "Xdiv0"
  xml_div1_name = "Xdiv1"
  xml_div2_name = "Xdiv2"
  xml_div3_name = "Xdiv3"
  xml_div4_name = "Xdiv4"
  xml_div5_name = "Xdiv5"
  xml_div6_name = "Xdiv6"
  xml_subfigure_name = "Xsubfigure"
  xml_row_name = "Xrow"
  xml_cell_name = "Xcell"
  xml_keywords_name = "Xkeywords"
  xml_term_name = "Xterm"
  xml_mbox_name = "Xmbox"
  xml_topic_name = "Xtopic"
  xml_caption_name = "Xcaption"
  xml_footnote_name = "Xnote"
  xml_fbox_name = "Xfbox"
  xml_box_name = "Xbox"
  xml_picture_name = "Xpicture"
  xml_graphics_name = "Xgraphics"
  xml_figure_name = "Xfigure"
  xml_table_name = "Xtable"
  xml_Table_name = "XTable"
  xml_bezier_name = "Xbezier"
  xml_put_name = "Xput"
  xml_line_name = "Xline"
  xml_vector_name = "Xvector"
  xml_oval_name = "Xoval"
  xml_dashline_name = "Xdashline"
  xml_drawline_name = "Xdrawline"
  xml_dottedline_name = "Xdottedline"
  xml_circle_name = "Xcircle"

<list type='simple'><Xlabel>A</Xlabel>
<Xitem id='uid25'><p>B </p>
</Xitem></list>
<list type='gloss'><head>Glossary</head&gqt;<Xglolabel>x</Xglolabel><Xitem><p>y</p>
</Xitem></list></Xdiv3></Xdiv2></Xdiv1></Xdiv0>
<Xdiv0 id='uid26'><head>A</head>
</Xdiv0>
<Xdiv0 id='uid27'><head>B</head>
</Xdiv0>
<Xdiv0 id='uid28'><head>C</head>
<Xdiv1 id='uid29'><head>D</head>
<Xdiv2 id='uid30'><head>E</head>
<Xdiv3 id='uid31'><head>F</head>
<Xdiv4 id='uid32'><head>G</head>
<Xkeywords><Xterm>first</Xterm>
<Xterm>second</Xterm>
</Xkeywords><p><Xmbox><formula type='inline'><simplemath>a</simplemath></formula></Xmbox>
<Xtopic num='10'><t_titre>foo</t_titre></Xtopic>
<Xcaption>ok</Xcaption>
<Xnote id='uid33' place='foot'>anote</Xnote> <Xfigure file='x'/>
</p>
<Xfigure file='y' id='uid34'></Xfigure>

Documentation of Tralics

Introduction

Standard example

Small example

Parameterisation