Provided by: rubber_1.6.0-2_all bug

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,  including  the compilation of the next documents on the command line, and
       rubber 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  equivalent  to  saying  -o
              bzip2 after all other options.

       --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 <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 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 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 <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 document 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 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(1) to produce 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 during compilation.  The
              available types are: boxes (overfull  and  underfull  boxes),  refs  (undefined  or
              multiply defined references), 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 provided by default to include new features (this is  the
       point of the module 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 document 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 makeindex(1) when needed (see
              section DIRECTIVES for options).

       ltxtable
              Add dependencies for files inserted via the ltxtable LaTeX package.

       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.

       xr     Add additional .aux files used for external references to the list of dependencies,
              so recompiling is automatic when referenced 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 modules: 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 document.

       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 document using lamed(1)
              instead of latex.

       omega  Use the Omega compiler instead of TeX, i.e. compiles the document  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 compile 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 spaces, 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 cleaning using --clean.

       depend <file>
              Consider the specified file as a dependency, so that its modification 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 documentation 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  contents 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 documentation for details.

       set <name> <value>
              Set the value of a variable as a string.  For details on the existing 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 meaning, 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 databases (.bib files).

       bibtex.crossrefs <number>
              Set the minimum  number  of  crossref  required  for  automatic  inclusion  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 databases (.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 applies to all indices.

       index.language (index) <language>
              Selects the language used for sorting the index.   This  only  applies  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 argument 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  homepage  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)