1RUBBER(1) General Commands Manual RUBBER(1)
2
6 rubber - a building system for LaTeX documents
7
9 rubber [options] sources ...
10 rubber-pipe [options]
11
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 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 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 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
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 -b, --bzip2
41 Compress the final document (in bzip2 format). This is equiva‐
42 lent to saying -o bzip2 after all other options.
43 --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 -c, --command <command>
53 Execute the specified command (or directive) before parsing the
54 input files. See section DIRECTIVES for details.
55 -e, --epilogue <command>
57 Execute the specified command (or directive) after parsing the
58 input files. See section DIRECTIVES for details.
59 -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 -z, --gzip
67 Compress the final document (in gzip format). This is equiva‐
68 lent to saying -o gz after all other options.
69 -h, --help
71 Display the list of all available options and exit nicely.
72 --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 --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 --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 -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 -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 -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 --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 -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 -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 -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 -q, --quiet
126 Decrease the verbosity level. This is the reverse of -v.
127 -r, --read <file>
129 Read additional directives from the specified file (see also the
130 directive "read").
131 -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 -s, --short
138 Display LaTeX's error messages in a compact form (one error per
139 line).
140 -I, --texpath <directory>
142 Add the specified directory to TeX's search path.
143 --synctex
145 Enable SyncTeX support in the LaTeX run.
146 --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 -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 --version
158 Print the version number and exit nicely.
159 -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
167 Rubber's action is influenced by modules. Modules take care of the
168 particular features of packages and external programs.
169 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 asymptote
178 Process the .asy files generated by the LaTeX package, then
179 triggers a recompilation.
180 beamer This module handles Beamer's extra files the same way as other
182 tables of contents.
183 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 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 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 glossaries
200 Run makeglossaries and recompiles when the .glo file changes.
201 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 hyperref
209 Handle the extra files that this package produces in some cases.
210 index, makeidx, nomencl
212 Process the document's indexes and nomenclatures with makein‐
213 dex(1) when needed (see section DIRECTIVES for options).
214 ltxtable
216 Add dependencies for files inserted via the ltxtable LaTeX pack‐
217 age.
218 minitoc, minitoc-hyper
220 On cleaning, remove additional files that produced to make par‐
221 tial tables of contents.
222 moreverb, verbatim
224 Adds the files included with \verbatiminput and similar macros
225 to the list of dependencies.
226 multibib
228 Handles the extra bibliographies that this package creates, and
229 removes the extra files on cleaning.
230 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 Pre-processing
236 The following modules are provided for using programs that generate a
237 LaTeX source from a different file format:
238 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 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 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 bzip2 Produce a version of the final file compressed with bzip2(1).
259 dvipdfm
261 Runs dvipdfm(1) at the end of compilation to produce a PDF docu‐
262 ment.
263 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 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 gz Produce a version of the final file compressed with gzip(1).
275 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 Compiler choice
281 The following modules are used to change the LaTeX compiler:
282 aleph Use the Aleph compiler instead of TeX, i.e. compiles the docu‐
284 ment using lamed(1) instead of latex.
285 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 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 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 xelatex
305 Instructs Rubber to use xelatex(1) instead of latex.
306
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 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 clean <file>
322 Indicates that the specified file should be removed when clean‐
323 ing using --clean.
324 depend <file>
326 Consider the specified file as a dependency, so that its modifi‐
327 cation time will be checked.
328 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 module <module> [<options>]
339 Loads the specified module, possibly with options. This is
340 equivalent to the command-line option --module.
341 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 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 produce <file>
353 Declares that the LaTeX run will create or update the specified
354 file(s).
355 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 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 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 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 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 synctex
382 Enable SyncTeX support in the LaTeX run.
383 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 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 biblatex.path <directory>
397 Adds the specified directory to the search path for BibTeX data‐
398 bases (.bib files).
399 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 bibtex.path <directory>
406 Adds the specified directory to the search path for BibTeX data‐
407 bases (.bib files).
408 bibtex.stylepath <directory>
410 Adds the specified directory to the search path for BibTeX
411 styles (.bst files).
412 bibtex.tool <command>
414 Use a different bibliography tool instead of BibTeX.
415 dvipdfm.options <options>
417 Pass the specified command-line switches to dvipdfm.
418 dvips.options <options>
420 Pass the specified command-line switches to dvips.
421 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 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 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 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 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 index.style (index) <style>
453 Specifies the index style to be used. The optional argument has
454 the same semantics as above.
455 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 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
468 There are surely a some...
469 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
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 info rubber
480 should give you access to the complete manual.
482 RUBBER(1)