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 -l, --landscape
94 Specify that the final document should use landscape orienta‐
95 tion. This is relevant only when using dvips or dvipdfm.
96 -n, --maxerr <num>
98 Set the maximum number of displayed errors. By default, up to
99 10 errors are reported, saying -n -1 displays all errors.
100 -m, --module <module>[:<args>]
102 Use the specified module in addition to the document's packages.
103 Arguments can be passed to the package by adding them after a
104 colon, they correspond to the package options in LaTeX. The
105 module is loaded before parsing the document's sources.
106 --only <sources>
108 Compile the document partially, including only the specified
109 sources. This works by inserting a call to \includeonly on the
110 command line. The argument is a comma-separated list of file
111 names.
112 -o, --post <module>[:<args>]
114 Use the specified module as a post-processor. This is similar
115 to the -m options except that the module is loaded after parsing
116 the document.
117 -d, --pdf
119 Produce PDF output. When this option comes after --ps (for
120 instance in the form -pd) it is a synonym for -o ps2pdf, other‐
121 wise it acts as -m pdftex, in order to use pdfLaTeX instead of
122 LaTeX.
123 -p, --ps
125 Process the DVI produced by the process through dvips(1) to pro‐
126 duce a PostScript document. This option is a synonym for
127 -o dvips, it cannot come after --pdf.
128 -q, --quiet
130 Decrease the verbosity level. This is the reverse of -v.
131 -r, --read <file>
133 Read additional directives from the specified file (see also the
134 directive "read").
135 -S, --src-specials
137 Enable generation of source specials if the compiler supports
138 it. This is equivalent to setting the variable src-specials to
139 yes.
140 -s, --short
142 Display LaTeX's error messages in a compact form (one error per
143 line).
144 -I, --texpath <directory>
146 Add the specified directory to TeX's search path.
147 --synctex
149 Enable SyncTeX support in the LaTeX run.
150 --unsafe
152 Permit the document to invoke arbitrary external programs. This
153 is potentially dangerous, only use this option for documents
154 coming from a trusted source.
155 -v, --verbose
157 Increase the verbosity level. Levels between 0 and 4 exist, the
158 default level is 1 for rubber and 0 for rubber-pipe. Beware,
159 saying -vvv makes Rubber speak a lot.
160 --version
162 Print the version number and exit nicely.
163 -W, --warn <type>
165 Report information of the given type if there was no error dur‐
166 ing compilation. The available types are: boxes (overfull and
167 underfull boxes), refs (undefined or multiply defined refer‐
168 ences), misc (other warnings) and all to report all warnings.
169
171 Rubber's action is influenced by modules. Modules take care of the
172 particular features of packages and external programs.
173 Packages
175 For every package that a document uses, Rubber looks for a module of
176 the same name to perform the tasks that this package my require apart
177 from the compilation by LaTeX. Modules can be added to the ones pro‐
178 vided by default to include new features (this is the point of the mod‐
179 ule system). The standard modules are the following:
180 asymptote
182 Process the .asy files generated by the LaTeX package, then
183 triggers a recompilation.
184 beamer This module handles Beamer's extra files the same way as other
186 tables of contents.
187 bibtex, biblatex
189 Takes care of processing the document's bibliography with BibTeX
190 when needed. This module is automatically loaded if the docu‐
191 ment contains the macro \bibliography (see also in DIRECTIVES
192 for options).
193 combine
195 The combine package is used to gather several LaTeX documents
196 into a single one, and this module handles the dependencies in
197 this case.
198 epsfig This modules handles graphics inclusion for the documents that
200 use the old style \psfig macro. It is actually an interface for
201 the graphics module, see this one for details.
202 glossaries
204 Run makeglossaries and recompiles when the .glo file changes.
205 graphics, graphicx
207 These modules identify the graphics included in the document and
208 consider them as dependencies for compilation. They also use
209 standard rules to build these files with external programs. See
210 the info documentation for details.
211 hyperref
213 Handle the extra files that this package produces in some cases.
214 index, makeidx, nomencl
216 Process the document's indexes and nomenclatures with makein‐
217 dex(1) when needed (see section DIRECTIVES for options).
218 ltxtable
220 Add dependencies for files inserted via the ltxtable LaTeX pack‐
221 age.
222 minitoc, minitoc-hyper
224 On cleaning, remove additional files that produced to make par‐
225 tial tables of contents.
226 moreverb, verbatim
228 Adds the files included with \verbatiminput and similar macros
229 to the list of dependencies.
230 multibib
232 Handles the extra bibliographies that this package creates, and
233 removes the extra files on cleaning.
234 xr Add additional .aux files used for external references to the
236 list of dependencies, so recompiling is automatic when refer‐
237 enced document are changed.
238 Pre-processing
240 The following modules are provided for using programs that generate a
241 LaTeX source from a different file format:
242 cweb This module's purpose is to run cweave(1) if needed before the
244 compiling process to produce the LaTeX source. This module is
245 automatically loaded if the file specified on the command line
246 has .w as its suffix.
247 lhs2TeX
249 This module uses the lhs2TeX preprocessor to generate the LaTeX
250 source from a Literate Haskell program. It is automatically
251 triggered if the input file's name ends with .lhs.
252 Post-processing
254 The following modules are provided to support different kinds of
255 post-processings. Note that the order matters when using these mod‐
256 ules: if you want to use a processing chain like
257 foo.tex -> foo.dvi -> foo.ps -> foo.pdf -> foo.pdf.gz
258 you have to load the modules dvips, ps2pdf and gz in that order, for
259 instance using the command line
260 rubber -p -o ps2pdf -z foo.tex
261 bzip2 Produce a version of the final file compressed with bzip2(1).
263 dvipdfm
265 Runs dvipdfm(1) at the end of compilation to produce a PDF docu‐
266 ment.
267 dvips Runs dvips(1) at the end of compilation to produce a PostScript
269 document. This module is also loaded by the command line option
270 --ps.
271 expand Produce an expanded LaTeX source by replacing \input macros by
273 included files, bibliography macros by the bibliography produced
274 by bibtex(1), and local classes and packages by their source.
275 If the main file is foo.tex then then expanded file will be
276 named foo-final.tex. See the info documentation for details.
277 gz Produce a version of the final file compressed with gzip(1).
279 ps2pdf Assuming that the compilation produces a PostScript document
281 (for instance using module dvips), convert this document to PDF
282 using ps2pdf(1).
283 Compiler choice
285 The following modules are used to change the LaTeX compiler:
286 aleph Use the Aleph compiler instead of TeX, i.e. compiles the docu‐
288 ment using lamed(1) instead of latex.
289 omega Use the Omega compiler instead of TeX, i.e. compiles the docu‐
291 ment using lambda(1) instead of latex. If the module dvips is
292 used too, it will use odvips(1) to translate the DVI file. Note
293 that this module is triggered automatically when the document
294 uses the package omega.
295 pdftex Instructs Rubber to use pdflatex(1) instead of latex(1) to com‐
297 pile the document. By default, this produces a PDF file instead
298 of a DVI, but when loading the module with the option dvi (for
299 instance by saying -m pdftex:dvi) the document is compiled into
300 DVI using pdflatex. This module is also loaded by the command
301 line option --pdf.
302 vtex Instructs Rubber to use the VTeX compiler. By default this uses
304 vlatex as the compiler to produce PDF output. With the option
305 ps (e.g. when saying "rubber -m vtex:ps foo.tex") the compiler
306 used is vlatexp and the result is a PostScript file.
307 xelatex
309 Instructs Rubber to use xelatex(1) instead of latex.
310
312 The automatic behavior of Rubber is based on searching for macros in
313 the LaTeX sources. When this is not enough, directives can be added in
314 the comments of the sources. A directive is a line like
315 % rubber: cmd args
316 The line must begin with a "%", then any sequence of "%" signs and spa‐
317 ces, then the text "rubber:" followed by spaces and a command name,
318 possibly followed by spaces and arguments.
319 General directives
321 alias <name1> <name2>
322 Pretend that the LaTeX macro name1 is equivalent to name2. This
323 can be useful when defining wrappers around supported macros.
324 clean <file>
326 Indicates that the specified file should be removed when clean‐
327 ing using --clean.
328 depend <file>
330 Consider the specified file as a dependency, so that its modifi‐
331 cation time will be checked.
332 make <file> [<options>]
334 Declare that the specified file has to be generated. Options
335 can specify the way it should be produced, the available options
336 are from <file> to specify the source and with <rule> to specify
337 the conversion rule. For instance, saying "make foo.pdf from
338 foo.eps" indicates that foo.pdf should be produced from foo.eps,
339 with any conversion rule that can do it. See the info documen‐
340 tation for details on file conversion.
341 module <module> [<options>]
343 Loads the specified module, possibly with options. This is
344 equivalent to the command-line option --module.
345 onchange <file> <command>
347 Execute the specified shell command after compiling if the con‐
348 tents of the specified file have changed. The file name ends at
349 the first space.
350 paper <options>
352 Specify options related to paper size. Currently they are used
353 to give -t options to dvips and -p options to dvipdfm.
354 path <directory>
356 Adds the specified directory to the search path for TeX (and
357 Rubber). The name of the directory is everything that follows
358 the spaces after "path".
359 produce <file>
361 Declares that the LaTeX run will create or update the specified
362 file(s).
363 read <file>
365 Read the specified file of directives. The file must contain
366 one directive per line. Empty lines and lines that begin with
367 "%" are ignored.
368 rules <file>
370 Read extra conversion rules from the specified file. The format
371 of this file is the same as that of rules.ini, see the info doc‐
372 umentation for details.
373 set <name> <value>
375 Set the value of a variable as a string. For details on the
376 existing variables and their meaning, see the info documenta‐
377 tion.
378 setlist <name> <values>
380 Set the value of a variable as a (space-separated) list of
381 strings. For details on the existing variables and their mean‐
382 ing, see the info documentation.
383 shell_escape
385 Mark the document as requiring external programs (shell-escape
386 or write18). Rubber does not actually enable this unless called
387 with the option --unsafe.
388 synctex
390 Enable SyncTeX support in the LaTeX run.
391 watch <file>
393 Watch the specified file for changes. If the contents of this
394 file has changed after a compilation, then another compilation
395 is triggered. This is useful in the case of tables of contents,
396 for instance.
397 Module-specific directives
399 If a command has the form foo.bar, it is considered a command bar for
400 the module foo. If this module is not registered when the directive is
401 found, then the command is silently ignored. For the standard modules,
402 the directives are the following:
403 biblatex.path <directory>
405 Adds the specified directory to the search path for BibTeX data‐
406 bases (.bib files).
407 bibtex.crossrefs <number>
409 Set the minimum number of crossref required for automatic inclu‐
410 sion of the referenced entry in the citation list. This sets
411 the option -min-crossrefs when calling bibtex(1).
412 bibtex.path <directory>
414 Adds the specified directory to the search path for BibTeX data‐
415 bases (.bib files).
416 bibtex.stylepath <directory>
418 Adds the specified directory to the search path for BibTeX
419 styles (.bst files).
420 bibtex.tool <command>
422 Use a different bibliography tool instead of BibTeX.
423 dvipdfm.options <options>
425 Pass the specified command-line switches to dvipdfm.
426 dvips.options <options>
428 Pass the specified command-line switches to dvips.
429 index.tool (index) <name>
431 Specifies which tool is to be used to process the index. The
432 currently supported tools are makeindex(1) (the default choice)
433 and xindy(1). The argument index is optional, it may be used to
434 specify the list of indexes the command applies to. When
435 present, it must be enclosed in parentheses; the list is comma-
436 separated. When the argument is not present, the command
437 applies to all indices.
438 index.language (index) <language>
440 Selects the language used for sorting the index. This only
441 applies when using xindy(1) as the indexing tool. The optional
442 argument has the same semantics as above.
443 index.modules (index) <module>...
445 Specify which modules to use when processing an index with
446 xindy(1). The optional argument has the same semantics as
447 above.
448 index.order (index) <options>
450 Modifies the sorting options for the indexes. The arguments are
451 words (separated by spaces) among standard, german and letter.
452 This only applies when using makeindex(1). The optional argu‐
453 ment has the same semantics as above.
454 index.path (index) <directory>
456 Adds the specified directory to the search path for index styles
457 (.ist files). The optional argument has the same semantics as
458 above.
459 index.style (index) <style>
461 Specifies the index style to be used. The optional argument has
462 the same semantics as above.
463 makeidx.language, .modules, .order, .path, .style, .tool
465 These directives are the same as for the index module, except
466 that they don't accept the optional argument.
467 multibib.crossrefs, .path, .stylepath, .tool
469 These directives are the same as for the bibtex module but they
470 apply to bibliographies managed by the multibib package. They
471 take an optional first argument, with the same convention as for
472 the directives of the index module, which may be used to specify
473 the list of bibliographies the command applies to.
474
476 There are surely a some...
477 This page documents Rubber version 1.4. The program and this man-page
479 are maintained by Sebastian Kapfer <sebastian.kapfer@fau.de>. The
480 homepage for Rubber can be found at https://launchpad.net/rubber/.
481
483 The full documentation for rubber is maintained as a Texinfo manual.
484 If the info and rubber programs are properly installed at your site,
485 the command
486 info rubber
488 should give you access to the complete manual.
490 RUBBER(1)