Ubuntu Manpage: rubber - un système de compilation de documents LaTeX

NAME

       rubber - un système de compilation de documents LaTeX

SYNOPSIS

       rubber [options] sources ...
       rubber-pipe [options]

DESCRIPTION

Rubber est un emballage autour de LaTeX et des programmes associés. Son but est, à partir d’un fichier
source LaTeX, d’effectuer autant de compilations que nécessaire et d’exécuter des programmes annexes
comme BibTeX, makeindex, Metapost, etc. pour produire au besoin des fichiers de données.

La commande rubber construit complètement les documents spécifiés. Les fichiers traités 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. 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. Veuillez vous
reporter à 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 à la manière de
GNU Getopt.

-b, --bzip2
Compresse le document final (au format bzip2). Cette option équivaut à écrire -o bzip2 après
toutes les autres options.

--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 après 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 paquet dans un répertoire système). Cette option n’a
pas de sens pour rubber-pipe.

-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 résultats sont
produits au même endroit que les sources.

--into <répertoire>
Va dans le répertoire spécifié avant la compilation, de sorte que les résultats y sont produits,
au lieu d’être placés dans le répertoire courant.

--jobname <nom>
Spécifie le nom de travail (« job ») à utiliser. Ceci change le nom des fichiers produits et ne
s’applique qu’au premier document de la ligne de commande.

-k, --keep
Cette option n’a de sens qu’avec rubber-pipe. 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.

-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 paquets du document. Des arguments peuvent être passés au
module en les ajoutant après un signe deux-points, ils correspondent aux options du paquet 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 après 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, --src-specials
Active l’insertion de « specials » indiquant les positions dans le code source, si le compilateur
le permet. Cette option équivaut à fixer la variable src-specials à yes.

-s, --short
Formate les messages d’erreur de LaTeX de façon compacte (une erreur par ligne).

-I, --texpath <répertoire>
Ajoute le répertoire spécifié au chemin de recherche de fichiers de TeX.

--synctex
Autorise l’extension SyncTeX pendant l’exécution de LaTeX.

--unsafe
Permettre au document d’exécuter lancer des logiciels externes. Cette option est potentiellement
dangereuse, réservez-la à des documents provenant d’une source de confiance !

-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 les suivants. boxes (boîtes trop ou pas assez remplies), refs (références non
définies ou définies plusieurs fois), misc (autres messages) et all pour rapporter tous les
messages.

MODULES

L’action de Rubber est influencée par des modules chargés des paquets ou programmes auxiliaires.

Paquets
Pour chaque paquet qu’un document utilise, Rubber recherche un module de même nom pour effectuer les
opérations que ce paquet 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.

asymptote
Traite les fichiers .asy générés par le paquet LaTeX, puis déclenche une recompilation.

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, biblatex
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 DIRECTIVES
pour les options).

combine
Le paquet combine sert à rassembler plusieurs documents LaTeX en un seul. 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.

glossaries
Exécute makeglossaries et recompile quand le fichier .glo change.

graphics, graphicx
Ces modules identifient les fichier graphiques inclus par le document et 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 paquet dans certains cas.

index, makeidx, nomencl
Traite les index et nomenclatures du document avec makeindex(1) lorsque c’est nécessaire (voir
dans DIRECTIVES pour les options).

ltxtable
Ajoute une dépendance vers les fichiers insérés par le paquet LaTeX ltxtable.

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 paquet, et efface les fichiers associés
lors du nettoyage.

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

bzip2 Produit une version du document final compressée avec bzip2(1).

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

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

xelatex
Demande à Rubber d’utiliser xelatex(1) au lieu de latex.

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 <règle> 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.

path <répertoire>
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 ».

produce <fichier>
Informe Rubber que l’exécution de LaTeX crée ou modifie ce(s) fichier(s).

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.

setlist <nom> <valeurs>
Définit la variable nom avec la liste de valeurs spécifiée. Les valeurs sont séparées par des
espaces. Pour plus d’informations sur les variables, voir la documentation en info.

shell_escape
Marquer ce document comme nécessitant des logiciels externes (shell-escape ou write18). Rubber va
ne pas accepter cette option sauf quand l’option --unsafe est utilisée.

synctex
Autorise l’extension SyncTeX pendant l’exécution de LaTeX.

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:

biblatex.path <répertoire>
Ajoute le répertoire donné aux chemins dans lesquels BibTex cherche ses bases de données

bibtex.crossrefs <nombre>
Spécifie le nombre minimum de crossref requis pour l’inclusion automatique de l’entrée référencée
dans la liste de citations. Définit l’option -min-crossrefs lors de l’appel à bibtex(1).

bibtex.path <répertoire>
Ajoute le répertoire spécifié au chemin de recherche de bases de données BibTeX (fichiers .bib).

bibtex.stylepath <répertoire>
Ajoute le répertoire spécifié au chemin de recherche de styles BibTeX (fichiers .bst).

bibtex.tool <commande>
Utiliser un autre outil que BibTeX pour la bibliography.

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 et letter. Cette option n’a d’effet qu’avec makeindex(1). L’argument optionnel a
la même signification qu’au-dessus.

index.path (index) <répertoire>
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.language, .modules, .order, .path, .style, .tool
Ces directives sont les mêmes que pour le module index, mais n’acceptent pas d’argument optionnel.

multibib.crossrefs, .path, .stylepath, .tool
Ces directives sont les mêmes que pour le module bibtex mais elles s’appliquent aux bibliographies
gérées par le paquet multibib. Elles acceptent un argument initial optionnel, avec les mêmes
conventions que pour le module index, qui permet de spécifier la liste des bibliographies
auxquelles s’applique la commande.

BUGS

       Il y en a surement quelques uns...

       Cette page se rapporte à la version 1.6.7 de Rubber. Le programme et cette documentation  sont  maintenus
       par   Florian   Schmaus   <flo@geekplace.eu>.   La   page   web   du  programme  se  trouve  à  l’adresse
       https://gitlab.com/latex-rubber/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).

                                                                                                       RUBBER(1)