RUBBER(1) General Commands Manual RUBBER(1)
NAME
rubber - a building system for LaTeX documents
SYNOPSIS
rubber [options] sources ...
rubber-pipe [options]
DESCRIPTION
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.
The command rubber builds the specified documents completely. 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. If one compilation fails, the whole process stops, includ-
ing the compilation of the next documents on the command line, and rub-
ber returns a non-zero exit code.
The command 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.
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 section DIRECTIVES.
OPTIONS
The options are used either to choose the action to be performed or to
configure the building process. They are mostly the same in rubber and
rubber-pipe. Options are parsed using GNU Getopt conventions.
-b, --bzip2
Compress the final document (in bzip2 format). This is equiva-
lent to saying -o bzip2 after all other options.
--clean
Remove all files produced by the compilation, instead of build-
ing 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 <command>
Execute the specified command (or directive) before parsing the
input files. See section DIRECTIVES for details.
-e, --epilogue <command>
Execute the specified command (or directive) after parsing the
input files. See section DIRECTIVES for details.
-f, --force
Force at least one compilation of the source. This may be use-
ful, 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 is equiva-
lent 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 <directory>
Go to the specified directory before compiling, so that all
files are produced there and not in the current directory.
--jobname <name>
Specify a job name different from the base file name. This
changes the name of output files and only applies to the first
target.
-k, --keep
This option is used in 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 docu-
ment is named rubtmpX.tex, where X is a number such that no file
of that name exists initially.
-n, --maxerr <num>
Set the maximum number of displayed errors. By default, up to
10 errors are reported, saying -n -1 displays all errors.
-m, --module <module>[:<args>]
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 <sources>
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 <module>[:<args>]
Use 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 in-
stance 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(1) to pro-
duce a PostScript document. This option is a synonym for
-o dvips, it cannot come after --pdf.
-q, --quiet
Decrease the verbosity level. This is the reverse of -v.
-r, --read <file>
Read additional directives from the specified file (see also the
directive "read").
-S, --src-specials
Enable generation of source specials if the compiler supports
it. This is equivalent to setting the variable src-specials to
yes.
-s, --short
Display LaTeX's error messages in a compact form (one error per
line).
-I, --texpath <directory>
Add the specified directory to TeX's search path.
--synctex
Enable SyncTeX support in the LaTeX run.
--unsafe
Permit the document to invoke arbitrary external programs. This
is potentially dangerous, only use this option for documents
coming from a trusted source.
-v, --verbose
Increase the verbosity level. Levels between 0 and 4 exist, the
default level is 1 for rubber and 0 for rubber-pipe. Beware,
saying -vvv makes Rubber speak a lot.
--version
Print the version number and exit nicely.
-W, --warn <type>
Report information of the given type if there was no error dur-
ing compilation. The available types are: boxes (overfull and
underfull boxes), refs (undefined or multiply defined refer-
ences), misc (other warnings) and all to report all warnings.
MODULES
Rubber's action is influenced by modules. Modules take care of the
particular features of packages and external programs.
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 pro-
vided by default to include new features (this is the point of the mod-
ule system). The standard modules are the following:
asymptote
Process the .asy files generated by the LaTeX package, then
triggers a recompilation.
beamer This module handles Beamer's extra files the same way as other
tables of contents.
bibtex, biblatex
Takes care of processing the document's bibliography with BibTeX
when needed. This module is automatically loaded if the docu-
ment contains the macro \bibliography (see also in DIRECTIVES
for options).
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 module, see this one for details.
glossaries
Run makeglossaries and recompiles when the .glo file changes.
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. See
the info documentation for details.
hyperref
Handle the extra files that this package produces in some cases.
index, makeidx, nomencl
Process the document's indexes and nomenclatures with makein-
dex(1) when needed (see section DIRECTIVES for options).
ltxtable
Add dependencies for files inserted via the ltxtable LaTeX pack-
age.
minitoc, minitoc-hyper
On cleaning, remove additional files that produced to make par-
tial 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.
xr Add additional .aux files used for external references to the
list of dependencies, so recompiling is automatic when refer-
enced document are changed.
Pre-processing
The following modules are provided for using programs that generate a
LaTeX source from a different file format:
cweb This module's purpose is to run cweave(1) if needed before the
compiling process to produce the LaTeX source. This module is
automatically loaded if the file specified on the command line
has .w as its suffix.
lhs2TeX
This module uses the lhs2TeX preprocessor to generate the LaTeX
source from a Literate Haskell program. It is automatically
triggered if the input file's name ends with .lhs.
Post-processing
The following modules are provided to support different kinds of
post-processings. Note that the order matters when using these mod-
ules: if you want to use a processing chain like
foo.tex -> foo.dvi -> foo.ps -> foo.pdf -> foo.pdf.gz
you have to load the modules dvips, ps2pdf and gz in that order, for
instance using the command line
rubber -p -o ps2pdf -z foo.tex
bzip2 Produce a version of the final file compressed with bzip2(1).
dvipdfm
Runs dvipdfm(1) at the end of compilation to produce a PDF docu-
ment.
dvips Runs dvips(1) at the end of compilation to produce a PostScript
document. This module is also loaded by the command line option
--ps.
expand Produce an expanded LaTeX source by replacing \input macros by
included files, bibliography macros by the bibliography produced
by bibtex(1), and local classes and packages by their source.
If the main file is foo.tex then then expanded file will be
named foo-final.tex. See the info documentation for details.
gz Produce a version of the final file compressed with gzip(1).
ps2pdf Assuming that the compilation produces a PostScript document
(for instance using module dvips), convert this document to PDF
using ps2pdf(1).
Compiler choice
The following modules are used to change the LaTeX compiler:
aleph Use the Aleph compiler instead of TeX, i.e. compiles the docu-
ment using lamed(1) instead of latex.
omega Use the Omega compiler instead of TeX, i.e. compiles the docu-
ment using lambda(1) instead of latex. If the module dvips is
used too, it will use odvips(1) to translate the DVI file. Note
that this module is triggered automatically when the document
uses the package omega.
pdftex Instructs Rubber to use pdflatex(1) instead of latex(1) to com-
pile the document. By default, this produces a PDF file instead
of a DVI, but when loading the module with the option dvi (for
instance by saying -m pdftex:dvi) the document is compiled into
DVI using pdflatex. This module is also loaded by the command
line option --pdf.
vtex Instructs Rubber to use the VTeX compiler. By default this uses
vlatex as the compiler to produce PDF output. With the option
ps (e.g. when saying "rubber -m vtex:ps foo.tex") the compiler
used is vlatexp and the result is a PostScript file.
xelatex
Instructs Rubber to use xelatex(1) instead of latex.
DIRECTIVES
The automatic behavior of Rubber is based on searching for macros in
the LaTeX sources. When this is not enough, directives can be added in
the comments of the sources. A directive is a line like
% rubber: cmd args
The line must begin with a "%", then any sequence of "%" signs and spa-
ces, then the text "rubber:" followed by spaces and a command name,
possibly followed by spaces and arguments.
General directives
alias <name1> <name2>
Pretend that the LaTeX macro name1 is equivalent to name2. This
can be useful when defining wrappers around supported macros.
clean <file>
Indicates that the specified file should be removed when clean-
ing using --clean.
depend <file>
Consider the specified file as a dependency, so that its modifi-
cation time will be checked.
make <file> [<options>]
Declare that the specified file has to be generated. Options
can specify the way it should be produced, the available options
are from <file> to specify the source and with <rule> to specify
the conversion rule. For instance, saying "make foo.pdf from
foo.eps" indicates that foo.pdf should be produced from foo.eps,
with any conversion rule that can do it. See the info documen-
tation for details on file conversion.
module <module> [<options>]
Loads the specified module, possibly with options. This is
equivalent to the command-line option --module.
onchange <file> <command>
Execute the specified shell command after compiling if the con-
tents of the specified file have changed. The file name ends at
the first space.
path <directory>
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".
produce <file>
Declares that the LaTeX run will create or update the specified
file(s).
read <file>
Read the specified file of directives. The file must contain
one directive per line. Empty lines and lines that begin with
"%" are ignored.
rules <file>
Read extra conversion rules from the specified file. The format
of this file is the same as that of rules.ini, see the info doc-
umentation for details.
set <name> <value>
Set the value of a variable as a string. For details on the ex-
isting variables and their meaning, see the info documentation.
setlist <name> <values>
Set the value of a variable as a (space-separated) list of
strings. For details on the existing variables and their mean-
ing, see the info documentation.
shell_escape
Mark the document as requiring external programs (shell-escape
or write18). Rubber does not actually enable this unless called
with the option --unsafe.
synctex
Enable SyncTeX support in the LaTeX run.
watch <file>
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.
Module-specific directives
If a command 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 command is silently ignored. For the standard modules,
the directives are the following:
biblatex.path <directory>
Adds the specified directory to the search path for BibTeX data-
bases (.bib files).
bibtex.crossrefs <number>
Set the minimum number of crossref required for automatic inclu-
sion of the referenced entry in the citation list. This sets
the option -min-crossrefs when calling bibtex(1).
bibtex.path <directory>
Adds the specified directory to the search path for BibTeX data-
bases (.bib files).
bibtex.stylepath <directory>
Adds the specified directory to the search path for BibTeX
styles (.bst files).
bibtex.tool <command>
Use a different bibliography tool instead of BibTeX.
dvipdfm.options <options>
Pass the specified command-line switches to dvipdfm.
dvips.options <options>
Pass the specified command-line switches to dvips.
index.tool (index) <name>
Specifies which tool is to be used to process the index. The
currently supported tools are makeindex(1) (the default choice)
and xindy(1). The argument index is optional, it may be used to
specify the list of indexes the command applies to. When
present, it must be enclosed in parentheses; the list is comma-
separated. When the argument is not present, the command ap-
plies to all indices.
index.language (index) <language>
Selects the language used for sorting the index. This only ap-
plies when using xindy(1) as the indexing tool. The optional
argument has the same semantics as above.
index.modules (index) <module>...
Specify which modules to use when processing an index with
xindy(1). The optional argument has the same semantics as
above.
index.order (index) <options>
Modifies the sorting options for the indexes. The arguments are
words (separated by spaces) among standard, german and letter.
This only applies when using makeindex(1). The optional argu-
ment has the same semantics as above.
index.path (index) <directory>
Adds the specified directory to the search path for index styles
(.ist files). The optional argument has the same semantics as
above.
index.style (index) <style>
Specifies the index style to be used. The optional argument has
the same semantics as above.
makeidx.language, .modules, .order, .path, .style, .tool
These directives are the same as for the index module, except
that they don't accept the optional argument.
multibib.crossrefs, .path, .stylepath, .tool
These directives are the same as for the bibtex module but they
apply to bibliographies managed by the multibib package. They
take an optional first argument, with the same convention as for
the directives of the index module, which may be used to specify
the list of bibliographies the command applies to.
BUGS
There are surely a some...
This page documents Rubber version 1.6.0. The program and this man-
page are maintained by Florian Schmaus <flo@geekplace.eu>. The home-
page for Rubber can be found at https://gitlab.com/latex-rubber/rubber.
SEE ALSO
The full documentation for rubber is maintained as a Texinfo manual.
If the info and rubber programs are properly installed at your site,
the command
info rubber
should give you access to the complete manual.
RUBBER(1)
Generated by dwww version 1.15 on Wed Jun 26 02:39:37 CEST 2024.