Tralics and the Raweb

A short history of the Raweb may be found on the Inria internal web site Inria internal website. The question concerns Inria's Annual Activity Report, also known as ``Rapport d'activité'', or ``Annexe technique'' to the RA or ``annexes scientifiques'' to the RA. This is a document, written by the research teams, at the end of the year N (October, November), and published in March of year N+1.

Until the 1993 edition (published in 1994), only a paper version existed. A LaTeX model was used since 1987, designed by Jacques André then Martin Jourdan. See the following paper, Une expérience d'utilisation de LaTeX : le Rapport d'activité de l'INRIA by Louarn in the first Cahiers Gutenberg.

In 1993, contacts were made with the Grif S.A. society, for the design of a SGML DTD and a LaTeX-to-SGML converter. As a result, Philippe Louarn was able to put on the web the RA (year 1994) in its HTML version. But this was judged too complicated, and for several years, the HTML was directly produced from the LaTeX source, using latex2html.

In 1996, a working group (conducted by Albert Benveniste) gave new specifications: independent modules, grouped into ten sections, etc. A technical group was created, whose objective was to find a company that could sell a software (maybe using XML as intermediate language). None was found, but the design of modules (in LaTeX syntax) was well-defined by Laurent Pierron and José Grimm. For the Ra98, a Perl script did some preprocessing, splitting the LaTeX source into modules (one module per HTML page).

In 1999, the Scientific Annexes to Inria's Annual Report were renamed RAWEB, to emphasize the role played by the Web (it is available as a CD-Rom, but no more printed by Inria).

In 2001, the Perl scripts mentioned above evolved into a LaTeX-to-XML converter (some ideas were borrowed from latex2html, which is also a Perl script). The main trouble was conversion from XML to Pdf, and we used tools from the TeX community (by S. Rahtz and D. Carlisle) and PdfLaTeX. On the other hand, the images in the HTML files were converted by LaTeX. Additional software (indexes, etc.) was written/used by Marie-Pierre Durollet.

This gave a complicated object: a Perl script, that converts a LaTeX file into XML (using Omega as a subprocess for the math) followed by another Perl script that extracts the math, calls latex, then dvips, then pstoimg (a Perl script that calls ppmquant, pncrop, and so forth, whose job is to produce a png image for the math formula), and finally an XSLT processor for the effective conversion.

1.2 Birth of Tralics

The big Perl script was rewritten as a C++ translator, renamed Tralics, and got (for version 1.6) a first IDDN number in Dec. 2002. This software was still able to produce a LaTeX preview of the Raweb: The source is read, the syntax is tested, a LaTeX file is written for each module, latex and bibtex are called, the resulting dvi is converted to PostScript. But the same Tralics can be used in a different way: the source is read, the syntax is tested, an XML file is created, an XSLT processor is called to generate the XSL/FO, and PdfLaTeX generates the Pdf (you can also generate an HTML version).

Note that in 2003, there were a few people writing their RA directly in XML. As a consequence, the new Tralics, to be be used in 2004, does only the bare minimum: it converts the LaTeX into XML. There is a Perl script that does everything else (calling external programs like latex, xsltproc, etc). A non-obvious point concerns conversion of math and images into HTML. Currently, a Perl script extracts the math, uses LaTex to produce a dvi file, which in converted to PostScript then png format.

Since 2005, the XML version of the Raweb is available on the web; its DTD is different from what Tralics produces; the research report inria-0000077 describes both DTDs and the XSL style sheet that does the conversion.

Since 2008, a raweb file is like another file. The pre-processor (with all its fatal errors) has been removed, as well as the postprocessor. All commands, specific to the raweb like \project are now defined in a style file (to be used via a class file), they may use some primitives that extract data from a configuration file.

2. Overview of the system

2.1 Requirements of the Raweb

We give here an example of a real file. It is an abridged version of the Report of the MIAOU project. The input to Tralics is: one TeX file (that can input other TeX files), one, two or three bibliography files, and some image files. These three bibliography files can be merged into a single one; and the filecontents environment might be used to insert the bibliography in the TeX source.

In the example, we have three bibliography files: miaou2003.bib, miaou_foot2003.bib, and miaou_refer2003.bib and one image (The image is extracted from a power-point presentation, converted to PostScript, then Pdf; the image shown here is the png version of the PostScript file obtained via convert; you can see this on the web, and notice a loss of quality.) The image explains how Tralics is connected to the other processes.

When translating a file, Tralics can be in Raweb mode or not. Differences between Raweb and non-raweb modes are tiny: they concern essentially the bibliography (there are some tests that check if an item is in the correct bibliography file). In Raweb mode, the input file should be foo2004.tex, where foo matches the name of team, and the document class should be ra2004 (replace 2004 by the current year). Non-ascii characters, as well as uppercase letters are forbidden.

2.2 Trivial examples

Example 1. An important point is that Tralics compiles only TeX files, i.e. whose names end with .tex. If no extension is given, one is added. The xml extension is replaced by tex.

grimm@medee$ tralics my_file.xml
This is tralics 2.13.0, a LaTeX to XML translator, running on medee
Copyright INRIA/MIAOU/APICS 2002-2008, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Fatal error: Cannot open input file my_file.tex

Example 2. Earlier versions of Tralics refused to translate files that are not in the current directory.

grimm@medee$ tralics /floppy/foo etc
This is tralics 2.8, a LaTeX to XML translator
Copyright INRIA/MIAOU/APICS 2002-2006, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Fatal error
Absolute or relative pathnames not allowed: /floppy/foo

Example 2bis. Since version 2.10.7 Tralics accepts to translate files that are not in the current directory. By default, the XML result and transcript files are put in the same directory as the input, but this can be changed.

