RUBBER(1) General Commands Manual RUBBER(1) NAME rubber - un systeme de compilation de documents LaTeX SYNOPSIS rubber [options] sources ... rubber-pipe [options] DESCRIPTION Rubber est un emballage autour de LaTeX et des programmes associes. Son but est, a partir d'un fichier source LaTeX, d'effectuer autant de compilations que necessaire et d'executer des programmes annexes comme BibTeX, makeindex, Metapost, etc. pour produire au besoin des fichiers de donnees. La commande rubber construit completement les documents specifies. Les fichiers traites peuvent etre des sources LaTeX (auquel cas le suffixe .tex peut etre omis), ou des fichiers dans un format que Rubber sait traduire vers LaTeX. Si une compilation echoue, 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 meme chose avec un seul document, mais le source LaTeX est lu sur l'entree standard et le document compile est envoye sur la sortie standard. Certaines informations ne peuvent pas etre extraites du source LaTeX. C'est le cas par exemple des chemins d'acces aux fichiers (qui peuvent etre specifies par les variables d'environnement comme TEXINPUTS), ou encore le style d'index a utiliser avec Makeindex. Pour remedier a ce probleme, il est possible d'ajouter de l'information pour Rubber dans les commentaires des sources LaTeX. Veuillez vous reporter a la section DIRECTIVES. OPTIONS Les options servent soit a choisir l'action a effectuer, soit a configurer le processus de compilation. Elles sont essentiellement les memes pour rubber et rubber-pipe. Les options sont lues a la maniere de GNU Getopt. -b, --bzip2 Compresse le document final (au format bzip2). Cette option equivaut a ecrire -o bzip2 apres toutes les autres options. --clean Efface tous les fichiers produits par la compilation au lieu de construire le document. Cette option n'est presente que dans rubber. Elle considere la compilation qui aurait eu lieu avec les autres arguments, c'est-a-dire que << rubber --clean toto >> n'effacera pas toto.ps, alors que << rubber --ps --clean toto >> le fera. -c, --command Execute la commande (ou directive) specifiee avant d'analyser les sources. Voir la section DIRECTIVES pour plus de details. -e, --epilogue Execute la commande (ou directive) specifiee apres l'analyse des sources. Voir la section DIRECTIVES pour plus de details. -f, --force Force au moins une compilation du source. Ceci peut etre utile, par exemple, si une dependance inhabituelle a ete modifiee (par exemple un paquet dans un repertoire systeme). Cette option n'a pas de sens pour rubber-pipe. -z, --gzip Compresse le document final (au format gzip). Cette option equivaut a ecrire -o gz apres toutes les autres options. -h, --help Affiche la liste de toutes les options disponibles et quitte. --inplace Va dans le repertoire du fichier source avant la compilation, de sorte que les resultats sont produits au meme endroit que les sources. --into Va dans le repertoire specifie avant la compilation, de sorte que les resultats y sont produits, au lieu d'etre places dans le repertoire courant. --jobname Specifie le nom de travail (<< job >>) a 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 effaces apres la compilation du document et l'envoi du resultat sur la sortie standard. Le document temporaire est nomme rubtmpX.tex, ou X est un nombre tel qu'aucun fichier de ce nom n'existe au depart. -n, --maxerr Definit le nombre maximum d'erreurs affichees. Par defaut, au plus 10 erreurs sont rapportees, l'option -n -1 les affiche toutes. -m, --module [:] Utilise le module specifie en plus des paquets du document. Des arguments peuvent etre passes au module en les ajoutant apres un signe deux-points, ils correspondent aux options du paquet dans LaTeX. Le module est charge avant l'analyse du document. --only Compile le document partiellement, en n'incluant que les sources specifies. Le fonctionnement consiste a ajouter un appel a \includeonly sur la ligne de commande. L'argument est une liste de noms de fichiers separes par des virgules. -o, --post [:] Utilise le module specifie en tant que post-processeur. Cette option est similaire a -m mais elle charge le module apres l'analyse du document. -d, --pdf Produit un document PDF. Si cette option apparait apres --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 apres compilation avec dvips(1) afin de produire un document PostScript. Cette option est synonyme de -o dvips, elle ne peut pas etre utilisee apres --pdf. -q, --quiet Diminue la quantite de messages affiches. C'est l'inverse de -v. -r, --read Lire des directives supplementaires dans le fichier specifie 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 equivaut a fixer la variable src-specials a yes. -s, --short Formate les messages d'erreur de LaTeX de facon compacte (une erreur par ligne). -I, --texpath Ajoute le repertoire specifie au chemin de recherche de fichiers de TeX. --synctex Autorise l'extension SyncTeX pendant l'execution de LaTeX. --unsafe Permettre au document d'executer lancer des logiciels externes. Cette option est potentiellement dangereuse, reservez-la a des documents provenant d'une source de confiance ! -v, --verbose Incremente le degre de detail dans les messages affiches. Les niveaux existants vont de 0 a 4, le niveau par defaut est 1 pour rubber et 0 pour rubber-pipe. Attention, dire -vvv rend Rubber tres bavard. --version Affiche le numero de version et termine. -W, --warn Rapporter les avertissements d'un type donne, s'il n'y a pas eu d'erreur de compilation. Les types disponibles sont les suivants. boxes (boites trop ou pas assez remplies), refs (references non definies ou definies plusieurs fois), misc (autres messages) et all pour rapporter tous les messages. MODULES L'action de Rubber est influencee par des modules charges des paquets ou programmes auxiliaires. Paquets Pour chaque paquet qu'un document utilise, Rubber recherche un module de meme nom pour effectuer les operations que ce paquet peut necessiter en plus de la compilation par LaTeX. Des modules peuvent etre ajoutes a ceux fournis par defaut pour ajouter de nouvelles fonctionnalites (c'est d'ailleurs un interet du systeme modulaire). Les modules standard sont les suivants. asymptote Traite les fichiers .asy generes par le paquet LaTeX, puis declenche une recompilation. beamer Ce module s'occupe des fichiers .head de Beamer de la meme facon que pour les autres tables des matieres. bibtex, biblatex S'occupe de traiter la bibliographie du document avec BibTeX lorsque c'est necessaire. Ce module est charge automatiquement lorsque le document contient la macro \bibliography (voir DIRECTIVES pour les options). combine Le paquet combine sert a rassembler plusieurs documents LaTeX en un seul. Ce module s'occupe de gerer les dependances dans ce cas. epsfig Ce module gere l'inclusion de figures pour les documents qui utilisent l'ancienne methode avec \psfig. Il s'agit en fait d'une interface pour le module graphics, voir celui-ci pour les details. glossaries Execute makeglossaries et recompile quand le fichier .glo change. graphics, graphicx Ces modules identifient les fichier graphiques inclus par le document et les considerent comme des dependances a la compilation. Ils utilisent en plus certaines regles pour construire ces fichiers. Voir la documentation en info pour plus de details. hyperref S'occupe des fichiers supplementaires que produit ce paquet dans certains cas. index, makeidx, nomencl Traite les index et nomenclatures du document avec makeindex(1) lorsque c'est necessaire (voir dans DIRECTIVES pour les options). ltxtable Ajoute une dependance vers les fichiers inseres par le paquet LaTeX ltxtable. minitoc, minitoc-hyper Lors du nettoyage, supprime les fichiers supplementaires produits pour la construction de tables des matieres partielles. moreverb, verbatim Ajoute les fichiers inclus par \verbatiminput et les macros similaires a la liste des dependances. multibib S'occupe des bibliographies supplementaires creees par ce paquet, et efface les fichiers associes lors du nettoyage. xr Ajoute les fichiers .aux utilises pour les references externes a la liste des dependances, afin que la compilation ait lieu lorsque les documents externes sont modifies. Pre-traitements Les modules suivants sont fournis pour l'utilisation de programmes qui produisent un source LaTeX a partir de formats differents. cweb Ce module sert a executer cweave(1) si necessaire avant le processus de compilation pour produire le source LaTeX. Ce module est charge automatiquement si le fichier specifie sur la ligne de commande a .w pour suffixe. lhs2TeX Ce module utilise le preprocesseur lhs2TeX pour produire le source LaTeX a partir d'un programme en Literate Haskell. Il est utilise automatiquement si le nom du fichier d'entree se termine par .lhs. Traitement apres compilation Les modules suivants sont fournis pour effectuer diverses transformations apres la compilation. L'ordre dans lequel ces modules sont utilises est important, par exemple pour effectuer une serie 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 compressee avec bzip2(1). dvipdfm Lance dvipdfm(1) a la fin de la compilation pour produire un document PDF. dvips Lance dvips(1) a la fin de la compilation pour produire un document PostScript. Ce module est aussi charge par l'option de ligne de commande --ps. expand Produit un source LaTeX a partir du document principal, en remplacant 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 developpe sera nomme foo-final.tex. Voir la documentation en info pour plus de details. gz Produit une version du document final compressee 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 a changer de compilateur LaTeX. aleph Utilise Aleph au lieu de TeX, c'est-a-dire compile le document avec lamed(1) au lieu de latex. omega Utilise Omega au lieu de TeX, c'est-a-dire compile le document avec lambda(1) au lieu de latex. Si le module dvips est utilise, il transformera le DVI avec la commande odvips(1). Notez que si le paquet omega est utilise par le document, ce module sera charge automatiquement. pdftex Indique a Rubber d'utiliser pdflatex(1) au lieu de latex pour compiler le document. Par defaut, cela a pour effet de produire un fichier PDF au lieu d'un DVI, mais si le module est charge avec l'option dvi (par exemple en disant -m pdftex:dvi) le document est compile en DVI par pdflatex. Ce module est aussi charge par l'option de ligne de commande --pdf. vtex Indique a Rubber d'utiliser le compilateur VTeX. Par defaut la commande vlatex est utilisee, pour produire une sortie en PDF. Avec l'option ps (par exemple en disant << rubber -m vtex:ps toto.tex >>) le compilateur utilise sera vlatexp et le resultat sera un fichier PostScript. xelatex Demande a 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 ou ce mecanisme 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, eventuellement suivi d'espaces et d'arguments. Les commandes disponibles sont les suivantes: Directives generales alias Declare la macro LaTeX nom1 comme equivalente a nom2. Ceci peut etre utile quand on definit une macro personnelle autour d'une macro connue de Rubber. clean Indique que le fichier specifie doit etre efface lors du nettoyage par --clean. depend Considere le fichier specifie comme une dependance a la compilation, sa date de modification sera verifiee. make [] Declare que le fichier specifie doit etre produit. Les options permettent de specifier la facon de le produire: from indique le nom du fichier source, with indique la regle de conversion a employer. Par exemple, << make toto.pdf from toto.eps >> indique que toto.pdf doit etre produit a partir de toto.eps, avec n'importe quelle regle susceptible de le faire. Voir la documentation info pour plus de details sur la conversion de fichiers. module [] Charge le module specifie, eventuellement avec des options. Cette directive est equivalente a l'option de ligne de commande --module. onchange Execute la commande shell specifiee apres la compilation lorsque le contenu du fichier specifie a change. Le nom de fichier se termine au premier espace sur la ligne. path Ajoute le repertoire specifie au chemin de recherche de TeX (et de Rubber). Le nom du repertoire est tout le texte qui suit les espaces apres << path >>. produce Informe Rubber que l'execution de LaTeX cree ou modifie ce(s) fichier(s). read Lit le fichier de directives specifie. Le fichier doit comporter une commande par ligne. Les lignes vides ou commencant par un << % >> sont ignorees. rules Lit des regles de conversion supplementaires dans le fichier specifie. Ce fichier doit etre au meme format que le fichier rules.ini, voir la documentation info pour plus de details. set Definit la variable nom avec la valeur specifiee. Pour plus d'informations sur les variables, voir la documentation en info. setlist Definit la variable nom avec la liste de valeurs specifiee. Les valeurs sont separees par des espaces. Pour plus d'informations sur les variables, voir la documentation en info. shell_escape Marquer ce document comme necessitant des logiciels externes (shell-escape ou write18). Rubber va ne pas accepter cette option sauf quand l'option --unsafe est utilisee. synctex Autorise l'extension SyncTeX pendant l'execution de LaTeX. watch Surveille les modifications sur le fichier specifie. Si le contenu de ce fichier change lors d'une compilation, une nouvelle compilation est declenchee. Ce mecanisme est utile par exemple pour les tables des matieres. Directives specifiques aux modules Si une commande est de la forme toto.tutu, elle est consideree comme une commande tutu pour le module toto. Si ce module n'est pas encore enregistre lorsque la directive est rencontree, la commande est simplement ignoree. Pour les modules standard, les directives sont les suivantes: biblatex.path Ajoute le repertoire donne aux chemins dans lesquels BibTex cherche ses bases de donnees bibtex.crossrefs Specifie le nombre minimum de crossref requis pour l'inclusion automatique de l'entree referencee dans la liste de citations. Definit l'option -min-crossrefs lors de l'appel a bibtex(1). bibtex.path Ajoute le repertoire specifie au chemin de recherche de bases de donnees BibTeX (fichiers .bib). bibtex.stylepath Ajoute le repertoire specifie au chemin de recherche de styles BibTeX (fichiers .bst). bibtex.tool Utiliser un autre outil que BibTeX pour la bibliography. dvipdfm.options Passe les options de ligne de commande specifiees a dvipdfm. dvips.options Passe les options de ligne de commande specifiees a dvips. index.tool (index) Specifie l'outil a utiliser pour traiter l'index. Les choix possibles sont actuellement makeindex(1) (valeur par defaut) et xindy(1). L'argument index est optionnel, il peut etre utilise pour specifier la liste des index auxquels s'applique la commande. S'il est present, il doit etre place entre parentheses et la liste est separee par des virgules. Si l'argument est absent, la commande s'applique a tous les index. index.language (index) Selectionne la langue a utiliser pour trier l'index. Ceci ne s'applique que si l'outil utilise est xindy(1). L'argument optionnel a la meme signification qu'au-dessus. index.modules (index) ... Specifie quels modules utiliser lors du traitement de l'index par xindy(1). L'argument optionnel a la meme signification qu'au-dessus. index.order (index) Modifie les options de tri de l'index. Les arguments dont des mots (separes par des espaces) parmi standard, german et letter. Cette option n'a d'effet qu'avec makeindex(1). L'argument optionnel a la meme signification qu'au-dessus. index.path (index) Ajoute le repertoire specifie au chemin de recherche de styles d'index (fichiers .ist). L'argument optionnel a la meme signification qu'au-dessus. index.style (index)