This is rubber.info, produced by makeinfo version 4.8 from rubber.texi. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled "Copying" and "GNU General Public License" are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. Copyright (C) 2002-2006 Emmanuel Beffara. INFO-DIR-SECTION teTeX START-INFO-DIR-ENTRY * Rubber: (rubber). A building system for LaTeX documents. END-INFO-DIR-ENTRY  File: rubber.info, Node: Top, Next: Introduction Rubber ****** Rubber is a wrapper for LaTeX and companion programs. Its purpose is, given a LaTeX source to process, to compile it enough times to resolve all references, possibly running satellite programs such as BibTeX, makeindex, Metapost, etc. to produce appropriate data files. * Menu: * Introduction:: Introduction. * Invoking:: Syntax of the command lines. * Directives:: Directives in LaTeX comments. * Modules:: List of standard modules. * Graphics:: Support for graphics conversion. * Index:: Directive and modules index.  File: rubber.info, Node: Introduction, Next: Invoking, Prev: Top, Up: Top 1 Introduction ************** The purpose of Rubber is to make the building of a document automated, from the source files to the final document file, replacing the work of a Makefile. The basis is a routine that compiles a LaTeX source the right number of times to resolve all references and make all tables of contents, list of figures, and so on. On top of that, Rubber provides a modular system to handle various tasks needed apart from compilations. This, for instance, includes processing bibliographic references or indices, as well as compilation or conversion of figures. Additionally, modules can perform a post-processing of the document (for instance to convert a DVI to PostScript or PDF) or even a preprocessing (useful when the LaTeX source is generated by another program, like cweave). Dependency analysis is performed by parsing the source files, so that modifying any source, user package, graphics file or other dependency leads to appropriate compilations. Modules are triggered either explicitly using command line options, or implicitly when the sources are parsed. For instance, BibTeX support is activated whenever the source contains commands that generate a bibliography, graphics support is activated by `\usepackage{graphics}' and similar commands, and so on. The modular approach allows any additional feature to be supported by simply writing a module to support it. Some information cannot be extracted from the LaTeX sources. This is the case, for instance, with the search paths (which can be specified in environment variables like `TEXINPUTS'), or the style to be used with Makeindex. To address this problem, one can add information for Rubber in the comments of the LaTeX sources, see *Note Directives::. The package comes with three different command line programs: `rubber' Builds the specified documents completely. The source files may be either LaTeX sources or documents in a format Rubber knows how to translate into LaTeX. `rubber-pipe' Does the same for one document but it reads the LaTeX source from standard input and dumps the compiled document on standard output. `rubber-info' This is a utility for extracting various kinds of information from a LaTeX document, either from the source or from the compilation log files.  File: rubber.info, Node: Invoking, Next: rubber command line, Prev: Introduction, Up: Top 2 Command lines *************** The command line of each program is read using the GNU Getopt conventions. `rubber' and `rubber-pipe' mostly have the same syntax. * Menu: * rubber command line:: Syntax for `rubber' and `rubber-pipe'. * rubber-info command line:: Syntax for `rubber-info'.  File: rubber.info, Node: rubber command line, Next: rubber-info command line, Prev: Invoking, Up: Invoking 2.1 Syntax for `rubber' and `rubber-pipe' ========================================= The syntax of the command lines for `rubber' and `rubber-pipe' are: rubber [options] files rubber-pipe [options] The source files may be either LaTeX sources (in which case the suffix `.tex' may be omitted) or documents in a format Rubber knows how to translate into LaTeX (this currently means CWEB or Literate Haskell documents). If any compilation fails, the whole process stops, including the compilation of the next documents on the command line, and the program returns a non-zero exit code. The options are the following: `--cache' Use the experimental cache system. This uses a file `rubber.cache' in the current directory to store the results of parsing and dependency analysis, so that subsequent compilations are faster. `--clean' Remove all files produced by the compilation, instead of building the document. This option is present in rubber only. It applies to the compilation as it would be done with the other options of the command line, i.e. saying rubber --clean foo will not delete foo.ps, while saying rubber --ps --clean foo will. `-c ' `--command ' Execute the specified command (or directive) _before_ parsing the source files. *Note Directives::. `-e ' `--epilogue ' Execute the specified command (or directive) _after_ parsing the source fiels. *Note Directives::. `-f' `--force' Force at least one compilation of the source. This may be useful, for instance, if some unusual dependency was modified (e.g. a package in a system directory). This option is irrelevant in rubber-pipe. `-z' `--gzip' Compress the final document (in `gzip' format). This option is equivalent to saying `-o gz' after all other options. `-h' `--help' Display the list of all available options and exit nicely. `--inplace' Go to the directory of the source files before compiling, so that compilation results are in the same place as their sources. `--into ' Go to the specified directory before compiling, so that all files are produced there and not in the current directory. `-k' `--keep' This option is for `rubber-pipe' only. With this option, the temporary files will not be removed after compiling the document and dumping the results on standard output. The temporary document is named `rubtmpX.tex', where `X' is a number such that no file of that name exists initially. `-l' `--landscape' Specify that the final document should use landscape orientation. This is relevant only when using `dvips' or `dvipdfm'. `-n ' `--maxerr ' Set the maximum number of displayed errors. By default, up to 10 errors are reported, saying `-n -1' displays all errors. `-m [:]' `--module [:]' Use the specified module in addition to the document's packages. Arguments can be passed to the package by adding them after a colon, they correspond to the package options in LaTeX. The module is loaded _before_ parsing the document's sources. `--only ' Compile the document partially, including only the specified sources. This works by inserting a call to `\includeonly' on the command line. The argument is a comma-separated list of file names. `-o [:]' `--post [:]' Used the specified module as a post-processor. This is similar to the `-m' options except that the module is loaded _after_ parsing the document. `-d' `--pdf' Produce PDF output. When this option comes after `--ps' (for instance in the form `-pd') it is a synonym for `-o ps2pdf', otherwise it acts as `-m pdftex', in order to use pdfLaTeX instead of LaTeX. `-p' `--ps' Process the DVI produced by the process through `dvips' to produce a PostScript document. This option is a synonym for `-e module dvips', it cannot come after `--pdf'. `-q' `--quiet' Suppress all messages during the process. `-r ' `--read ' Read additional directives form the specified file (see also the directive `read'). `-s' `--short' Display LaTeX's error messages in a compact form (one error per line). `-I ' `--texpath ' Add the specified directory to the search path of TeX files. `-v' `--verbose' Increase the verbosity level. The default level is 0, levels up to 3 exist. Beware, saying `-vvv' makes Rubber speak a lot. `--version' Print the version number and exit nicely. `-W ' `--warn ' Report warnings of the given type, if there was no compilation error. The available types are: `boxes' overfull and underfull boxes, `refs' undefined or multiply defined references, `misc' other warnings, `all' all of the above.  File: rubber.info, Node: rubber-info command line, Next: Directives, Prev: rubber command line, Up: Invoking 2.2 Syntax for `rubber-info' ============================ The command-line syntax for `rubber-info' is the following: rubber-info [options] [action] source The options are all those accepted by `rubber' and `rubber-pipe', as described in *Note rubber command line::. The `action' specified what kind of information has to be extracted. At most one such argument must be present on the command line, `--check' is assumed if none is present. The possible actions are: `--boxes' Extracts from the log file the places in the source where bad boxes appeared (these are the famous overfull and underfull `\hbox' and `\vbox'). `--check' Report errors if there are any, otherwise report undefined references if there are any, otherwise list warnings and bad boxes. This is the default action. `--deps' Analyse the source files and produce a space-separated list of all the files that the document depends on and that Rubber cannot rebuild. `--errors' Extract from the log file the list of errors that occured during the last compilation. `-h' `--help' Display the list of all available options and exit nicely. `--refs' Report the list of undefined or multiply defined references (i.e. the `\ref''s that are not defined by one `\label'). `--rules' Analyse the source files and produce a list of dependency rules. One rule is produced for each intermediate target that would be made when running `rubber'. Rules are formatted in the style of Makefiles. `--version' Print the version number and exit nicely. `--warnings' Stupidly enumerate all LaTeX warnings, i.e. all the lines in the log file that contain the string "Warning".  File: rubber.info, Node: Directives, Next: General directives, Prev: rubber-info command line, Up: Top 3 Directives ************ Some information cannot be extracted from the LaTeX sources. To address this problem, one can add information for Rubber in the comments of the LaTeX sources, in the form of directives. A directive is a line like % rubber: cmd args The line must begin with a `%', then any sequence of `%' signs and spaces, then the text `rubber:' followed by zero or more spaces and a directive name, possibly followed by spaces and arguments. The argument in the directive line are separated by spaces, single and double quotes allow escaping of spaces (and quotes). The directive can contain variable references with the syntax `$VAR' or `${VAR}'. For details on the use of variables, see *Note Variables::. If a directive name has the form `foo.bar', it is considered a command `bar' for the module `foo'. If this module is not registered when the directive is found, then the directive is silently ignored. See the individual documentation for modules for module-specific directives. * Menu: * General directives:: * Variables::  File: rubber.info, Node: General directives, Next: Variables, Prev: Directives, Up: Directives 3.1 General directives ====================== `alias ' Pretend that the LaTeX macro `name1' is equivalent to `name2'. This can be useful when defining wrappers around supported macros, like: % rubber: alias ig includegraphics \newcommand\ig[1]{\includegraphics[scale=.5]{#1}} `clean ' Indicates that the specified file should be removed when cleaning using `--clean'. `depend ' Consider the specified file as a dependency, so that its modification time will be checked. `make []' Declare that the specified file has to be generated. Options can specify the way it should be produced, the available options are `from ' to specify the source and `with ' to specify the conversion rule. For instance, saying % rubber: make foo.pdf from foo.eps indicates that `foo.pdf' should be produced from `foo.eps', with any conversion rule that can do it. `module []' Loads the specified module, possibly with options. This is equivalent to the command-line option `--module'. `onchange ' Execute the specified shell command after compiling if the contents of the specified file have changed. The file name ends at the first space. `paper ' Specify options related to paper size. Currently they are used to give `-t' options to `dvips' and `-p' options to `dvipdfm'. `path ' Adds the specified directory to the search path for TeX (and Rubber). The name of the directory is everything that follows the spaces after `path'. `read ' Read the specified file of directives. The file must contain one directive per line. Empty lines and lines that begin with `%' are ignored. `rules ' Read extra conversion rules from the specified file. The format of this file is the same as that of `rules.ini', see *Note rules.ini::. `set ' Set the value of a variable. For details on the existing variables and their meaning, see *Note Variables::. `watch ' Watch the specified file for changes. If the contents of this file has changed after a compilation, then another compilation is triggered. This is useful in the case of tables of contents, for instance.  File: rubber.info, Node: Variables, Next: Modules, Prev: General directives, Up: Directives 3.2 Variables ============= The following variables are defined by Rubber (or its modules) and used by various modules to influence compilation. `base' The base name of the main source file, including its path but without the extension. `engine' The name of the TeX engine used. By default this is `TeX', this can be changed to `VTeX', `pdfTeX', `Omega' or others by the modules that change the compiler, see *Note Compiler choice::. `file' The name of the current file (this is set during parsing). `job' The job name of the document, with no path indication. `latex' Specify which program should be used for compiling. By default this is `latex', various modules can change it in order to use a different compiler instead, see *Note Compiler choice::. `line' The current line number in the current file (this is set during parsing). `paper' The paper size to use when compiling. This is used by post-processors like `dvips' or `dvipdfm'.  File: rubber.info, Node: Modules, Next: Packages, Prev: Variables, Up: Top 4 Modules ********* * Menu: * Packages:: Supported LaTeX packages. * Pre-processing:: Files format that can be converted into LaTeX. * Post-processing:: Post-processing the compiler's output. * Compiler choice:: Choosing which LaTeX compiler to use.  File: rubber.info, Node: Packages, Next: BibTeX, Prev: Modules, Up: Modules 4.1 Supported Packages ====================== For every package that a document uses, Rubber looks for a module of the same name to perform the tasks that this package my require apart from the compilation by LaTeX. Modules can be added to the ones provided by default to include new features (this is the point of the module system). The standard modules are the following: `beamer' This module handles Beamer's extra files the same way as other tables of contents. `bibtex' Takes care of processing the document's bibliography with BibTeX when needed. This module is automatically loaded if the document contains the macro `\bibliography'. For details, see *Note BibTeX::. `combine' The combine package is used to gather several LaTeX documents into a single one, and this module handles the dependencies in this case. `epsfig' This modules handles graphics inclusion for the documents that use the old style `\psfig' macro. It is actually an interface for the graphics system, for details see *Note Graphics::. `graphics' `graphicx' These modules identify the graphics included in the document and consider them as dependencies for compilation. They also use standard rules to build these files with external programs. For more details, see *Note Graphics::. `hyperref' Handle the extra files that this package produces in some cases. `index' `makeidx' Process the document's indexes with `makeindex' when needed. For details, see *Note Indexing::. `minitoc' `minitoc-hyper' On cleaning, remove additional files that produced to make partial tables of contents. `moreverb' `verbatim' Adds the files included with `\verbatiminput' and similar macros to the list of dependencies. `multibib' Handles the extra bibliographies that this package creates, and removes the extra files on cleaning. `natbib' May cause an extra compilation to solve references. `xr' Add additional `.aux' files used for external references to the list of dependencies, so recompiling is automatic when refer- enced document are changed. * Menu: * BibTeX:: Details on BibTeX support. * Indexing:: Details on Makeindex support.  File: rubber.info, Node: BibTeX, Next: Indexing, Prev: Packages, Up: Packages 4.1.1 BibTeX support -------------------- If the document contains a call to `\bibliography' or `\bibliographystyle', then the BibTeX module is used. This triggers the execution of BibTeX between compilations when new references are made, bibliographies are changed, and in other appropriate cases. The following directives may be used to control BibTeX's behaviour: `bibtex.path ' Add the specified directory to the seach path for BibTeX database files (`.bib' files). `bibtex.sorted ' If the argument is `true', `yes' or `1', declare that the bibliography is sorted (this is the default), otherwise declare that the citations appear in the same order as in the text. This may require additional calls to `bibtex'. `bibtex.stylepath ' Add the specified directory to the search path for BibTeX style files (`.bst' files).  File: rubber.info, Node: Indexing, Next: Pre-processing, Prev: BibTeX, Up: Packages 4.1.2 Index generation ---------------------- The use of the packages `index' and `makeidx' triggers the generation of an index (or several of them). Currently Rubber can use either the standard Makeindex or the more sophisticated Xindy. The following directives may be used to control how indices are generated: `index.tool ' Specifies which tool is to be used to process the index. The currently supported tools are `makeindex' (the default choice) and `xindy'. `index.language ' Selects the language used for sorting the index. This only applies when using `xindy' as the indexing tool. `index.modules ...' Specify which modules to use when processing an index with `xindy'. `index.order ' Modifies the sorting options for the index. The argument must be a space-separated list of words among `standard', `german' and `letter'. his only applies when using `makeindex'. `index.path ' Adds the specified directory to the search path for index style files (`.ist' files). `index.style