grimm@macarthur$ tralics ../Test/hello -outputdir=/tmp -logfile=x -silent
This is tralics 2.13.0, a LaTeX to XML translator, running on medee
Copyright INRIA/MIAOU/APICS 2002-2008, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Starting translation of file ../Test/hello.tex.
Output written on /tmp/hello.xml (192 bytes).
No error found.
(For more information, see transcript file /tmp/x.log)

Example 3. In the examples 1 to 6, we use the -silent switch to reduce verbosity, and we translate a trivial TeX file. Here we demontrate the -dir switch. This option has currrently no effect anymore.

grimm@medee$ tralics hello -dir none -silent
This is tralics 2.13.0, a LaTeX to XML translator, running on medee
Copyright INRIA/MIAOU/APICS 2002-2008, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Starting translation of file hello.tex.
Output written on hello.xml (192 bytes).
No error found.
(For more information, see transcript file hello.log)

grimm@medee$ tralics -noconfig hello -silent
This is tralics 2.8, a LaTeX to XML translator
Copyright INRIA/MIAOU/APICS 2002-2006, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Starting xml processing for hello.
No configuration file.
Output written on hello.xml (171 bytes).
No error found.
(For more information, see transcript file hello.log)

Example 5. In version 2.8, you could set the shell variable TRALICSDIR to a directory containing the configuration file. This has no effect any more, and the translation is the same as in example 3.

grimm@medee$ TRALICSDIR=.. tralics hello -silent
This is tralics 2.13.0, a LaTeX to XML translator, running on medee
...
(For more information, see transcript file hello.log)

Example 6. Here the configuration file is found via default rules. Translation is the same as in example 3.

grimm@medee$ tralics hello -silent
...
(For more information, see transcript file hello.log)

In all these examples, the TeX file contains a single line Hello, world!. The translation is

<?xml version='1.0' encoding='iso-8859-1'?>
<!DOCTYPE unknown SYSTEM 'unknown.dtd'>
<!-- translated from latex by tralics 2.8-->
<unknown>
<p>Hello, world!
</p></unknown>

There are some differences between version 2.8 and the current version. For instance the compilation date has been added in the XML, thus making it a bit larger (192 bytes instead of 171). The sentence starting xml processing for hello has been replaced by Starting translation of file hello.tex. If the -silent option is given, information about configuration file is not printed on the terminal.

Raweb mode is entered if the type is ra. The type can be specified in the configuration file (the .tralics_rc file; we assume that either no configurationn file, or the standard configuration one will be used). If you call Tralics with option type=foo, then the type will be foo. Otherwise, if you call Tralics with option config=bar2005, and if bar2005.tcf exists, the type will be bar. Otherwise, if the file has \documentclass{gee2003}, and gee2003.tcf or gee.tcf exists, then the type will be gee; otherwise some default type will be used. The tcf file will be loaded, if given or deduced.

Let's assume that we have a file containing two lines, the first one is \documentclass{ra2003}, the second one is Hello, world! as above. Assume that the file has three names xhello.tex, hello2003.tex and hello2006.tex. All these files will be translated in Raweb mode. No XML file will be produced unless the four digits that appear in the document class are also in the file name, the is the case only for hello2003.

Example 7. We translate here file xhello.tex. Since the file name has no digits in it, you will get an error of the form Input file name must be team name followed by 2008. With version 2.8, the -verbose switch produces a great number of lines, explaining what happens (current version is less verbose).

grimm@medee$ tralics xhello -verbose
This is tralics 2.8, a LaTeX to XML translator
Copyright INRIA/MIAOU/APICS 2002-2006, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Starting xml processing for xhello.
Configuration file identification: standard $ Revision: 2.24 $
Read configuration file /user/grimm/home/cvs/tralics/.tralics_rc.
Configuration file has type \documentclass
Seen \documentclass ra2003
Potential type is ra2003
...
Configuration file identification: standard-ra $ Revision: 2.1 $
Read tcf file for type: ../confdir/ra.tcf
Using type ra
...
dtd is raweb from raweb3.dtd (mode RAWEB2006)
Fatal error: Please add 2006 in the name of the input file
Fatal_error for xhello
Say tralics --help to get some help

Example 8. You can use the option -year=2008; this sets a variable to be 2008; moreover, in Raweb mode, this can produce an error of the form Option -year=2008 incompatible with year in source file when used on the file hello2006. Even without this switch, the file will not compile, because of a mismatch between the year of the file, and that of the document class.

grimm@medee$ tralics hello2006
This is tralics 2.13.0, a LaTeX to XML translator, running on medee
Copyright INRIA/MIAOU/APICS 2002-2008, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Starting translation of file hello2006.tex.
Configuration file identification: standard $ Revision: 2.24 $
Read configuration file ../confdir/.tralics_rc.
Configuration file identification: standard-ra $ Revision: 2.4 $
Read tcf file ../confdir/ra.tcf
Illegal document class ra2003 should be ra2006

Example 9. Final test: we translate the file hello2003. Tralics version 2.8 uses a preprocessor that complains in case of unbalanced environments.

[2]grimm@medee$ tralics hello2003
This is tralics 2.8, a LaTeX to XML translator
Copyright INRIA/MIAOU/APICS 2002-2006, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Starting xml processing for hello2003.
Configuration file identification: standard $ Revision: 2.24 $
Read configuration file /user/grimm/home/cvs/tralics/.tralics_rc.
Configuration file identification: standard-ra $ Revision: 2.1 $
Read tcf file for type: ../confdir/ra.tcf
Error signaled at line 3:
Missing \end{document}.
Fatal_error for hello2003

Example 10. In version 2.10.7, the preprocessor is not called if the year is 2007 or greater (this is indicated by the line Simplified RA). Thus, we can copy hello2003 into hello2007, replacing 2003 by 2007 is the document class. Compilation succeeds.

