RUBBER
Section: User Commands (1)
Index
Return to Main Contents
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.0 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).
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- OPTIONS
-
- MODULES
-
- Paquets
-
- Pré-traitements
-
- Traitement après compilation
-
- Choix du compilateur
-
- DIRECTIVES
-
- Directives générales
-
- Directives spécifiques aux modules
-
- BUGS
-
- VOIR AUSSI
-
This document was created by
man2html,
using the manual pages.
Time: 21:47:14 GMT, May 23, 2024