Provided by: rubber_1.1-2.4ubuntu1_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  (this currently means CWEB or Literate Haskell documents).
       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.

       --cache
              Use the experimental cache  system.   This  uses  a  file  named
              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 <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.

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

       -l, --landscape
              Specify  that  the   final   document   should   use   landscape
              orientation.  This is relevant only when using dvips or dvipdfm.

       -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, --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.

       -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:

       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  (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.

       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
              Process the document's index (or indexes) with makeindex(1) when
              needed (see section DIRECTIVES for options).

       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
              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

       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.

       etex   Instructs Rubber to use elatex(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.

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.

       paper <options>
              Specify options related to paper size.  Currently they are  used
              to give -t options to dvips and -p options to dvipdfm.

       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".

       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.   For  details on the existing
              variables and their meaning, see the info documentataion.

       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:

       bibtex.path <directory>
              Adds the specified directory  to  the  search  path  for  BibTeX
              databases (.bib files).

       bibtex.sorted <boolean>
              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 <directory>
              Adds the specified directory  to  the  search  path  for  BibTeX
              styles (.bst files).

       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.

BUGS

       There are surely a some...

       This page documents Rubber version 1.1.  The program and this  man-page
       are  maintained  by  Emmanuel Beffara <manu@beffara.org>.  The homepage
       for          Rubber          can          be          found          at
       http://www.pps.jussieu.fr/~beffara/soft/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)