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

Provided by: rubber_1.1+20100306-3_all

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

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

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

--jobname <nom>
Spécifie le nom de 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 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 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.

-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, nomencl
Traite les index et nomenclatures 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

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

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

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.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.sorted <booléen>
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 <répertoire>
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) <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.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.

multibib.crossrefs, .path, .sorted, .stylepath
Ces directives sont les mêmes que pour le module bibtex mais elles s'appliquent aux
bibliographies gérées par le package multibib. Elles acceptent un argument
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.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).

                                                                                        RUBBER(1)