1RUBBER(1)                   General Commands Manual                  RUBBER(1)
2
3
4

NAME

6       rubber - a building system for LaTeX documents
7

SYNOPSIS

9       rubber [options] sources ...
10       rubber-pipe [options]
11

DESCRIPTION

13       Rubber  is a wrapper for LaTeX and companion programs.  Its purpose is,
14       given a LaTeX source to process, to compile it enough times to  resolve
15       all  references,  possibly  running  satellite programs such as BibTeX,
16       makeindex, Metapost, etc. to produce appropriate data files.
17
18       The command rubber builds  the  specified  documents  completely.   The
19       source files may be either LaTeX sources (in which case the suffix .tex
20       may be omitted) or documents in a format Rubber knows how to  translate
21       into LaTeX.  If one compilation fails, the whole process stops, includ‐
22       ing the compilation of the next documents on the command line, and rub‐
23       ber returns a non-zero exit code.
24
25       The command rubber-pipe does the same for one document but it reads the
26       LaTeX source from standard input and dumps  the  compiled  document  on
27       standard output.
28
29       Some  information  cannot be extracted from the LaTeX sources.  This is
30       the case, for instance, with the search paths (which can  be  specified
31       in  environment variables like TEXINPUTS), or the style to be used with
32       Makeindex.  To address this problem, one can add information for Rubber
33       in the comments of the LaTeX sources, see section DIRECTIVES.
34

OPTIONS

36       The  options are used either to choose the action to be performed or to
37       configure the building process.  They are mostly the same in rubber and
38       rubber-pipe.  Options are parsed using GNU Getopt conventions.
39
40       -b, --bzip2
41              Compress  the final document (in bzip2 format).  This is equiva‐
42              lent to saying -o bzip2 after all other options.
43
44       --clean
45              Remove all files produced by the compilation, instead of  build‐
46              ing  the  document.   This option is present in rubber only.  It
47              applies to the compilation as it would be done  with  the  other
48              options  of  the  command line, i.e. saying "rubber --clean foo"
49              will not delete foo.ps, while saying "rubber --ps  --clean  foo"
50              will.
51
52       -c, --command <command>
53              Execute  the specified command (or directive) before parsing the
54              input files.  See section DIRECTIVES for details.
55
56       -e, --epilogue <command>
57              Execute the specified command (or directive) after  parsing  the
58              input files.  See section DIRECTIVES for details.
59
60       -f, --force
61              Force  at least one compilation of the source.  This may be use‐
62              ful, for instance, if some unusual dependency was modified (e.g.
63              a  package in a system directory).  This option is irrelevant in
64              rubber-pipe.
65
66       -z, --gzip
67              Compress the final document (in gzip format).  This  is  equiva‐
68              lent to saying -o gz after all other options.
69
70       -h, --help
71              Display the list of all available options and exit nicely.
72
73       --inplace
74              Go  to  the  directory  of the source files before compiling, so
75              that compilation results are in the same place as their sources.
76
77       --into <directory>
78              Go to the specified directory  before  compiling,  so  that  all
79              files are produced there and not in the current directory.
80
81       --jobname <name>
82              Specify  a  job  name  different  from the base file name.  This
83              changes the name of output files and only applies to  the  first
84              target.
85
86       -k, --keep
87              This  option is used in rubber-pipe only.  With this option, the
88              temporary files will not be removed after compiling the document
89              and dumping the results on standard output.  The temporary docu‐
90              ment is named rubtmpX.tex, where X is a number such that no file
91              of that name exists initially.
92
93       -n, --maxerr <num>
94              Set  the  maximum number of displayed errors.  By default, up to
95              10 errors are reported, saying -n -1 displays all errors.
96
97       -m, --module <module>[:<args>]
98              Use the specified module in addition to the document's packages.
99              Arguments  can  be  passed to the package by adding them after a
100              colon, they correspond to the package  options  in  LaTeX.   The
101              module is loaded before parsing the document's sources.
102
103       --only <sources>
104              Compile  the  document  partially,  including only the specified
105              sources.  This works by inserting a call to \includeonly on  the
106              command  line.   The  argument is a comma-separated list of file
107              names.
108
109       -o, --post <module>[:<args>]
110              Use the specified module as a post-processor.  This  is  similar
111              to the -m options except that the module is loaded after parsing
112              the document.
113
114       -d, --pdf
115              Produce PDF output.  When this  option  comes  after  --ps  (for
116              instance  in the form -pd) it is a synonym for -o ps2pdf, other‐
117              wise it acts as -m pdftex, in order to use pdfLaTeX  instead  of
118              LaTeX.
119
120       -p, --ps
121              Process the DVI produced by the process through dvips(1) to pro‐
122              duce a PostScript  document.   This  option  is  a  synonym  for
123              -o dvips, it cannot come after --pdf.
124
125       -q, --quiet
126              Decrease the verbosity level.  This is the reverse of -v.
127
128       -r, --read <file>
129              Read additional directives from the specified file (see also the
130              directive "read").
131
132       -S, --src-specials
133              Enable generation of source specials if  the  compiler  supports
134              it.   This is equivalent to setting the variable src-specials to
135              yes.
136
137       -s, --short
138              Display LaTeX's error messages in a compact form (one error  per
139              line).
140
141       -I, --texpath <directory>
142              Add the specified directory to TeX's search path.
143
144       --synctex
145              Enable SyncTeX support in the LaTeX run.
146
147       --unsafe
148              Permit the document to invoke arbitrary external programs.  This
149              is potentially dangerous, only use  this  option  for  documents
150              coming from a trusted source.
151
152       -v, --verbose
153              Increase the verbosity level.  Levels between 0 and 4 exist, the
154              default level is 1 for rubber and 0  for  rubber-pipe.   Beware,
155              saying -vvv makes Rubber speak a lot.
156
157       --version
158              Print the version number and exit nicely.
159
160       -W, --warn <type>
161              Report  information of the given type if there was no error dur‐
162              ing compilation.  The available types are: boxes  (overfull  and
163              underfull  boxes),  refs  (undefined  or multiply defined refer‐
164              ences), misc (other warnings) and all to report all warnings.
165

