NAME
rubber - un système de compilation de documents LaTeX
SYNOPSIS
rubber [options] sources ...
rubber-pipe [options]
Rubber est un emballage autour de LaTeX est des programmes associés.
Son but est, étant donné un fichier source LaTeX, de le compiler tant
que nécessaire et d’exécuter des programmes annexes comme BibTeX,
makeindex, Metapost, etc. pour produire des fichiers de données si
besoin est.
La commande rubber construit complètement les documents spécifiés. Les
sources passés en argument peuvent être des sources LaTeX (auquel cas
le suffixe .tex peut être omis), ou des fichiers dans un format que
Rubber sait traduire vers LaTeX (pour le moment, cela signifie un
source CWEB ou Literate Haskell). Si une compilation échoue,
l’ensemble du processus est interrompu, y compris la compilation des
documents suivants sur la ligne de commande, et rubber renvoie un code
de retour non nul.
La commande rubber-pipe fait la même chose avec un seul document, mais
le source LaTeX est lu sur l’entrée standard et le document compilé est
envoyé sur la sortie standard.
Certaines informations ne peuvent pas être extraites du source LaTeX.
C’est le cas par exemple des chemins d’accès aux fichiers (qui peuvent
être spécifiés par les variables d’environnement comme TEXINPUTS), ou
encore le style d’index à utiliser avec Makeindex. Pour remédier à ce
problème, il est possible d’ajouter de l’information pour Rubber dans
les commentaires des sources LaTeX, voir pour cela la section
DIRECTIVES.
OPTIONS
Les options servent soit à choisir l’action à effectuer, soit à
configurer le processus de compilation. Elles sont essentiellement les
mêmes pour rubber et rubber-pipe. Les options sont lues selon les
conventions à la GNU Getopt.
--cache
Utiliser le système (expérimental) de cache. Cette fonction
utilise un fichier rubber.cache dans le répertoire courant pour
stocker le résultat de l’analyse des sources, de sorte que les
compilations suivantes sont accélérées.
--clean
Efface tous les fichiers produits par la compilation au lieu de
construire le document. Cette option n’est présente que dans
rubber. Elle considère la compilation qui aurait eu lieu avec
les autres arguments, c’est-à-dire que « rubber --clean toto »
n’effacera pas toto.ps, alors que « rubber --ps --clean toto »
le fera.
-c, --command <commande>
Exécute la commande (ou directive) spécifiée avant d’analyser
les sources. Voir la section DIRECTIVES pour plus de détails.
-e, --epilogue <commande>
Exécute la commande (ou directive) spécifiée aprs l’analyse des
sources. Voir la section DIRECTIVES pour plus de détails.
-f, --force
Force au moins une compilation du source. Ceci peut être utile,
par exemple, si une dépendance inhabituelle a été modifiée (par
exemple un package dans un répertoire système).
-z, --gzip
Compresse le document final (au format gzip). Cette option
équivaut à écrire -o gz après toutes les autres options.
-h, --help
Affiche la liste de toutes les options disponibles et quitte.
--inplace
Va dans le répertoire du fichier source avant la compilation, de
sorte que les fichiers produits arrivent au même endroit que les
sources.
--into <rpertoire>
Va dans le répertoire spécifié avant la compilation, de sorte
que les résultats de compilation y soient produits, au lieu
d’être placés dans le répertoire courant.
-k, --keep
Cette option est utile dans rubber-pipe uniquement. Avec cette
option, les fichiers temporaires ne seront pas effacés après la
compilation du document et l’envoi du résultat sur la sortie
standard. Le document temporaire est nommé rubtmpX.tex, où X
est un nombre tel qu’aucun fichier de ce nom n’existe au départ.
-l, --landscape
Produit un document orienté en paysage. Cette option n’a
d’effet qu’avec dvips et dvipdfm.
-n, --maxerr <num>
Définit le nombre maximum d’erreurs affichées. Par défaut, au
plus 10 erreurs sont rapportées, l’option -n -1 les affiche
toutes.
-m, --module <module>[:<args>]
Utilise le module spécifié en plus des packages du document.
Des arguments peuvent être passés au module en les ajoutant
après un signe deux-points, ils correspondent aux options du
package dans LaTeX. Le module est chargé avant l’analyse du
document.
--only <sources>
Compile le document partiellement, en n’incluant que les sources
spécifiés. Le fonctionnement consiste à ajouter un appel à
\includeonly sur la ligne de commande. L’argument est une liste
de noms de fichiers séparés par des virgules.
-o, --post <module>[:<args>]
Utilise le module spécifié en tant que post-processeur. Cette
option est similaire à -m mais elle charge le module aprs
l’analyse du document.
-d, --pdf
Produit un document PDF. Si cette option apparaît après --ps
(par exemple sous la forme -pd) elle est synonyme de -o ps2pdf,
sinon elle agit comme -m pdftex, pour compiler avec pdfLaTeX au
lieu de LaTeX.
-p, --ps
Traite le fichier DVI obtenu après compilation avec dvips(1)
afin de produire un document PostScript. Cette option est
synonyme de -o dvips, elle ne peut pas être utilisée après
--pdf.
-q, --quiet
Diminue la quantité de messages affichés. C’est l’inverse de
-v.
-r, --read <fichier>
Lire des directives supplémentaires dans le fichier spécifié
avant l’analyse des sources (voir aussi la directive « read »).
-s, --short
Formate les messages d’erreur de LaTeX de façon compacte (une
erreur par ligne).
-I, --texpath <rpertoire>
Ajoute le répertoire spécifié au chemin de recherche de fichiers
de TeX.
-v, --verbose
Incrémente le degré de détail dans les messages affichés. Les
niveaux existants vont de 0 à 4, le niveau par défaut est 1 pour
rubber et 0 pour rubber-pipe. Attention, dire -vvv rend Rubber
très bavard.
--version
Affiche le numéro de version et termine.
-W, --warn <type>
Rapporter les avertissements d’un type donné, s’il n’y a pas eu
d’erreur de compilation. Les types disponibles sont: boxes
(boîtes mal construites), refs (références non définies ou
définies plusieurs fois), misc (les autres messages) et all pour
rapporter tous les messages.
MODULES
L’action de Rubber est influencée par des modules. Les modules
s’occupent des fonctionnalités de packages et de programmes
auxiliaires.
Packages
Pour chaque package qu’un document utilise, Rubber recherche un module
de même nom pour effectuer les opérations que ce package peut
nécessiter en plus de la compilation par LaTeX. Des modules peuvent
être ajoutés à ceux fournis par défaut pour ajouter de nouvelles
fonctionnalités (c’est d’ailleurs un intérêt du système modulaire).
Les modules standard sont les suivants:
beamer Ce module s’occupe des fichiers .head de Beamer de la même façon
que pour les autres tables des matières.
bibtex S’occupe de traiter la bibliographie du document avec BibTeX
lorsque c’est nécessaire. Ce module est chargé automatiquement
lorsque le document contient la macro \bibliography (voir aussi
dans DIRECTIVES pour les options).
combine
Le package combine sert à rassembler plusieurs documents LaTeX
en un seul, et ce module s’occupe de gérer les dépendances dans
ce cas.
epsfig Ce module gère l’inclusion de figures pour les documents qui
utilisent l’ancienne méthode avec \psfig. Il s’agit en fait
d’une interface pour le module graphics, voir celui-ci pour les
détails.
graphics, graphicx
Ces modules identifient les fichier graphiques inclus par le
document et de les considèrent comme des dépendances à la
compilation. Ils utilisent en plus certaines règles pour
construire ces fichiers. Voir la documentation en info pour
plus de détails.
hyperref
S’occupe des fichiers supplémentaires que produit ce package
dans certains cas.
index, makeidx
Traite l’index (ou les index) du document avec makeindex(1)
lorsque c’est nécessaire (voir dans DIRECTIVES pour les
options).
minitoc, minitoc-hyper
Lors du nettoyage, supprime les fichiers supplémentaires
produits pour la construction de tables des matières partielles.
moreverb, verbatim
Ajoute les fichiers inclus par \verbatiminput et les macros
similaires à la liste des dépendances.
multibib
S’occupe des bibliographies supplémentaires créées par ce
package, et efface les fichiers associés lors du nettoyage.
natbib Peut lancer une compilation supplémentaire pour résoudre des
références.
xr Ajoute les fichiers .aux utilisés pour les références externes à
la liste des dépendances, afin que la compilation ait lieu
lorsque les documents externes sont modifiés.
Pré-traitements
Les modules suivants sont fournis pour l’utilisation de programmes qui
produisent un source LaTeX à partir de formats différents:
cweb Ce module sert à exécuter cweave(1) si nécessaire avant le
processus de compilation pour produire le source LaTeX. Ce
module est chargé automatiquement si le fichier spécifié sur la
ligne de commande a .w pour suffixe.
lhs2TeX
Ce module utilise le préprocesseur lhs2TeX pour produire le
source LaTeX à partir d’un programme en Literate Haskell. Il
est utilisé automatiquement si le nom du fichier d’entrée se
termine par .lhs.
Traitement après compilation
Les modules suivants sont fournis pour effectuer diverses
transformations après la compilation. L’ordre dans lequel ces modules
sont utilisés est important, par exemple pour effectuer une série de
transformations comme
toto.tex → toto.dvi → toto.ps → toto.pdf → toto.pdf.gz
il faut charger les modules dvips, ps2pdf et gz dans cet ordre, par
exemple avec la ligne de commande
rubber -p -o ps2pdf -z toto.tex
dvipdfm
Lance dvipdfm(1) à la fin de la compilation pour produire un
document PDF.
dvips Lance dvips(1) à la fin de la compilation pour produire un
document PostScript. Ce module est aussi chargé par l’option de
ligne de commande --ps.
expand Produit un source LaTeX à partir du document principal, en
remplaçant les macros \input par les fichiers inclus, les macros
de bibliographies par la bibliographie produite par bibtex(1),
et les classes et packages locaux par leur source. Si le
fichier principal est foo.tex, le fichier développé sera nommé
foo-final.tex. Voir la documentation en info pour plus de
détails.
gz Produit une version du document final compressée avec gzip(1).
ps2pdf Lorsque la compilation produit un document PostScript (par
exemple en utilisant le module dvips), convertit ce document en
PDF avec ps2pdf(1).
Choix du compilateur
Les modules suivants servent à changer de compilateur LaTeX:
aleph Utilise Aleph au lieu de TeX, c’est-à-dire compile le document
avec lamed(1) au lieu de latex.
etex Indique à Rubber d’utiliser elatex(1) au lieu de latex pour
compiler le document.
omega Utilise Omega au lieu de TeX, c’est-à-dire compile le document
avec lambda(1) au lieu de latex. Si le module dvips est
utilisé, il transformera le DVI avec la commande odvips(1).
Notez que si le package omega est utilisé par le document, ce
module sera chargé automatiquement.
pdftex Indique à Rubber d’utiliser pdflatex(1) au lieu de latex pour
compiler le document. Par défaut, cela a pour effet de produire
un fichier PDF au lieu d’un DVI, mais si le module est chargé
avec l’option dvi (par exemple en disant -m pdftex:dvi) le
document est compilé en DVI par pdflatex. Ce module est aussi
chargé par l’option de ligne de commande --pdf.
vtex Indique à Rubber d’utiliser le compilateur VTeX. Par défaut la
commande vlatex est utilisée, pour produire une sortie en PDF.
Avec l’option ps (par exemple en disant « rubber -m vtex:ps
toto.tex ») le compilateur utilisé sera vlatexp et le résultat
sera un fichier PostScript.
DIRECTIVES
Le fonctionnement automatique de Rubber se base sur la recherche de
macros dans les sources LaTeX. Dans les cas où ce mécanisme n’est pas
suffisant, il est possible d’ajouter des directives dans les
commentaires des sources. Une directive est une ligne de la forme
% rubber: cmd args
La ligne doit commencer par un signe « % » puis une suite quelconque de
« % » et d’espaces, puis le texte « rubber: » suivi d’espaces et d’un
nom de commande, éventuellement suivi d’espaces et d’arguments. Les
commandes disponibles sont les suivantes:
Directives générales
alias <nom1> <nom2>
Déclare la macro LaTeX nom1 comme équivalente à nom2. Ceci peut
être utile quand on définit une macro personnelle autour d’une
macro connue de Rubber.
clean <fichier>
Indique que le fichier spécifié doit être effacé lors du
nettoyage par --clean.
depend <fichier>
Considère le fichier spécifié comme une dépendance à la
compilation, sa date de modification sera vérifiée.
make <fichier> [<options>]
Déclare que le fichier spécifié doit être produit. Les options
permettent de spécifier la façon de le produire: from <fichier>
indique le nom du fichier source, with <rgle> indique la règle
de conversion à employer. Par exemple, « make toto.pdf from
toto.eps » indique que toto.pdf doit être produit à partir de
toto.eps, avec n’importe quelle règle susceptible de le faire.
Voir la documentation info pour plus de détails sur la
conversion de fichiers.
module <module> [<options>]
Charge le module spécifié, éventuellement avec des options.
Cette directive est équivalente à l’option de ligne de commande
--module.
onchange <fichier> <commande>
Exécute la commande shell spécifiée après la compilation lorsque
le contenu du fichier spécifié a changé. Le nom de fichier se
termine au premier espace sur la ligne.
paper <options>
Spécifie des options relatives à la taille du papier. Pour le
moment, ces options sont passées sous forme d’options -t à dvips
ou -p à dvipdfm.
path <rpertoire>
Ajoute le répertoire spécifié au chemin de recherche de TeX (et
de Rubber). Le nom du répertoire est tout le texte qui suit les
espaces après « path ».
read <fichier>
Lit le fichier de directives spécifié. Le fichier doit
comporter une commande par ligne. Les lignes vides ou
commençant par un « % » sont ignorées.
rules <fichier>
Lit des règles de conversion supplémentaires dans le fichier
spécifié. Ce fichier doit être au même format que le fichier
rules.ini, voir la documentation info pour plus de détails.
set <nom> <valeur>
Définit la variable nom avec la valeur spécifiée. Pour plus
d’informations sur les variables, voir la documentation en info.
watch <fichier>
Surveille les modifications sur le fichier spécifié. Si le
contenu de ce fichier change lors d’une compilation, une
nouvelle compilation est déclenchée. Ce mécanisme est utile par
exemple pour les tables des matières.
Directives spécifiques aux modules
Si une commande est de la forme toto.tutu, elle est considérée comme
une commande tutu pour le module toto. Si ce module n’est pas encore
enregistré lorsque la directive est rencontrée, la commande est
simplement ignorée. Pour les modules standard, les directives sont les
suivantes:
bibtex.path <rpertoire>
Ajoute le répertoire spécifié au chemin de recherche de bases de
données BibTeX (fichiers .bib).
bibtex.sorted <boolen>
Si l’argument est true, yes ou 1, déclare que la bibliographie
est triée (c’est le comportement par défaut), sinon déclare que
les citations apparaissent dans l’ordre du texte, ce qui peut
nécessiter plus d’appels à bibtex.
bibtex.stylepath <rpertoire>
Ajoute le répertoire spécifié au chemin de recherche de styles
BibTeX (fichiers .bst).
dvipdfm.options <options>
Passe les options de ligne de commande spécifiées à dvipdfm.
dvips.options <options>
Passe les options de ligne de commande spécifiées à dvips.
index.tool (index) <name>
Spécifie l’outil à utiliser pour traiter l’index. Les choix
possibles sont actuellement makeindex(1) (valeur par défaut) et
xindy(1). L’argument index est optionnel, il peut être utilisé
pour spécifier la liste des index auxquels s’applique la
commande. S’il est présent, il doit être placé entre
parenthèses et la liste est séparée par des virgules. Si
l’argument est absent, la commande s’applique à tous les index.
index.language (index) <langues>
Sélectionne la langue à utiliser pour trier l’index. Ceci ne
s’applique que si l’outil utilisé est xindy(1). L’argument
optionnel a la même signification qu’au-dessus.
index.modules (index) <module>...
Spécifie quels modules utiliser lors du traitement de l’index
par xindy(1). L’argument optionnel a la même signification
qu’au-dessus.
index.order (index) <options>
Modifie les options de tri de l’index. Les arguments dont des
mots (séparés par des espaces) parmi « standard », « german »,
« letter ». L’argument optionnel a la même signification qu’au-
dessus.
index.path (index) <rpertoire>
Ajoute le répertoire spécifié au chemin de recherche de styles
d’index (fichiers .ist). L’argument optionnel a la même
signification qu’au-dessus.
index.style (index) <style>
Spécifie le style d’index à utiliser. L’argument optionnel a la
même signification qu’au-dessus.
makeidx.order, makeidx.path, makeidx.style
Ces directives sont les mêmes que pour le module index, sauf
qu’elles n’acceptent pas l’argument optionnel.
BUGS
Il y en a surement quelques uns...
Cette page se rapporte à la version 1.1 de Rubber. Le programme et
cette documentation sont maintenus par Emmanuel Beffara
<manu@beffara.org>. La page web du programme se trouve à l’adresse
http://www.pps.jussieu.fr/~beffara/soft/rubber/.
VOIR AUSSI
La documentation complète de rubber est maintenue en tant que manuel en
Texinfo. Si les programmes info et rubber sont installés correctement
sur votre système, la commande
info rubber
devrait vous donner accès au manuel complet (en anglais).