grimm@macarthur$ tralics hello2007 -silent
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 hello2007.tex.
Read tcf file ../confdir/ra2007.tcf
Simplified RA
Translation done 
Output written on hello.xml (249 bytes).
No error found.
(For more information, see transcript file hello2007.log)
rahandler.pl v2.15, (C) 2004 2006 INRIA, Jos\'e Grimm, Team Apics
Postprocessor did nothing

Example 11. In version 2.13, both the preprocessor and postprocessors are removed. Note the following differences between examples 10 and 11. The line Simplified RA has been removed, as well as the two lines dealing with the postprocessor. There is a file ra2007.tcf but no file ra2003.tcf (because ra.tcf can be used instead). Finally, the class file ra2007.clt was added to the system after example 10 was run.

grimm@medee$ tralics hello2003
This is tralics 2.13.0, a LaTeX to XML translator, running on medee
Copyright INRIA/MIAOU/APICS 2002-2008, Jos\'e Grimm
Licensed under the CeCILL Free Software Licensing Agreement
Starting translation of file hello2003.tex.
Read tcf file ../confdir/ra.tcf
Document class: ra2003 2008/07/12 v1.0 Activity Report, Inria 2003
Output written on hello.xml (249 bytes).
No error found.
(For more information, see transcript file hello2003.log)

In Raweb mode, the magic line \AtBeginDocument{\rawebstartdocument} is executed. The effect of this command is to translate the metadata (name of the team, etc); it is defined by the class file. Our little file compiles because there is no \begin{document}. Translation is

<?xml version='1.0' encoding='iso-8859-1'?>
<!DOCTYPE raweb SYSTEM 'raweb7.dtd'>
<!-- Translated from latex by tralics 2.10.7, date: 2007/11/03-->
<raweb language='english' creator='Tralics version 2.10.7' year='2007'>
<p>Hello, world!</p>
</raweb>

2.3 Main document

We make here the following assumption: the document is named foo2003.tex, the document class is ra2003 (same year), and a configuration file specifying type RA is seen. In this case, RA mode is entered. Before 2007, there was a preprocessor, that did some checks, rearranged the code, etc. In what follows, we explain what happens with the example of 2003 and what is new in 2007 or 2008.

A first difference in 2007 is that you will not see fatal error, missing \project anymore (a normal error will be signaled instead when translating the start of the document). A well-formed configuration file is required. If you get a message like the following, please contact the raweb team.

Read tcf file ra2007.tcf
The configuration file for the RA is ra2007.tcf or ra.tcf
It must define a value for the parameter ur_vals
See transcript file apics2007.log for details
No xml file generated
Fatal_error for apics2007

2.3.1 The Configuration File

  DocType = raweb raweb7.dtd
  DocAttrib = year \specialyear
  DocAttrib = creator \tralics

This has as effect to define the preamble of the XML result file (see translation of example 10 above).

The file ra2008.tcf file contains also the following lines that defines five lists. The standard ra.tcf file contains additional lines (some TeX commands).

  theme_vals = "Com Cog Num Sym Bio"
  section_vals = "composition*/presentation*/fondements/domaine/logiciels/"
  section_vals = "+resultats/contrats*/international*/diffusion*/"
  ur_vals = "Rocquencourt//Sophia/Sophia Antipolis/Rennes//Lorraine//";
  ur_vals = "+RhoneAlpes/Rh\^one-Alpes/Futurs//"
  affiliation_vals ="Inria//Cnrs//University//ForeignUniversity//"
  affiliation_vals ="+Public//Other//"
  profession_vals = "Scientist//Assistant//Technical//PHD//"
  profession_vals = "+PostDoc//StudentIntern//Other//"

Since 2007, the English title associated to a (French) section name has been moved to the configuration file; it is given by fullsection_vals (that should be used instead of section_vals). As the following demontrates, you can put a string on more than one line, provided that the last character on the line is a backslash.

  fullsection_vals = "/composition/Team/presentation/Overall Objectives/\
     fondements/Scientific Foundations/domaine/Application Domains/\
     logiciels/Software/resultats/New Results/\
     contrats/Contracts and Grants with Industry/\
     international/Other Grants and Activities/diffusion/Dissemination"

The quantity theme_vals is a list of words, separated by spaces, converted to lower case. The quantity section_vals is a list of words, separated by slash characters, with possibly a star at the end. For all other variables of the form something_vals, it is a list of pairs, name and value, separated by slashes. If the value is omitted, the name is used instead. An initial plus sign means continuation. The final slash can be omitted; an initial slash is ignored.

The transcript file contains some lines, showing how Tralics interprets the configuration file. You might see the following lines.

theme_vals=Com Cog Num Sym Bio
Section: composition -> Team
Section: presentation -> Overall Objectives
Section: fondements -> Scientific Foundations
Section: domaine -> Application Domains
Section: logiciels -> Software
Section: resultats -> New Results
Section: contrats -> Contracts and Grants with Industry
Section: international -> Other Grants and Activities
Section: diffusion -> Dissemination
UR: Rocquencourt -> Rocquencourt
UR: Sophia -> Sophia Antipolis
UR: Rennes -> Rennes
UR: Lorraine -> Lorraine
+UR: RhoneAlpes -> Rh\^one-Alpes
UR: Futurs -> Futurs

2.3.2 Interpreting the Configuration File

Tralics has a command \tralics@get@config{X}{Y} that returns a value Z, according to the following rules.

2.3.3 The main document

\documentclass{ra2003}         %001
<Header>
\begin{document}               %016
\maketitle                     %019
<Modules>
\loadbiblio                    %488
\end{document}                 %489

Here, and in the examples that follow, blue numbers are the line numbers of the corresponding lines in the example file. Things like <Modules> are explained below. The \documentclass should be ra2006 for the year 2006.

Note. The two commands \maketitle and \loadbiblio exist for historic reasons. They are made equivalent to \relax in the class file.