MODULES

167       Rubber's action is influenced by modules.  Modules  take  care  of  the
168       particular features of packages and external programs.
169
170   Packages
171       For  every  package  that a document uses, Rubber looks for a module of
172       the same name to perform the tasks that this package my  require  apart
173       from  the  compilation by LaTeX.  Modules can be added to the ones pro‐
174       vided by default to include new features (this is the point of the mod‐
175       ule system).  The standard modules are the following:
176
177       asymptote
178              Process  the  .asy  files  generated  by the LaTeX package, then
179              triggers a recompilation.
180
181       beamer This module handles Beamer's extra files the same way  as  other
182              tables of contents.
183
184       bibtex, biblatex
185              Takes care of processing the document's bibliography with BibTeX
186              when needed.  This module is automatically loaded if  the  docu‐
187              ment  contains  the  macro \bibliography (see also in DIRECTIVES
188              for options).
189
190       combine
191              The combine package is used to gather  several  LaTeX  documents
192              into  a  single one, and this module handles the dependencies in
193              this case.
194
195       epsfig This modules handles graphics inclusion for the  documents  that
196              use the old style \psfig macro.  It is actually an interface for
197              the graphics module, see this one for details.
198
199       glossaries
200              Run makeglossaries and recompiles when the .glo file changes.
201
202       graphics, graphicx
203              These modules identify the graphics included in the document and
204              consider  them  as  dependencies for compilation.  They also use
205              standard rules to build these files with external programs.  See
206              the info documentation for details.
207
208       hyperref
209              Handle the extra files that this package produces in some cases.
210
211       index, makeidx, nomencl
212              Process  the  document's  indexes and nomenclatures with makein‐
213              dex(1) when needed (see section DIRECTIVES for options).
214
215       ltxtable
216              Add dependencies for files inserted via the ltxtable LaTeX pack‐
217              age.
218
219       minitoc, minitoc-hyper
220              On  cleaning, remove additional files that produced to make par‐
221              tial tables of contents.
222
223       moreverb, verbatim
224              Adds the files included with \verbatiminput and  similar  macros
225              to the list of dependencies.
226
227       multibib
228              Handles  the extra bibliographies that this package creates, and
229              removes the extra files on cleaning.
230
231       xr     Add additional .aux files used for external  references  to  the
232              list  of  dependencies,  so recompiling is automatic when refer‐
233              enced document are changed.
234
235   Pre-processing
236       The following modules are provided for using programs that  generate  a
237       LaTeX source from a different file format:
238
239       cweb   This  module's  purpose is to run cweave(1) if needed before the
240              compiling process to produce the LaTeX source.  This  module  is
241              automatically  loaded  if the file specified on the command line
242              has .w as its suffix.
243
244       lhs2TeX
245              This module uses the lhs2TeX preprocessor to generate the  LaTeX
246              source  from  a  Literate  Haskell program.  It is automatically
247              triggered if the input file's name ends with .lhs.
248
249   Post-processing
250       The following modules  are  provided  to  support  different  kinds  of
251       post-processings.   Note  that  the order matters when using these mod‐
252       ules: if you want to use a processing chain like
253              foo.tex -> foo.dvi -> foo.ps -> foo.pdf -> foo.pdf.gz
254       you have to load the modules dvips, ps2pdf and gz in  that  order,  for
255       instance using the command line
256              rubber -p -o ps2pdf -z foo.tex
257
258       bzip2  Produce a version of the final file compressed with bzip2(1).
259
260       dvipdfm
261              Runs dvipdfm(1) at the end of compilation to produce a PDF docu‐
262              ment.
263
264       dvips  Runs dvips(1) at the end of compilation to produce a  PostScript
265              document.  This module is also loaded by the command line option
266              --ps.
267
268       expand Produce an expanded LaTeX source by replacing \input  macros  by
269              included files, bibliography macros by the bibliography produced
270              by bibtex(1), and local classes and packages  by  their  source.
271              If  the  main  file  is  foo.tex then then expanded file will be
272              named foo-final.tex.  See the info documentation for details.
273
274       gz     Produce a version of the final file compressed with gzip(1).
275
276       ps2pdf Assuming that the compilation  produces  a  PostScript  document
277              (for  instance using module dvips), convert this document to PDF
278              using ps2pdf(1).
279
280   Compiler choice
281       The following modules are used to change the LaTeX compiler:
282
283       aleph  Use the Aleph compiler instead of TeX, i.e. compiles  the  docu‐
284              ment using lamed(1) instead of latex.
285
286       omega  Use  the  Omega compiler instead of TeX, i.e. compiles the docu‐
287              ment using lambda(1) instead of latex.  If the module  dvips  is
288              used too, it will use odvips(1) to translate the DVI file.  Note
289              that this module is triggered automatically  when  the  document
290              uses the package omega.
291
292       pdftex Instructs  Rubber to use pdflatex(1) instead of latex(1) to com‐
293              pile the document. By default, this produces a PDF file  instead
294              of  a  DVI, but when loading the module with the option dvi (for
295              instance by saying -m pdftex:dvi) the document is compiled  into
296              DVI  using  pdflatex.  This module is also loaded by the command
297              line option --pdf.
298
299       vtex   Instructs Rubber to use the VTeX compiler.  By default this uses
300              vlatex  as  the compiler to produce PDF output.  With the option
301              ps (e.g. when saying "rubber -m vtex:ps foo.tex")  the  compiler
302              used is vlatexp and the result is a PostScript file.
303
304       xelatex
305              Instructs Rubber to use xelatex(1) instead of latex.
306

