\input texinfo
@c %**start of header
@setfilename rubber.info
@settitle Rubber Manual 1.6.7
@c %**end of header

@copying
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 @copyright{} 2002--2006 Emmanuel Beffara.

Copyright @copyright{} 2006--2015 Sebastian Kapfer.
@end copying

@titlepage
@title Rubber
@subtitle Documentation for version 1.6.7
@author Sebastian Kapfer
@page
@vskip 0pt plus 1fill
@insertcopying
@end titlepage

@iftex
@contents
@end iftex

@c ---  Introduction  ---

@dircategory TeX
@direntry
* Rubber: (rubber).   A building system for LaTeX documents.
@end direntry

@ifnottex
@node Top, Introduction
@top 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.
@end ifnottex

@menu
* Introduction::  Introduction.
* Invoking::      Syntax of the command lines.
* Directives::    Directives in LaTeX comments.
* Modules::       List of standard modules.
* Graphics::      Support for graphics conversion.
* Encoding::      Encoding issues.
* Index::         Directive and modules index.
@end menu

@node Introduction, Invoking, Top, Top
@chapter 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
@code{\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 @env{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 @ref{Directives}.

The package comes with three different command line programs:

@table @command
@item 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.
@item 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.
@item 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.
@end table


@c ---  Command-line syntax  ---

@node Invoking, rubber command line, Introduction, Top
@chapter Command lines

The command line of each program is read using the GNU Getopt conventions.
@command{rubber} and @command{rubber-pipe} mostly have the same syntax.

@menu
* rubber command line::       Syntax for @command{rubber} and @command{rubber-pipe}.
* rubber-info command line::  Syntax for @command{rubber-info}.
@end menu

@node rubber command line, rubber-info command line, Invoking, Invoking
@section Syntax for @command{rubber} and @command{rubber-pipe}

The syntax of the command lines for @command{rubber} and @command{rubber-pipe}
are:

@example
rubber [options] files
rubber-pipe [options]
@end example

@noindent
The source files may be either LaTeX sources (in which case the suffix
@file{.tex} may be omitted) or documents in a format Rubber knows how to
translate into LaTeX.  This currently includes CWEB documents (filename
extension @file{.w}, via @command{cweave}), Literate Haskell (@file{.lhs} via
@command{lhs2tex}) and Knitr (@file{.Rtex}).  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:

@table @command
@item -b
@itemx --bzip2
Compress the final document (in @command{bzip2} format). This option is
equivalent to saying @option{-o bzip2} after all other options. It is
incompatible with the option @command{--gzip}.

@item --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
@example
rubber --clean foo
@end example
will not delete foo.ps, while saying
@example
rubber --ps --clean foo
@end example
will.

@item -c <command>
@itemx --command <command>
Execute the specified command (or directive) @emph{before} parsing the source
files. @xref{Directives}.

@item -e <command>
@itemx --epilogue <command>
Execute the specified command (or directive) @emph{after} parsing the source
fiels. @xref{Directives}.

@item -f
@itemx --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.

@item -z
@itemx --gzip
Compress the final document (in @command{gzip} format). This option is
equivalent to saying @option{-o gz} after all other options. It is
incompatible with the option @command{--bzip2}.

@item -h
@itemx --help
Display the list of all available options and exit nicely.

@item --inplace
Go to the directory of the source files before compiling, so that compilation
results are in the same place as their sources.

@item --into <directory>
Go to the specified directory before compiling, so that all files are produced
there and not in the current directory.

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

@item -k
@itemx --keep
This option is for @command{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 @file{rubtmpX.tex}, where
@file{X} is a number such that no file of that name exists initially.

@item -n <num>
@itemx --maxerr <num>
Set the maximum number of displayed errors. By default, up to 10 errors are
reported, saying @option{-n -1} displays all errors.

@item -m <module>[:<args>]
@itemx --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 @emph{before} parsing the
document's sources.

@item --only <sources>
Compile the document partially, including only the specified sources. This
works by inserting a call to @command{\includeonly} on the command line. The
argument is a comma-separated list of file names.

@item -o <module>[:<args>]
@itemx --post <module>[:<args>]
Used the specified module as a post-processor. This is similar to the
@option{-m} options except that the module is loaded @emph{after} parsing the
document.

@item -d
@itemx --pdf
Produce PDF output. When this option comes after @option{--ps} (for instance
in the form @option{-pd}) it is  a  synonym  for @option{-o ps2pdf}, otherwise
it acts as @option{-m pdftex}, in order to use pdfLaTeX instead of LaTeX.

@item -p
@itemx --ps
Process the DVI produced by the process through @command{dvips} to produce a
PostScript document. This option is a synonym for @option{-e module dvips}, it
cannot come after @option{--pdf}.

@item -q
@itemx --quiet
Suppress all messages during the process.

@item -r <file>
@itemx --read <file>
Read additional directives form the specified file (see also the directive
@command{read}).

@item -S
@itemx --src-specials
Enable generation of source @command{\special}s if the compiler supports it.
This is equivalent to setting the variable @command{src-specials} to
@samp{yes}.

@item -s
@itemx --short
Display LaTeX's error messages in a compact form (one error per line).

@item --synctex
Enable SyncTeX support in the LaTeX run.

@item -I <dir>
@itemx --texpath <dir>
Add the specified directory to the search path of TeX files.

@item --unsafe
Permit the document to invoke arbitrary external programs.  This is potentially
dangerous, only use this option for documents coming from a trusted source.

@item -v
@itemx --verbose
Increase the verbosity level. The default level is 0, levels up to 3 exist.
Beware, saying @option{-vvv} makes Rubber speak a lot.

@item --version
Print the version number and exit nicely.

@item -W <type>
@itemx --warn <type>
Report warnings of the given type, if there was no compilation error. The
available types are:
@table @option
@item boxes
overfull and underfull boxes,
@item refs
undefined or multiply defined references,
@item misc
other warnings,
@item all
all of the above.
@end table
@end table

@node rubber-info command line, Directives, rubber command line, Invoking
@section Syntax for @command{rubber-info}

The command-line syntax for @command{rubber-info} is the following:

@example
rubber-info [options] [action] source
@end example

The options are all those accepted by @command{rubber} and
@command{rubber-pipe}, as described in @ref{rubber command line}. The
@option{action} specified what kind of information has to be extracted. At
most one such argument must be present on the command line, @option{--check}
is assumed if none is present. The possible actions are:

@table @command
@item --boxes
Extracts from the log file the places in the source where bad boxes appeared
(these are the famous overfull and underfull @code{\hbox} and @code{\vbox}).

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

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

@item --errors
Extract from the log file the list of errors that occured during the last
compilation.

@item -h
@itemx --help
Display the list of all available options and exit nicely.

@item --refs
Report the list of undefined or multiply defined references (i.e. the
@code{\ref}'s that are not defined by one @code{\label}).

@item --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
@command{rubber}. Rules are formatted in the style of Makefiles.

@item --version
Print the version number and exit nicely.

@item --warnings
Stupidly enumerate all LaTeX warnings, i.e. all the lines in the log file that
contain the string "Warning".
@end table


@c ---  Directives  ---

@node Directives, General directives, rubber-info command line, Top
@chapter 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

@example
% rubber: cmd args
@end example

@noindent
The line must begin with a @samp{%}, then any sequence of @samp{%} signs and
spaces, then the text @samp{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 @samp{$VAR} or @samp{$@{VAR@}}. For
details on the use of variables, see @ref{Variables}.

If a directive name has the form @samp{foo.bar}, it is considered a command
@command{bar} for the module @command{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::
@end menu

@node General directives, Variables, Directives, Directives
@section General directives

@ftable @command
@item alias <name1> <name2>
Pretend that the LaTeX macro @samp{name1} is equivalent to @samp{name2}. This
can be useful when defining wrappers around supported macros, like:
@example
% rubber: alias ig includegraphics
\newcommand\ig[1]@{\includegraphics[scale=.5]@{#1@}@}
@end example

@item clean <file>
Indicates that the specified file should be removed when cleaning using
@option{--clean}.

@item depend <file>
Consider the specified file as a dependency, so that its modification time
will be checked.

@item 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 @command{from <file>} to
specify the source and @command{with <rule>} to specify the conversion rule.
For instance, saying
@example
% rubber: make foo.pdf from foo.eps
@end example
indicates that @file{foo.pdf} should be produced from @file{foo.eps}, with any
conversion rule that can do it.

@item module <module> [<options>]
Loads the specified module, possibly with options. This is equivalent to
the command-line option @command{--module}.

@item onchange <file> <command>
Execute the specified shell command after compiling if the contents of the
specified file have changed. In case the file or command contains
spaces, they must be enclosed within double or single quotes.

@item 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
@samp{path}.

@item produce <file>
Declares that the LaTeX run will create or update the specified file(s).
This implies that Rubber will check if the file contents changed and re-make
other files derived from it; it also implies that rubber --clean will
remove the indicated file.  @command{produce} may be combined with @command{watch}.
For example, Rubber's built-in behavior of recompiling the main LaTeX source
until the auxiliary file's contents no longer changes may be achieved using
@example
    produce document.aux
    watch document.aux
@end example

@item read <file>
Read the specified file of directives. The file must contain one directive per
line. Empty lines and lines that begin with @samp{%} are ignored.

@item rules <file>
Read extra conversion rules from the specified file. The format of this file
is the same as that of @file{rules.ini}, see @ref{rules.ini}.

@item set <name> <value>
Set the value of a variable as a string. For details on the existing variables
and their meaning, see @ref{Variables}.

@item setlist <name> <values>
Set the value of a variable as a list of strings. The list is space-separated,
possibly empty. For details on the existing variables and their meaning, see
@ref{Variables}.

@item shell_escape
Mark the document as requiring external programs (shell-escape or write18).
Rubber does not actually enable this unless called with the option
@option{--unsafe}.

@item synctex
Enable SyncTeX support in the LaTeX run.

@item 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.
@end ftable

@node Variables, Modules, General directives, Directives
@section Variables

The following variables are defined by Rubber (or its modules) and used by
various modules to influence compilation. All variables are strings that
should be defined by the @code{set} directive, unless explicitly specified.

@table @command
@item arguments (list)
Extra command-line arguments that are passed to the compiler. Note that this
is potentially dangerous and has no reason to be portable across different
compilers. This variable contains a list of strings, it should be set using
the @code{setlist} directive.

@item engine
Deprecated.  Please use a module to change the compiler, as described in
@ref{Compiler choice}.

@item file
Deprecated.
The name of the current file (this is set during parsing).

@item job
The job name of the document, with no path indication.
Note that changing the value of this variable does not affect compilation; in
order to actually change the job name, use the command line option
@option{--jobname}.

@item logfile_limit
Specify how much of the LaTeX logfile Rubber reads.
The default is 1 MB, which should be ample for any real document.

@item line
Deprecated.
The current line number in the current file (this is set during parsing).

@item src-specials
The kind of source @command{\special}s that should be generated. When empty
(which is the case by default), no @command{\special}s are generated. When set
to @samp{yes}, the default set is generated, otherwise the variable is passed
as the argument of the @command{-src-specials} switch of the compiler.

@end table

@c ---  Modules  ---

@node Modules, Packages, Variables, Top
@chapter Modules

@menu
* Packages::           Supported LaTeX packages.
* Post-processing::    Post-processing the compiler's output.
* Compiler choice::    Choosing which LaTeX compiler to use.
@end menu

@node Packages, BibLaTeX, Modules, Modules
@section 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:

@vtable @command

@item asymptote
Process the @code{.asy} files generated by the LaTeX package, then
triggers a recompilation.

@item beamer
This module handles Beamer's extra files the same way as other tables
of contents.

@item biblatex
Takes care of processing the document's bibliographies with Biber or BibTeX
when needed.  For details, see @ref{BibLaTeX}.

@item bibtex
@itemx bibtopic
@itemx multibib
Takes care of processing the document's bibliographies with BibTeX when
needed. The @command{bibtex} module is automatically loaded if the document
contains the macro @code{\bibliography}. For details, see @ref{BibTeX}.

@item combine
The combine package is used to gather several LaTeX documents into a single
one, and this module handles the dependencies in this case.

@item epsfig
This modules handles graphics inclusion for the documents that use the old
style @code{\psfig} macro. It is actually an interface for the graphics
system, for details see @ref{Graphics}.

@item glossaries
Run @code{makeglossaries} and recompiles when the @code{.glo} file changes.

@item graphics
@itemx 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 @ref{Graphics}.

@item hyperref
Handle the extra files that this package produces in some cases.

@item index
@itemx makeidx
@itemx nomencl
Process the document's indexes with @command{makeindex} when needed. For
details, see @ref{Indexing}.

@item minitoc
@itemx minitoc-hyper
On cleaning, remove additional files that produced to make partial tables of
contents.

@item moreverb
@itemx verbatim
Adds the files included with @code{\verbatiminput} and similar macros to the
list of dependencies.

@item ltxtable
Add dependencies for files inserted via the @code{ltxtable} LaTeX package.

@item xr
Add additional @file{.aux} files used for external references to the list of
dependencies, so recompiling is automatic when refer- enced document are
changed.
@end vtable

@menu
* BibLaTeX::    Details on BibLaTeX support.
* BibTeX::      Details on BibTeX support.
* Indexing::    Details on Makeindex support.
@end menu

@node BibLaTeX, BibTeX, Packages, Packages
@subsection BibLaTeX support

If the document loads the package @code{biblatex}, Rubber enables
BibLaTeX support.  Rubber will extract the appropriate external bibliography
tool such as @command{biber} or @command{bibtex} from the @code{backend}
option to the @code{biblatex} package and invoke it as needed.

@ftable @command
@item biblatex.path <directory>
Add the specified directory to the seach path for BibTeX database files
(@file{.bib} files).  The directory will be passed down to the bibliography
tool in the environment variable @command{BIBINPUTS}.
@end ftable

@node BibTeX, Indexing, BibLaTeX, Packages
@subsection BibTeX support

If the document contains a call to @code{\bibliography} or
@code{\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:

@ftable @command
@item bibtex.crossrefs <number>
Set the minimum number of @command{crossref} required for automatic inclusion
of the referenced entry in the citation list. This sets the option
@command{-min-crossrefs} when calling @command{bibtex}.

@item bibtex.path <directory>
Add the specified directory to the seach path for BibTeX database files
(@file{.bib} files).  The directory will be passed down to the bibliography
tool in the environment variable @command{BIBINPUTS}.

@item bibtex.stylepath <directory>
Add the specified directory  to  the  search  path  for  BibTeX style files
(@file{.bst} files).

@item bibtex.tool <command>
Call the specified command instead of @command{bibtex} to process the .aux file,
for example @command{bibtex8}.
@end ftable

Multiple bibliographies can be handled by the @command{multibib} package. The
directives provided by the @command{multibib} module are the same as those of
the @command{bibtex} module, and they may be used with an optional first
arument of the form @samp{(foo,bar,quux)} in order to specify that the
directive only applies to the bibliographies named @samp{foo}, @samp{bar} and
@samp{quux}. By default, directives are applied to all bibliographies.

@node Indexing, Post-processing, BibTeX, Packages
@subsection Index generation

The use of the packages @command{index}, @command{makeidx} and
@command{nomencl} 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:

@ftable @command
@item index.tool <name>
Specifies which tool is to be used to process the index. The currently
supported tools are @command{makeindex} (the default choice) and
@command{xindy}.

@item index.language <language>
Selects the language used for sorting the index. This only applies when
using @command{xindy} as the indexing tool.

@item index.modules <module>...
Specify which modules to use when processing an index with @command{xindy}.

@item index.order <options>
Modifies the sorting options for the index. The argument must be a
space-separated list of words among @samp{standard}, @samp{german} and
@samp{letter}. his only applies when using @command{makeindex}.

@item index.path <directory>
Adds the specified directory to the search path for index style files
(@file{.ist} files).

@item index.style <style>
Specifies the index style to be used.
@end ftable

Each of these directives may be used with an optional first arument of the
form @samp{(foo,bar,quux)} in order to specify that the directive only applies
to the indexes named @samp{foo}, @samp{bar} and @samp{quux}. By default,
directives are applied to all indices.

When using the package @command{makeidx} instead of  @command{index}, the
directives must of course be prefixed by @samp{makeidx.} instead of
@samp{index.}, and the optional first argument is not accepted.

@node Post-processing, Dvips and Dvipdfm, Indexing, Modules
@section Post-processors

The following modules are provided to support different kinds of
post-processings. Note that the order matters when using these modules: if you
want to use a processing chain like

@example
foo.tex -> foo.dvi -> foo.ps -> foo.pdf -> foo.pdf.gz
@end example

@noindent
you have to load the modules @command{dvips}, @command{ps2pdf} and
@command{gz} in that order, for instance using the command line

@example
rubber -p -o ps2pdf -z foo.tex
@end example

@vtable @command
@item bzip2
Produce a version of the final document compressed with @command{bzip2}.

@item dvipdfm
Runs @command{dvipdfm} at the end of compilation to produce a PDF document.

@item dvips
Runs @command{dvips} at the end of compilation to produce a PostScript
document. This module is also loaded by the command line option @option{--ps}.

@item expand
Produce an expanded LaTeX source by replacing @code{\input} macros by included
files, bibliography macros by the bibliography produced by @command{bibtex},
and local classes and packages by their source. For details, see @ref{Expand}.

@item gz
Produce a version of the final document compressed with @command{gzip}.

@item ps2pdf
Assuming that the compilation produces a PostScript document (for instance
using module @command{dvips}), convert this document to PDF using
@command{ps2pdf}.
@end vtable

@menu
* Dvips and Dvipdfm::    Details on DVI to PS/PDF conversion.
* Expand::               Details on the source expansion plugin.
@end menu

@node Dvips and Dvipdfm, Expand, Post-processing, Post-processing
@subsection Dvips and Dvipdfm

The @command{dvips} and @command{dvipdfm} modules can be used to call the
associated DVI drivers to produce PostScript or PDF documents from the DVI
output of LaTeX. The following directives may be used to change their
behaviour:

@ftable @command
@item dvipdfm.options <options>
@itemx dvips.options <options>
Pass the specified options to the driver. The argument is a space-separated
list of options that are passed before the DVI file's name.
@end ftable

@node Expand, Compiler choice, Dvips and Dvipdfm, Post-processing
@subsection Source file expansion

The module @command{expand} produces a LaTeX source from the original one by
expanding included files and packages. If the main file is @file{foo.tex}
then then expanded file will be named @file{foo-final.tex}. This file will be
self-contained, in particular it will not need BibTeXing nor user-defined
packages, as may be required when preparing the final version of a document
for publication.

As additional effect, this module removes all comments from the source file
(including those that may contain Rubber directives). It also removes any text
that may be present after @code{\end@{document@}}.

Please note that this module is rather experimental.

@noindent
The following options control how the expansion is done:

@table @option
@item class
If the document class is user-defined (i.e. if it is in a local directory
instead of a system directory), the @code{\documentclass} call will be
replaced by the code of the @file{.cls} file. Note that this is dangerous in
general.

@item nobib
Do not expand the bibliography. When this option is @emph{not} present, any
call to @command{\bibiography} is discarded and the call to
@command{\bibliographystyle} is replaced by the document's @file{.bbl} file.

@item nopkg
Do not expand user-defined packages. When this option is @emph{not} present,
local packages (i.e. those that are in the current directory) are replaced by
their contents.
@end table

@node Compiler choice, Graphics, Expand, Modules
@section Changing compilers

The following modules are used to change the LaTeX compiler:

@vtable @command
@item aleph
Use the Aleph compiler instead of TeX, i.e. compile with @command{lamed}
instead of @command{latex}.

@item omega
Use the Omega compiler instead of TeX, i.e. compiles the document using
@command{lambda} instead of @command{latex}. If the module @command{dvips} is
used too, it will use @command{odvips} to translate the DVI file. Note that
this module is triggered automatically when the document uses the package
@command{omega}.

@item pdftex
Instructs Rubber to use @command{pdflatex} instead of @command{latex} to
compile the document. By default, this produces a PDF file instead of a DVI,
but when loading the module with the option @option{dvi} (for instance by
saying @option{-m pdftex:dvi}) the document is compiled into DVI using
@command{pdflatex}.  This module is also loaded by the command line option
@option{--pdf}.

@item vtex
Instructs Rubber to use the VTeX compiler. By default this uses
@command{vlatex} as the compiler to produce PDF output. With the option
@option{ps} (e.g. when saying @command{rubber -m vtex:ps foo.tex}) the
compiler used is @command{vlatexp} and the result is a PostScript file.
@end vtable


@c ---  Graphics conversion  ---

@node Graphics, Conversion algorithm, Compiler choice, Top
@chapter Graphics conversion

Rubber includes a system for automatic conversion of graphics (and other
files) between various file formats. This is used when graphics are included
using commands from the packages @command{graphicx}, @command{graphics} or
@command{epsfig}.

When a graphics inclusion macro like @command{\includegraphics} (even with the
parameters allowed by the @command{graphicx} package) or @command{\epsfig} is
found in a LaTeX source, Rubber looks for the corresponding file or a way to
generate it. If the call to the macro does not specify a file extension, then
the list of possible suffixes is tried (according to the current compiler and
the options passed to the graphics package). For each possible file name,
Rubber tries to find a good way to convert this file from a source, and looks
for the file itself. The precise method is described in
@ref{Conversion algorithm}.

@menu
* Conversion algorithm::  How conversion rules are guessed.
* Standard rules::        List of standard conversion rules.
* rules.ini::             Syntax of rules.ini.
@end menu

@node Conversion algorithm, Standard rules, Graphics, Graphics
@section Conversion algorithm

Files are converted using conversion rules, as described in
@ref{Standard rules}, and each rule can take a number of formats as input and
produce a number of formats as output.

Assume you are using @command{pdflatex} to compile a document that contains a
macro call @command{\includegraphics@{foo@}}. Since @command{pdftex} only
accepts figures in @file{png}, @file{pdf} and @file{jpg} format, one
of @file{foo.png}, @file{foo.pdf} and @file{foo.jpg} must be available. If the
only available file around happens to be @file{foo.gif}, it has to be
translated into one of these formats. There are tools to convert @file{gif}
files into just about any other format, so we have to choose the proper
conversion to perform.

Hence all rules have a @emph{cost}, an integer that represents how unlikely a
given conversion is. For instance the rule form @command{.fig} to
@command{.eps} files (for XFig support) has cost zero because it is almost
certain that this is the expected rule when the @command{.fig} file exists. On
the other hand, the rule from @command{.eps} to @command{.jpeg} has cost 11
because this conversion is possible though usually not wanted.

Now assume that a directory contains a LaTeX source that contains
@command{\includegraphics@{foo@}} and that both @file{foo.eps} and
@file{foo.pdf} are present, because we want to compile the document both to
PostScript and to PDF format. How can Rubber decide which figure is the source
file and which is converted from the other? By default, in this situation, no
conversion will ever be performed, since there is no way to decide. Generally,
a file will never be overwritten if the source could have been produced by
some conversion rule. This behaviour can be overridden using the
@command{make} directive, see @ref{General directives}.

To sum up, for each requested file, the detection algorithm works as follows.
If relevant, take all possible suffixes (i.e. all accepted file formats, if no
format is specified in the source), and take all possible directories where
the file will be searched for by LaTeX. In each case, you get a file name
@file{foo}. If there is an applicable rule with cost at most 0 to produce
@file{foo}, use that rule. Otherwise, if the file @file{foo} exists, use it
without conversion. Otherwise use the applicable rule with the least cost. If
all fails, proceed to the next file name.

The list of standard rules is defined in the file @command{rules.ini} in the
data directory. The syntax of this file is described in @ref{rules.ini}, the
standard rules are described in @ref{Standard rules}. Additional rules can be
defined in a file with the same format and declared using the directive
@command{rules}.

The path searched for graphics files is the same as that for LaTeX inputs by
default. If the macro @command{\graphicspath} is used, the specified paths are
also searched, the same way as LaTeX does. Limited support is also provided
for the @command{\DeclareGraphicsExtensions} and
@command{\DeclareGraphicsRule} macros.

@node Standard rules, rules.ini, Conversion algorithm, Graphics
@section Standard conversion rules

The following built-in rules are available:

@table @command
@item eps_gz
This rule is used to extract a bounding box from a gzipped EPS file, in order
to be able to compile a document while keeping large figure files compressed.

@item fig2dev
This is the exporting program that goes with XFig. It is used to convert files
in @file{.fig} format into EPS, PDF or PNG. Rubber also supports the use of
combined EPS/LaTeX of PDF/LaTeX, it is detected when an @command{\input} macro
refers to a filename that ends in @file{.eps_t} or @file{.pstex_t}. When the
suffix is @file{.eps_t} or @file{.pdf_t}, the same document will compile both
in PostScript and PDF.

@item mpost
MetaPost has extra support in Rubber. If a graphics is included with a
filename that ends with a dot and a decimal number like @file{foo.42}, then
it is considered to be generated from @file{foo.mp} if it exists. Dependency
analysis is performed between MetaPost sources, so that recompilation always
occurs when needed. If the compilation of a MetaPost source fails, the errors
are reported as it would be done for LaTeX errors.

@item shell
Other programs can be used using the @command{shell} rule. This rule takes an
extra parameter @code{command}, specified in the rule file, that defines a
shell command-line. This is used for simple conversion rules using
command-line tools like @command{convert} (from ImageMagick),
@command{epstopdf}.
@end table

@node rules.ini, Encoding, Standard rules, Graphics
@section Syntax of @command{rules.ini}

The rules file has a format in the style of Wind*ws INI files. The lines that
start with a semicolon @code{;} are comments, empty lines are ignored. The
file is decomposed in sections, each introduced by a line of the form

@example
[rule-name]
@end example

@noindent
where @code{rule-name} is a unique identifier for the rule. Following this
header are lines of the form

@example
key = value
@end example

@noindent
where @code{key} is an attribute name and @code{value} is its value, without
any quotes. The spaces around the value are stripped.

@noindent
The following attributes are used:

@table @code
@item target
A regular expression that matches the target file name.
@item source
A template that describes the source file name, with references to groups
marked in the target expression as @code{\1}, @code{\2} etc. This template may
also contain choices of the form @code{@{foo,bar,quux@}} to denote several
possibilities for the source name.
@item rule
The name of the conversion rule. This name currently refers to internal
modules of Rubber, as described in @ref{Standard rules}.
@item cost
The cost of the rule, as an integer. In the default file, this ranges between
0 and 12.
@end table

@node Encoding, Index, rules.ini, Top
@chapter Encoding issues

@menu
* Design choices about encoding::   Design choices about input and output encoding
* Conversion to UTF-8::             Conversion of legacy sources to UTF-8
* Non UTF-8 sources::               Handling of unconverted legacy sources
@end menu

@node Design choices about encoding, Conversion to UTF-8, Encoding, Encoding
@section Design choices about input and output encoding.

Since version 1.5, rubber decodes @file{.tex} sources and log files
with the UTF-8 encoding.
Legacy 8-bits encodings are quite common,
but can easily be converted,
and should become rare now that the LaTeX community recommends UTF-8
for new documents.

For data exchanged with the underlying operating system,
like arguments received from the command line,
paths passed to subprocesses
or messages displayed on the console,
it makes sense that rubber uses the system default encoding:
generally UTF-8,
a code page depending on local settings on Windows.

In the rare cases where it converts auxiliary files by itself, rubber
simply avoids to decode, and only deals with bytes between 0 and 127.

@node Conversion to UTF-8, Non UTF-8 sources, Design choices about encoding, Encoding
@section Conversion of legacy sources to UTF-8

Most text editors allow you to explicitly select this encoding for
newly created files.

An existing source with any other encoding can be converted, either by
selecting the appropriate option when saving from your favorite
editor, or with a dedicated tool.
For example, the following commands translate @file{doc.tex} from the
@option{latin1} encoding.
@example
cp doc.tex doc.tex.bak
iconv doc.tex.bak -f latin1 -o doc.tex -t utf-8
@end example
You should then update the @code{inputenc} line,
check that the compilation goes well,
and finally remove the @file{doc.tex.bak} backup.

Legacy US-ASCII sources, only containing bytes betwen 0 and 127 and
relying on TeX constructs like @code{\'e} to encode local characters,
are valid UTF-8 sources, and will be decoded correctly.  No conversion
is needed.

More generally, conversion from usual (8-bits, US-ASCII-compatible)
encodings will only replace bytes from 128 to 255 with new UTF-8 byte
sequences, but US-ASCII bytes will remain unchanged.

@node Non UTF-8 sources, Encoding, Conversion to UTF-8, Encoding
@section Handling of unconverted legacy sources

For various reasons, some sources cannot be converted.
Rubber attempts to deal with them,
but the result will never be perfect.

Accurate detection of the source encoding is not as easy as it seems.
An @code{inputenc} command anywhere in an included @file{.tex} source
can affect remaining bytes in all including files.
Its arguments can be generated,
or depend on the result of a test.
In other words, rubber would need a full TeX interpreter,
including features that the author now consider as bugs,
like tolerating encoding errors inside comments.

Instead, rubber translates
bytes from 0 to 127 to the right ASCII character,
most bytes from 128 to 255 to the Unicode replacement character
 (often displayed as an empty square),
and rare sequences of such bytes as random non-ASCII characters.

All encodings encountered in the TeX world share the
property that a byte between 0 and 127 anywhere in the file always
represents a single US-ASCII character, and that such characters
cannot be represented by another byte sequence.
Since rubber searches for TeX commands expressed with such characters,
it will most of the time be able to work even if it ignores all other bytes.

Non-ASCII characters will look ugly in log messages displayed on the
screen, and this is acceptable.

Real problems may occur when commands intended for cooperation with
the underlying operating system,
like @code{\includegraphics} or @code{\input},
receive arguments, like paths, containing non-ASCII characters.

These characters will be decoded incorrectly, resulting in various
problems later (no file found with the given path, for example).
This problem is not specific to rubber,
and such path arguments should always be formed of ASCII characters,
ideally roman letters, decimal digits and a dot for the extension.

@c ---  Indices  ---

@node Index, Directive index, Encoding, Top
@chapter Index

@menu
* Directive index::
* Module index::
@end menu

@node Directive index, Module index, Index, Index
@ifnothtml
@section Index of directives
@printindex fn
@end ifnothtml

@node Module index, , Directive index, Index
@ifnothtml
@section Index of modules
@printindex vr
@end ifnothtml

@bye