2.3.4 The header

The header of the file is everything before \begin{document}. It should not produce any text. There is a free part and a required one, they can be intermixed. The free part contains definitions and \usepackage commands. We recommend to always use \newcommand instead of \def (do not follow the example). You should not load packages like french or babel, because the current language of the Raweb is English. For instance:

\usepackage{amsfonts}          %002
\usepackage{amsmath}
\def\CC{{\mathbb C}}           %009
\newcommand{\etc}{etc}
\def\corresp{manager}

\projet{MIAOU}{Miaou}{Mathématiques et 
     Informatique de l'Automatique et de l'Optimisation pour 
  l'Utilisateur}               %006
\theme{4a}                     %004
\isproject{YES} % \isproject{OUI} works also %005
\UR{\URSophia}                 %007

See Changes in 2007 and Changes in 2008 for some changes introduced for the RA2007 or RA2008. There are no fatal errors any more.

2.3.5 The Team Name and Properties

The \project command (it can be spelled as \projet) takes three arguments. The first argument is the name of the Team, the second argument is the short name of the Team (if empty, the lower case equivalent of the first argument is used). The third argument is the long name of the Team.

The \isproject command takes a boolean as argument (for instance, yes or oui means true; in fact, if the first letter is Y or O, the result is true, otherwise false). You should say yes if the Team is an official Project-Team, no otherwise.

The file name must be the the lowercase version of the first argument of \isproject. This was once a fatal error, but produces now an error of the form Package Raweb Error: Invalid Team name exezmple. We show below the test done in the package file. It uses the primitive \ra@jobname, it is like \jobname, but removes the directory part and final digits of the file to be translated, expansion is a list of tokens of category code 12.

  \edef\tmpB{\ra@jobname} % first arg of \project
  \def\tmpA##1{\lowercase{\xdef\tmpA{\detokenize{##1}}}}
  \expandafter\tmpA\expandafter{\ra@proj@a}
  \ifx\tmpA\tmpB \else\PackageError{Raweb}{Invalid Team name \ra@proj@a}{}\fi

2.3.6 The Theme

The \theme command takes as argument a Theme (Research Teams are grouped into themes, there is for instance a theme named ``Communicating systems'', with a sub-theme ``Distributed systems and software architecture''). Between 1996 and 2003, research themes were identified by a digit, between 1 and 4, followed by a letter; giving 4a as argument has as effect to insert in the HTML a link to the theme 4. The list of themes has since changed, as well as the Tralics behavior: it uses \tralics@get@config in order to fetch something from the configuration file. In case of error, Tralics may signal an error like
Invalid theme 4a
Valid themes are com cog num sym bio

2.3.7 The Localisation

The \UR command takes as argument a list of Research Units. The default configuration file shown above gives the list of valid names. In 2007 they are Rocquencourt, Sophia, Rennes, Lorraine, RhoneAlpes and Futurs. Before 2007, you had to say \UR{\URSophia} (for a team in a single UR) or \UR{\URFuturs\URSophia} for a team in two URs. This is still accepted, but the recommended syntax is now \UR{Sophia} (for a team in a single UR) or \UR{Futurs,Sophia} where the comma could be replaced by a space. The list is interpreted by \tralics@interpret@rc that can signal an error of the form:

Error signaled at line 22 of file exemple2006.tex:
Illegal localisation value: Saclay
Use one or more of: Rocquencourt Sophia Rennes Lorraine RhoneAlpes Futurs.

2.3.8 The Topics

Topics are defined if the ra package is called with option topic. Otherwise the two lines above are ignored as well as the optional argument of the module environment. Topics have been declared obsolete in 2007, so they exist only for compatibility reason, and no error is signaled anymore. Each topic has a name and a title. The name can be an optional argument of module (see the example, lines 79, 207 212 and 322.) Topics are handled via a call to \tralics@get@config{section}{XX}. See for instance the reports of isa 2003, isa 2004 or odyssee 2005.

2.3.9 Preprocessor Limitations

These errors are not signalled for the RA2007 that does not use the preprocessor.

Lines containing \theme etc, should not contain anything else after the arguments. Replacing the % line 5 by a _ will give this message

Error signaled at line 5:
Characters ignored at end of line
current line is  _ \isproject{OUI} works also
error is at position 1 at character _ (ascii 95).
Fatal_error for miaou2003

You cannot say \def\foo{YES}\isproject\foo, because the program looks for explicit braces. Example:

Error signaled at line 5:
Characters ignored before open brace
error signaled while scanning isproject
current line is \foo % \isproject{OUI} works also
error is at position 0 at character \ (ascii 92).
Fatal_error for miaou2003

In these messages, the `position' is relative to the current position; in the first case, it is the second character after the argument that causes problem (first character is space, thus OK), in the second case, it is the first character after the command that causes problem; Tralics does not print the characters already handled.

Before 2006, Tralics created file, named _hyperref.cfg, containing all the keywords in alphabetic order. You could see errors of the form

Error at line 107
Strange keywords 

meromorphic approximation, frequency-domain identification,
extremal problems {$(\max,+)$}

The participants environment should contain only \pers{}{}[] commands, separated by commas. In the current version of Tralics all tests done by the preprocessor have been removed, and the following error have become obsolete.

Error signaled at line 253:
Syntax error near `and \pers{xx}{yy}'

\pers{Jean-Paul}{Marmorat} and \pers{xx}{yy}.
Fatal_error for miaou2003

Error signaled at line 253:
Superfluous comma

\pers{Jean-Paul}{Marmorat},, \pers{xx}{yy}
\pers{Martine}{Olivi}[\corresp]
.
Fatal_error for miaou2003

The \pers command can be used in a participants or catperso environment. In one case, you must use commas as separators, in the other case, you cannot. In the current version, the comma after \pers is optional, so that you won't see

Error signaled at line 253:
There must be a comma between two \pers

\pers{Jean-Paul}{Marmorat}\pers{xx}{yy}
\pers{Martine}{Olivi}[\corresp]
.
Fatal_error for miaou2003

Error signaled at line 44:
Syntax error near `, \pers{x}{y}'
{Ph. D. Students}
\pers{David}{Avanessoff}[Fellow, INRIA], \pers{x}{y}.
Fatal_error for miaou2003

The distiction between environments participants and participants has been removed, there is no more

For the environment ending near line 191
please use `participant' or `participante' for the name,
as there is only one \pers in the list.
For the environment ending near line 253:
please use `participants' or `participantes' for the name,
as there are 2 \pers in the list.

The following error message was introduced in 2007, after removal of the preprocessor. You will not see anymore in 2008.

Error signaled at line 3095 of file apics2007.tex:
Text found in a mode where no text is allowed.
Only \pers commands should appear in a participants environment

2.4 Modules

A module is an environment, with some arguments: an optional topic reference (see above), and three required arguments (section, name, title). It is followed by an optional interface (formed of contributors, keywords, glossary, and moreinfo) and text. Since a module is essentially a \subsection, the text should contain only \subsubsection and \paragraph commands. The first module is special, we shall explain it later. The second module looks like this

\begin{module}{presentation}{presentation}{} %047
\begin{moreinfo}                             %048
The project was terminated June the 30th, 2003. 
A proposal for a new project named APICS has been submitted to the steering
committee of Inria Sophia Antipolis.
\end{moreinfo}
...
\end{module}                                 %076

It should be a small description of the main research objectives of the Team. You can use the moreinfo environment for emphasizes (in this example, to indicate that this is the last RA for the miaou Team). Historical note: Miaou has been effectively dissolved on 2003-31-12, was replaced by Apics on 2004-01-01, which became a Project on 2005-01-01.

The standard configuration file (see above) defines nine sections. The Raweb DTD associates to each section an English name, shown in parenthesis here. Since 2007, the names have been moved to the configuration file (see above)

The first argument of a module, the section, is handled by calling \tralics@get@config{fullsection}{#1} whose behavior is described above. If the command returns an empty string, the module is in the same section as the previous one. Otherwise it is a new section, and the command return its title T. In this case the previous (in any) is popped via \tralics@pop@section and a new section is created via \tralics@push@section{#1}. The title T will be added as an attribute to the element. There are many cases where the command may fail. We indicate here the original (fatal) error messages.

If the section name is not in the list, the error will be Invalid section Composition followed by Valid sections are composition presentation fondements domaine logiciels resultats contrats international diffusion. If the name of the section is empty (as in line 187), the previous section will be used. If there is no previous section, the error message is No default section

Note You can notice that the module starting at line 359 is in the section `resultats', but it comes after the modules of the section `contrats'. This is allowed by the preprocessor : modules are re-ordered. This feature is removed in 2007. You will see the error Bad section fondements after diffusion. Note that only one module is allowed in the first section. If this rule is disobeyed, you will see a message like Only one module accepted in composition.

Each module has a symbolic name, that can be used as a label. In the example, these names are en-tete, presentation, identif, chapeau, resonn, etc. Using the same name twice produces the error Class Raweb Error: Duplicate module: dif-anim that will be followed by Label 'mod:dif-anim' multiply defined (first use line 667 file exemple2006.tex). Trying to use special commands (for instance math formulas) can produce errors of the form unexpected element formula.

Finally a module has a title. In the example, three modules have no title: line 22, line 47, and line 183. As will be seen later, the composition section is special: it contains only one module whose title is ignored. In all other cases, Tralics tries to invent a title for the module. Before 2008, a complicated algorithm was used by the postprocessor. This could print messages like (SansTitre) Only one module seen in the section or There were 2 NoTitle handled. The current behavior is: If the ra package is loaded with option emptymodule, an error is signaled, otherwise (Sans Titre) is used.

2.5 Module Interface

A typical module should contain: contributors, keywords, a glossary, a ``moreinfo'' part and a body. In a section like `Overall objectives', you do not cite contributors (because you talk about the whole Team), and in a section like `Dissemination', you do not cite them either (in fact, names appear in the body of the module, for instance line 436 and line 470). In some cases, a module is split into submodules (technically \subsubsection), and contributors, keywords, etc, are associated to these submodules. As a consequence, Tralics does not check. You can put the meta-data wherever you want. Example

\begin{module}{}{calcul formel}{Software aspects of computer algebra}
  \begin{participants}
    \pers{Jean}[de]{La Fontaine}[1621-1695]
    \pers{Cecil Blount}{De Mille}
  \end{participants}
  \begin{motscle}
    mot1, mot2, mot3
  \end{motscle}
  \begin{glossaire}
    \glo{trick}{the thing which makes go the thingummy}
    \glo{BabelFish}{the translator of the previous sentence}
  \end{glossaire}
  \begin{moreinfo}
    This work was sponsored by all the sponsors
  \end{moreinfo}
  This is the body of the module.
\end{module}

The ``moreinfo'' part is technically a moreinfo environment. It is formed of a short paragraph (of the form: `this work done in collaboration with X').

The keywords meta-data are indicated by the motscle environment; examples are given at line 104, line 136, line 193, line 202, and line 225. The environment contains a comma separated list of keywords. The last example shows how to put commas into a keyword.

A glossary is a glossaire environment in which you can put \glo commands; they take two arguments: a word and its description. There is a dummy example line 475. In the current version, there is no possibility to make a reference to the items of the glossary.

A contributors list is given by a participants environment. Since 2008, this produces a <participants> element. For compatibility reasons with the initial (French) version, you can use participant, participante or participantes. If the ra package is called with option participant, then the name of the element is the name of the environment. Inside the environment, empty lines are ignored and \pers is defined to be \persA. Examples are line 094, line 126, line 189, line 219, line 233, line 243, line 250, line 265, and line 274.

2.6 First Module

2.6.1 Original syntax

The first section contains a single module, for instance, the one starting at line 22. Its name is useless. It should contain only catperso environments (but this is not checked). Examples are line 24, line 28, line 32, line 36, and line 40. Each such environment has a title, and contains a list of names, like the participants environment, without commas.

The syntax of the \pers command is the same, be it for participant and catperso (see paragraph 2.6.2 for changes introduced in 2006). There are two required arguments (first name and last name) and an optional field. In the first module, you may indicate that some contributor has a grant from Inria, or whatever, and for non permanent people, you indicate their arrival, and departure (as in line 43); this information is not repeated. If a collaboration is done with a person from the X university, you indicate it, for instance like in line 97; this information should be repeated, since it does not appear in the first module. Finally, in the software section, you flag the main contact.

In the example above, we cited two famous people: Jean de la Fontaine and Cecil B. De Mille. The first one should be sorted alphabetically with the letter L, and the other with D. This is indicated by putting brackets around the particle. This is now obsolete: you should say \pers{Jean}{de la Fontaine} and \pers{Cecil B.}{De Mille}.

2.6.2 The 2006 semantics

In 2006, the syntax of \pers changed. The \persA command is the one described above, it has four arguments, first name, optional particle, last name, optional moreinfo. The new command is called \persB, it takes seven arguments. The new arguments are CR, profession, affiliation, HDR. The CR argument was introduced in 2007, is is described in section 2.6.3.

The profession and affilation arguments must be used after the last name, before the optional moreinfo. The value is restricted to what is defined by the configuration file. The HDR argument is optional, it should be placed after everything else. An non-empty value means that the person has a Thèse d'état or a Habilitation à diriger les Recherches. This is only useful for Inria's Staff. The Raweb Web page provides additional information concerning the profession and affilation arguments.

\begin{catperso}{Ph. D. Students}
\pers{Jean}{Dupond}{Scientist}{Inria}
\pers{Jean}{Dupont}{Assistant}{Cnrs}[][yes]
\pers{Jean}{Durand}{Technical}{University}[][]
\pers{Jean}{Dumat}{StudentIntern}{Other}[bla bla ][no]
\pers{Jean}{Durant}{PHD}{ForeignUniversity}[with a T]
\pers{Jean}{Dumas}{PostDoc}{Public}[with a S][scheduled november 2007]
\pers{Jean}{Dumont}{ Other }{Other}[bla bla ][no]
\end{catperso}

2.6.3 The 2007 changes

Topics have become obsolescent. This means that Tralics recognises the syntax, but ignores all values.

A new feature has been added: the start of the document optionally contains a line of the form \TeamHasHdr{yes}. A true value means: at least one staff member has a Hdr (see discussion about the \pers command). This feature has been removed in 2008.

The following three lines are equivalent; they say that the team is located in both Rocquencourt and Sophia. Recall that `UR' stands for Unité de Recherche (Research Unit), and this is nowadays called Research Center.

\UR{\URRocquencourt\URSophia }
\UR{Rocquencourt,Sophia }
\ResearchCentreList{Rocquencourt,Sophia}

Since 2007 you must indicate, for every staff member, its localisation (Rocquencourt or Sophia, in the example above). This is done by adding an optional argument to the \pers command. Of course, the optional argument is required only if the RC list has more than one element. Example

\begin{catperso}{Team Leader}
\pers{Laurent}{Baratchart}[Sophia]{Chercheur}{INRIA}[DR Inria][Habilite]
\end{catperso}

In the example that follows, the equals sign says that Sophia becomes the default value (so that there is no need to repeat it).

\begin{catperso}{Reserch scientists (external)}
  \pers{Jean}{Louchet}[=Sophia]{Chercheur}{INRIA}[CR]
  \pers{Jean-Marie}{Rocchisani}{Chercheur}{UnivFr}[Université Paris XIII]
\end{catperso}

2.6.4 The 2008 changes

Remember that the \pers command comes in two versions \persA and \persB; these are defined in the ra package file, and the document class (raXXXX.clt) loads the package with some options that define the behavior of \pers. As explained above, \pers is \persA in a participants environment. It is also \persA before 2006. If option composition is given it is \persB in the composition environment, undefined otherwise. Without the option it is \persB.

Remember that \persB should be used in the catperso environment; this has been removed in 2008. This gives the following rule: the first section should contain a single module, describing the Team composition; it should contain only \pers commands of the type \persB.

The ra2008 class loads the ra package with option 'composition'. As said above, this makes \pers undefined, unless in environment participants or composition. This environment is new in 2008. It replaces the first module. This means

\begin{composition}
  \pers{Christine}{Eisenbeis}{Chercheur}{INRIA}[Team Leader (CR) Inria][Habilite]
  \pers{Nathalie}{Gaudechoux}{Assistant}{INRIA}[Secretary (SAR) Inria]
  \pers{François}{Thomasset}{Chercheur}{INRIA}[Research Director (DR) Inria]
  \pers{Jean}{Louchet}{Chercheur}{AutreEtablissementPublic}[Ing. en chef Armement (CR)]
  \pers{Jean-Marie}{Rocchisani}{Chercheur}{UnivFr}[Université Paris XIII]
  \pers{Moussa}{Lo}{Visiteur}{UnivEtrangere}[AUF Grant/ Gaston Berger University, 
    Saint-Louis, Senegal, from March 1st till August 31 2008]
\end{composition}

2.7 References

Our example contains line 92 a \label that is referenced at line 329. This label is associated to a section (starting at line line 90). You can also associate a label with an equation (line 141) or a figure (line 304) (note that the label has nothing to do with the \caption that follows; references to the figure will be correct after translation, but incorrect if LaTeX is called directly).

You can reference a module via \moduleref[y]{p}{s}{name}, there is an example line 330 and some more at line 410. The effect is the same as \ref{mod:name}. This command is considered obsolete, and using empty name, or the optional argument is not guranteed to work anymore.

In the bibliography, you can add a url field, like this one. We provide the \rrrt command: its argument is the number of a Inria Research report. Example here.

It is also possible to give the doi: in this example, indicating the doi= is the same as the xxurl, without the xx.

2.8 Bibliography

2.8.1 Bibliography: the raweb case

A reference from the main file miaou2003.bib appears in the bibliography if it is cited via \cite (there is an example line 122) or via \nocite (example line 246) or if the \nocite{*} has been issued (example line 20). The example file contains an instance of each of the standard bibtex entries, with all the required and optional fields, named std1 to std13, with two famous authors.

The main bibliography should contain only references of the Team in the current year (in exceptional circumstances, you have to right to put \toappear in the note field, if the entry is to appear really soon now).

Entries from miaou_refer2003.bib can be referred to in the same way, there is an implicit \nocite{*}, so that the whole database is included. The miaou_refer2003.bib should contain the ten most important published papers (or books) of the team.

Reference to other bibliography entries (not from the team, not from the current year, or not one of the most important publications of the team) can be made, provided that the entry is in miaou_foot2003.bib, and you use the command \footcite (there is an example line 122).

2.8.2 Bibliography: the general case

Normally, you say \cite{foo,bar}, and this makes two references to some bibliographic entries, defined by \bibitem{foo} and \bibitem{bar}. Very often, an external program, bibtex, is used to compute the list of these \bibitem and their content, using the argument of the \bibliography command as the list of the database files to look at. The output of bibtex is put in the file miaou2003.bbl, it contains essentially one thebibliography environment (more than one in the raweb case), and lots of \bibitem{foo} commands. The content of these is defined by the current bibliography style, the value of the argument of the \bibliographystyle command.

The default behavior of Tralics is not to call bibtex, but to compute and translate an intermediate file, say miaou2003_.bbl (note the underscore), that is equivalent to the miaou2003.bbl file produced by bibtex. It contains no thebibliography environment, but a lot of \citation commands (that are in reality environments, since they are explicitly terminated by an \endcitation command). This file is translated (in case of errors while translating the bibliography, line numbers refer to this file). An example is given under \citation.

The result is independent of any bibliographystyle. It contains commands of the form \cititem{btitle}{title of the book}. If the command \cititem-btitle is defined, it will be called with 'title of the book' as argument. It can also contain commands as \bauteurs and \beditors, that take as argument a list of \bpers commands. All these commands can be redefined, they are independent of commands used elsewhere.

The bibliography is translated at the end of the run, when the list of all citations is found. The result is a <biblio> element (the name can be changed, via the configuration file, using something like xml_biblio = "Biblio"). This element is inserted in the XML tree at the end. If you use the \bibliography command, the first occurrence of it defines the location (bibtex complains if more than one \bibliography is issued, but Tralics is happy with more than one). You can also use \insertbibliohere, this command has precedence over everything else.

Assume that the configuration file contains a line with bibtex_fields = "firstpage lastpage". The effect of this line is to tell Tralics to read also the fields firstpage and lastpage and to include them in the bbl file as \cititem{firstpage}{50}. If the configuration file contains also bibtex_extension = "foo bar" then entry types foo and bar are recognised, together with the standard types.

2.8.3 Bibliography: extended syntax

The mechanism explained in §2.8.1 above works by extending the syntax of the \cite command. In any case, you can say \cite[foo][bar]{gee}, this means that you cite the reference 'gee', with the additional information 'bar' and type 'foo'. You can put more than one citation in the \cite command, for instance, you can say \cite[foo][bar]{gee1, gee2}. The additional information is applied to the first entry only, the type is for all of them. The important point is that a unique identifier is used, of the form 'citefoo:gee', this will later on be converted into a valid XML identifier, say bid44. The prefix disappears if it is 'year', or if it 'refer' and DRY is false (in particular, for versions up to year 2005).

The translation of a cite command, whatever the syntax, is of the form <cit rend='foo'> <ref target='bid44'> text </ref> </cit>, where the 'rend' attribute contains the value of the type (unless it is empty). One task of Tralics is to solve the citation, this means, check that there is a single element whose id is bid44. This could fail without warning if, for instance, you create a box, add the attribute to it, then either discard or duplicate the box. The solver is in general a <citation > element, but this is irrelevant for Tralics. On the other hand, if you contribute to the raweb, you have to follow some specific rules: in particular, the postprocessor will sort all citations, and show <cit> as [14], where the number is the index in the sorted list, so that only garbage will be seen if the solver is not a <citation>. In the same fashion, only 'foot', 'refer' or 'year' are valid types.

Since version 2.8 of Tralics, you can use \refercite and \yearcite when the type is 'refer' or 'year'. These functions, as well as \footcite, take one optional argument. All the three commands (plus \cite) call \cite@one, a command that takes three arguments: the type, the reference, additional information. See \cite@one for details. When there are more than one citations in the original command, some separators are added between the calls of \cite@one, see \footcite in one case and \cite for other cases.

There is a special hack, DRY (for distinguish-refer-year) introduced in version 2.8. If the configuration file specifies a value XX for distinguish_refer_in_rabib, or if Tralics is called with the switch -distinguish_refer_in_rabib=XX, then DRY mode is set to true if XX is true, to false is XX is false (and the assignment is ignored otherwise). The value of the configuration file is considered first, so that than an argument to the program has precedence.

If DRY is false, the default, then \cite[refer][]{x} and \cite[year][]{x} are the same, the same as \cite[][]{x}. If DRY is true, this is no more the case, and you should use \refercite. In any case, there is an implicit \nocite for all references of the file miaou_refer2006.bib. Note the following rules: for year 2006, the year field of an entry miaou2006.bib should be 2006, for miaou_refer2006.bib, it must exist, and be less than 2006; otherwise, you will get an error of the form: entry moved from refer to year with additional information: the year field of this entry is missing or the year field of this entry is invalid or if DRY is false and the year is 2006: it is from this year or finally it is unpublished.

Note: if DRY is true, you can put the same entry (with the same key, and the same value) in both files; then miaou2006.bib should contain all references of the year 2006 of the team, and miaou_refer2006.bib contains (at most ten) major publications of the team (of course, all of these major publications should be published). However, if DRY is false, you cannot put the same entry in both files, so that miaou_refer2006.bib cannot contain entries of 2006.

2.8.4 Bibliography: more hacks

There are different ways to put solve an entry. For instance \xbox {foo} {\XMLsolvecite [] [foot] {toto} {text}} solves the entry associated to \footcite{toto}. You can also use \bibitem[xx]{toto], that solves the entry with a <citation>. These commands are described under \XMLsolvecite. Otherwise, you can use an external program that get all data from one or more bibliography databases.

Tralics interprets the argument of the \bibliographystyle command as follows. If it is 'bibtex:foo', this means that bibtex should be called with 'foo' as style. If it is 'bibtex:', then bibtex should be called with the default style. If it is 'program:foo', this means that the program foo shall be called. Otherwise, the argument becomes the default style. Example

 
\documentclass{article}
\begin{document}
\AtEndDocument{\bibitem{unused}Hey}
\bibliography{torture}
\bibliographystyle{bibtex:}
\cite{poussin,cruz,many,strange,unused}
\end{document}

 
\citation{poussin}
\citation{cruz}
\citation{many}
\citation{strange}
\bibstyle{plain}
\bibdata{torture}

It is assumed that the external program will create a bbl file, that is read and interpreted by Tralics. We assume that if anything goes wrong the external program signals an error, so that Tralics does no further checks. We also assume that translation of the resulting file will not add any unsolved reference (this is an error that reads Citation after loading biblio?).

If no external program is given, Tralics will read the database files, and construct a bbl. If an entry 'gee' is seen in a file of type 'foo', its key will be transformed into 'foocite:gee'. The same algorithm as above is used; 'year' disappears, 'refer' is the same as 'year', depending on the DRY, and 'foot' is left unchanged. In the current version only these three types are handled, extension is planned. If the argument of the \bibliography is 'foo+bar.bib', and if this file does not exist, then 'foo.bib' will be used, with type 'bar'. Given the following command \newcommand \usebib[2] {\bibliography{#1#2, #1_foot#2+foot, #1_refer#2+refer}}, you can say \usebib{miaou}{2003}, if you want to mimic what Tralics does for the RA2003 (of course, the equivalent of this command is executed implicitly in raweb mode). A simple warning no biblio file foo is printed if the database cannot be opened. It is possible to insert a database more than once, provided that no entry is solved twice, i.e., in the case where the whole data base is ignored.

2.8.5 Bibliography: reducing entropy

A new feature was introduced in 2006, it allows the use of a single data base instead of three different ones. On one hand, this means that if the argument of the \bibliography is 'foo+bar.bib', and if this file does not exist, then 'foo.bib' will be used, with type 'bar', where 'bar' is one of 'foot', 'refer', 'year' or 'all'. On the other hand, for the raweb 2006, if the file miaou_all2006.bib exists, it will be loaded, otherwise, the three files miaou2006.bib, miaou_refer2006.bib and miaou_foot2006.bib will be read.

When Tralics reads the file miaou_all2006.bib, and sees an entry, say `Knuth', it considers it as solving \cite{Knuth}, \refercite{Knuth} or \footcite{Knuth}. In general, a single alternative is chosen, but explained above, it is allowed to use both \cite{Knuth} and \refercite{Knuth}.

What happens if you say \nocite{*}? One possibility would be to insert the whole data base thrice (as foot, refer and year), a second possibility would be to insert it once, but not as year, neither as refer. Hence, the only logical solution: the behavior is the same as before version 2.9.3. If you say \nocite{*}, all entries from miaou2006.bib are included, by defaut all entries from miaou_refer2006.bib are included. As a consequence, an entry from miaou_foot2006.bib or miaou_all2006.bib is included only if explicitly cited. This can be done via \nocite[foot]{Knuth} or \nocite[refer]{Knuth} if the reference should have type `foot' or `refer'.

Important note. Assume that you say \cite{Knuth} and \footcite{knuth}, but no other variants like KNUTH of KNuth, etc. It is possible to have two files miaou2006.bib and miaou_foot2006.bib with the entry `Knuth'. When the second data base is read, then `Knuth' will solve `knuth' (assuming that the data base does not contain any variants like KNUTH, etc.) However, if you merge these two files in a single one, you will be in trouble: `Knuth' will solve \cite{Knuth}, and no tentative is made for variants; in this case the data base must contain `knuth' that solves \footcite{knuth}.

3. Running the programs

Options to the Tralics program can be found on a separate page. Some of them have been removed in 2008, there description can be found here, where we explain the different strategies that could be used to produce the Raweb before 2008.

4. The auxiliary perl script

5. The fotex.cfg file

6. The raweb-cfg.sty file

The pdf files of the activity report are produced via a Makefile as follows. The TeX source is converted by Tralics into some XML file; an XML processor converts this into another XML file, conforming to the new DTD (whatever this means). Another XML processor converts the result into XSL/FO format, which is interpreted by TeX via the tools of S. Rahtz and D. Carlisle. Some patches to these files are required, they are described here.