DIRECTIVES

308       The  automatic  behavior  of Rubber is based on searching for macros in
309       the LaTeX sources.  When this is not enough, directives can be added in
310       the comments of the sources.  A directive is a line like
311              % rubber: cmd args
312       The line must begin with a "%", then any sequence of "%" signs and spa‐
313       ces, then the text "rubber:" followed by spaces  and  a  command  name,
314       possibly followed by spaces and arguments.
315
316   General directives
317       alias <name1> <name2>
318              Pretend that the LaTeX macro name1 is equivalent to name2.  This
319              can be useful when defining wrappers around supported macros.
320
321       clean <file>
322              Indicates that the specified file should be removed when  clean‐
323              ing using --clean.
324
325       depend <file>
326              Consider the specified file as a dependency, so that its modifi‐
327              cation time will be checked.
328
329       make <file> [<options>]
330              Declare that the specified file has to  be  generated.   Options
331              can specify the way it should be produced, the available options
332              are from <file> to specify the source and with <rule> to specify
333              the  conversion  rule.   For instance, saying "make foo.pdf from
334              foo.eps" indicates that foo.pdf should be produced from foo.eps,
335              with  any conversion rule that can do it.  See the info documen‐
336              tation for details on file conversion.
337
338       module <module> [<options>]
339              Loads the specified module,  possibly  with  options.   This  is
340              equivalent to the command-line option --module.
341
342       onchange <file> <command>
343              Execute  the specified shell command after compiling if the con‐
344              tents of the specified file have changed.  The file name ends at
345              the first space.
346
347       path <directory>
348              Adds  the  specified  directory  to the search path for TeX (and
349              Rubber).  The name of the directory is everything  that  follows
350              the spaces after "path".
351
352       produce <file>
353              Declares  that the LaTeX run will create or update the specified
354              file(s).
355
356       read <file>
357              Read the specified file of directives.  The  file  must  contain
358              one  directive  per line.  Empty lines and lines that begin with
359              "%" are ignored.
360
361       rules <file>
362              Read extra conversion rules from the specified file.  The format
363              of this file is the same as that of rules.ini, see the info doc‐
364              umentation for details.
365
366       set <name> <value>
367              Set the value of a variable as a string.   For  details  on  the
368              existing  variables  and  their meaning, see the info documenta‐
369              tion.
370
371       setlist <name> <values>
372              Set the value of a  variable  as  a  (space-separated)  list  of
373              strings.   For details on the existing variables and their mean‐
374              ing, see the info documentation.
375
376       shell_escape
377              Mark the document as requiring external  programs  (shell-escape
378              or write18).  Rubber does not actually enable this unless called
379              with the option --unsafe.
380
381       synctex
382              Enable SyncTeX support in the LaTeX run.
383
384       watch <file>
385              Watch the specified file for changes.  If the contents  of  this
386              file  has  changed after a compilation, then another compilation
387              is triggered.  This is useful in the case of tables of contents,
388              for instance.
389
390   Module-specific directives
391       If  a  command has the form foo.bar, it is considered a command bar for
392       the module foo.  If this module is not registered when the directive is
393       found, then the command is silently ignored.  For the standard modules,
394       the directives are the following:
395
396       biblatex.path <directory>
397              Adds the specified directory to the search path for BibTeX data‐
398              bases (.bib files).
399
400       bibtex.crossrefs <number>
401              Set the minimum number of crossref required for automatic inclu‐
402              sion of the referenced entry in the citation  list.   This  sets
403              the option -min-crossrefs when calling bibtex(1).
404
405       bibtex.path <directory>
406              Adds the specified directory to the search path for BibTeX data‐
407              bases (.bib files).
408
409       bibtex.stylepath <directory>
410              Adds the specified directory  to  the  search  path  for  BibTeX
411              styles (.bst files).
412
413       bibtex.tool <command>
414              Use a different bibliography tool instead of BibTeX.
415
416       dvipdfm.options <options>
417              Pass the specified command-line switches to dvipdfm.
418
419       dvips.options <options>
420              Pass the specified command-line switches to dvips.
421
422       index.tool (index) <name>
423              Specifies  which  tool  is to be used to process the index.  The
424              currently supported tools are makeindex(1) (the default  choice)
425              and xindy(1).  The argument index is optional, it may be used to
426              specify the list  of  indexes  the  command  applies  to.   When
427              present,  it must be enclosed in parentheses; the list is comma-
428              separated.  When  the  argument  is  not  present,  the  command
429              applies to all indices.
430
431       index.language (index) <language>
432              Selects  the  language  used  for  sorting the index.  This only
433              applies when using xindy(1) as the indexing tool.  The  optional
434              argument has the same semantics as above.
435
436       index.modules (index) <module>...
437              Specify  which  modules  to  use  when  processing an index with
438              xindy(1).  The optional  argument  has  the  same  semantics  as
439              above.
440
441       index.order (index) <options>
442              Modifies the sorting options for the indexes.  The arguments are
443              words (separated by spaces) among standard, german  and  letter.
444              This  only  applies when using makeindex(1).  The optional argu‐
445              ment has the same semantics as above.
446
447       index.path (index) <directory>
448              Adds the specified directory to the search path for index styles
449              (.ist  files).   The optional argument has the same semantics as
450              above.
451
452       index.style (index) <style>
453              Specifies the index style to be used.  The optional argument has
454              the same semantics as above.
455
456       makeidx.language, .modules, .order, .path, .style, .tool
457              These  directives  are  the same as for the index module, except
458              that they don't accept the optional argument.
459
460       multibib.crossrefs, .path, .stylepath, .tool
461              These directives are the same as for the bibtex module but  they
462              apply  to  bibliographies managed by the multibib package.  They
463              take an optional first argument, with the same convention as for
464              the directives of the index module, which may be used to specify
465              the list of bibliographies the command applies to.
466

BUGS

468       There are surely a some...
469
470       This page documents Rubber version 1.5.1.  The program  and  this  man-
471       page are maintained by Sebastian Kapfer <sebastian.kapfer@fau.de>.  The
472       homepage for Rubber can be found at https://launchpad.net/rubber/.
473

SEE ALSO

475       The full documentation for rubber is maintained as  a  Texinfo  manual.
476       If  the  info  and rubber programs are properly installed at your site,
477       the command
478
479              info rubber
480
481       should give you access to the complete manual.
482
483
484
485                                                                     RUBBER(1)
Impressum