1RUBBER(1) General Commands Manual RUBBER(1)
2
6 rubber - a building system for LaTeX documents
7
10 rubber [options] sources ...
11 rubber-pipe [options]
12
15 Rubber is a wrapper for LaTeX and companion programs. Its purpose is,
16 given a LaTeX source to process, to compile it enough times to resolve
17 all references, possibly running satellite programs such as BibTeX,
18 makeindex, Metapost, etc. to produce appropriate data files.
19 The command rubber builds the specified documents completely. The
21 source files may be either LaTeX sources (in which case the suffix .tex
22 may be omitted) or documents in a format Rubber knows how to translate
23 into LaTeX (this currently means CWEB or Literate Haskell documents).
24 If one compilation fails, the whole process stops, including the compi‐
25 lation of the next documents on the command line, and rubber returns a
26 non-zero exit code.
27 The command rubber-pipe does the same for one document but it reads the
29 LaTeX source from standard input and dumps the compiled document on
30 standard output.
31 Some information cannot be extracted from the LaTeX sources. This is
33 the case, for instance, with the search paths (which can be specified
34 in environment variables like TEXINPUTS), or the style to be used with
35 Makeindex. To address this problem, one can add information for Rubber
36 in the comments of the LaTeX sources, see section Directives.
37
40 The options are used either to choose the action to be performed or to
41 configure the building process. They are mostly the same in rubber and
42 rubber-pipe. Options are parsed using GNU Getopt conventions.
43 --cache
45 Use the experimental cache system. This uses a file rubber.cache
46 in the current directory to store the results of parsing and
47 dependency analysis, so that subsequent compilations are faster.
48 --clean
50 Remove all files produced by the compilation, instead of build‐
51 ing the document. This option is present in rubber only. It
52 applies to the compilation as it would be done with the other
53 options of the command line, i.e. saying "rubber --clean foo"
54 will not delete foo.ps, while saying "rubber --ps --clean foo"
55 will.
56 -c, --command <command>
58 Execute the specified command (or directive) before parsing the
59 input files. See section "Directives" for details.
60 -e, --epilogue <command>
62 Execute the specified command (or directive) after parsing the
63 input files. See section "Directives" for details.
64 -f, --force
66 Force at least one compilation of the source. This may be use‐
67 ful, for instance, if some unusual dependency was modified (e.g.
68 a package in a system directory). This option is irrelevant in
69 rubber-pipe.
70 -z, --gzip
72 Compress the final document (in gzip format). This is equivalent
73 to saying -o gz after all other options.
74 -h, --help
76 Display the list of all available options and exit nicely.
77 --inplace
79 Go to the directory of the source files before compiling, so
80 that compilation results are in the same place as their sources.
81 --into <directory>
83 Go to the specified directory before compiling, so that all
84 files are produced there and not in the current directory.
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 10
99 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 mod‐
105 ule 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 to
115 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 form the specified file (see also the
134 directive "read").
135 -s, --short
137 Display LaTeX's error messages in a compact form (one error per
138 line).
139 -I, --texpath <directory>
141 Add the specified directory to TeX's search path.
142 -v, --verbose
144 Increase the verbosity level. Levels between 0 and 4 exist, the
145 default level is 1 for rubber and 0 for rubber-pipe. Beware,
146 saying -vvv makes Rubber speak a lot.
147 --version
149 Print the version number and exit nicely.
150 -W, --warn <type>
152 Report information of the given type if there was no error dur‐
153 ing compilation. The available types are: boxes (overfull and
154 underfull boxes), refs (undefined or multiply defined refer‐
155 ences), misc (other warnings) and all to report all warnings.
156
158 Rubber's action is influenced by modules. Modules take care of the par‐
159 ticular features of packages and external programs.
160 Packages
163 For every package that a document uses, Rubber looks for a module of
164 the same name to perform the tasks that this package my require apart
165 from the compilation by LaTeX. Modules can be added to the ones pro‐
166 vided by default to include new features (this is the point of the mod‐
167 ule system). The standard modules are the following:
168 beamer This module handles Beamer's extra files the same way as other
170 tables of contents.
171 bibtex Takes care of processing the document's bibliography with BibTeX
173 when needed. This module is automatically loaded if the docu‐
174 ment contains the macro \bibliography (see also in "Directives"
175 for options).
176 combine
178 The combine package is used to gather several LaTeX documents
179 into a single one, and this module handles the dependencies in
180 this case.
181 epsfig This modules handles graphics inclusion for the documents that
183 use the old style \psfig macro. It is actually an interface for
184 the graphics module, see this one for details.
185 graphics, graphicx
187 These modules identify the graphics included in the document and
188 consider them as dependencies for compilation. They also use
189 standard rules to build these files with external programs. See
190 the info documentation for details.
191 hyperref
193 Handle the extra files that this package produces in some cases.
194 index, makeidx
196 Process the document's index (or indexes) with makeindex(1) when
197 needed (see section "Directives" for options).
198 minitoc, minitoc-hyper
200 On cleaning, remove additional files that produced to make par‐
201 tial tables of contents.
202 moreverb, verbatim
204 Adds the files included with \verbatiminput and similar macros
205 to the list of dependencies.
206 multibib
208 Handles the extra bibliographies that this package creates, and
209 removes the extra files on cleaning.
210 natbib May cause an extra compilation to solve references.
212 xr Add additional .aux files used for external references to the
214 list of dependencies, so recompiling is automatic when refer‐
215 enced document are changed.
216 Pre-processing
218 The following modules are provided for using programs that generate a
219 LaTeX source from a different file format:
220 cweb This module's purpose is to run cweave(1) if needed before the
222 compiling process to produce the LaTeX source. This module is
223 automatically loaded if the file specified on the command line
224 has .w as its suffix.
225 lhs2TeX
227 This module uses the lhs2TeX preprocessor to generate the LaTeX
228 source from a Literate Haskell program. It is automatically
229 triggered if the input file's name ends with .lhs.
230 Post-processing
232 The following modules are provided to support different kinds of post-
233 processings. Note that the order matters when using these modules: if
234 you want to use a processing chain like
235 foo.tex -> foo.dvi -> foo.ps -> foo.pdf -> foo.pdf.gz
236 you have to load the modules dvips, ps2pdf and gz in that order, for
237 instance using the command line
238 rubber -p -o ps2pdf -z foo.tex
239 dvipdfm
241 Runs dvipdfm(1) at the end of compilation to produce a PDF docu‐
242 ment.
243 dvips Runs dvips(1) at the end of compilation to produce a PostScript
245 document. This module is also loaded by the command line option
246 --ps.
247 expand Produce an expanded LaTeX source by replacing \input macros by
249 included files, bibliography macros by the bibliography produced
250 by bibtex(1), and local classes and packages by their source. If
251 the main file is foo.tex then then expanded file will be named
252 foo-final.tex. See the info documentation for details.
253 gz Produce a version of the final file compressed with gzip(1).
255 ps2pdf Assuming that the compilation produces a PostScript document
257 (for instance using module dvips), convert this document to PDF
258 using ps2pdf(1).
259 Compiler choice
261 The following modules are used to change the LaTeX compiler:
262 aleph Use the Aleph compiler instead of TeX, i.e. compiles the docu‐
264 ment using lamed(1) instead of latex.
265 etex Instructs Rubber to use elatex(1) instead of latex.
267 omega Use the Omega compiler instead of TeX, i.e. compiles the docu‐
269 ment using lambda(1) instead of latex. If the module dvips is
270 used too, it will use odvips(1) to translate the DVI file. Note
271 that this module is triggered automatically when the document
272 uses the package omega.
273 pdftex Instructs Rubber to use pdflatex(1) instead of latex(1) to com‐
275 pile the document. By default, this produces a PDF file instead
276 of a DVI, but when loading the module with the option dvi (for
277 instance by saying -m pdftex:dvi) the document is compiled into
278 DVI using pdflatex. This module is also loaded by the command
279 line option --pdf.
280 vtex Instructs Rubber to use the VTeX compiler. By default this uses
282 vlatex as the compiler to produce PDF output. With the option ps
283 (e.g. when saying "rubber -m vtex:ps foo.tex") the compiler used
284 is vlatexp and the result is a PostScript file.
285
287 The automatic behavior of Rubber is based on searching for macros in
288 the LaTeX sources. When this is not enough, directives can be added in
289 the comments of the sources. A directive is a line like
290 % rubber: cmd args
291 The line must begin with a "%", then any sequence of "%" signs and spa‐
292 ces, then the text "rubber:" followed by spaces and a command name,
293 possibly followed by spaces and arguments.
294 General directives
297 alias <name1> <name2>
298 Pretend that the LaTeX macro name1 is equivalent to name2. This
299 can be useful when defining wrappers around supported macros.
300 clean <file>
302 Indicates that the specified file should be removed when clean‐
303 ing using --clean.
304 depend <file>
306 Consider the specified file as a dependency, so that its modifi‐
307 cation time will be checked.
308 make <file> [<options>]
310 Declare that the specified file has to be generated. Options can
311 specify the way it should be produced, the available options are
312 from <file> to specify the source and with <rule> to specify the
313 conversion rule. For instance, saying "make foo.pdf from
314 foo.eps" indicates that foo.pdf should be produced from foo.eps,
315 with any conversion rule that can do it. See the info documenta‐
316 tion for details on file conversion.
317 module <module> [<options>]
319 Loads the specified module, possibly with options. This is
320 equivalent to the command-line option --module.
321 onchange <file> <command>
323 Execute the specified shell command after compiling if the con‐
324 tents of the specified file have changed. The file name ends at
325 the first space.
326 paper <options>
328 Specify options related to paper size. Currently they are used
329 to give -t options to dvips and -p options to dvipdfm.
330 path <directory>
332 Adds the specified directory to the search path for TeX (and
333 Rubber). The name of the directory is everything that follows
334 the spaces after "path".
335 read <file>
337 Read the specified file of directives. The file must contain one
338 directive per line. Empty lines and lines that begin with "%"
339 are ignored.
340 rules <file>
342 Read extra conversion rules from the specified file. The format
343 of this file is the same as that of rules.ini, see the info doc‐
344 umentation for details.
345 set <name> <value>
347 Set the value of a variable. For details on the existing vari‐
348 ables and their meaning, see the info documentataion.
349 watch <file>
351 Watch the specified file for changes. If the contents of this
352 file has changed after a compilation, then another compilation
353 is triggered. This is useful in the case of tables of contents,
354 for instance.
355 Module-specific directives
357 If a command has the form foo.bar, it is considered a command bar for
358 the module foo. If this module is not registered when the directive is
359 found, then the command is silently ignored. For the standard modules,
360 the directives are the following:
361 bibtex.path <directory>
363 Adds the specified directory to the search path for BibTeX data‐
364 bases (.bib files).
365 bibtex.sorted <boolean>
367 If the argument is true, yes or 1, declare that the bibliography
368 is sorted (this is the default), otherwise declare that the
369 citations appear in the same order as in the text. This may
370 require additional calls to bibtex.
371 bibtex.stylepath <directory>
373 Adds the specified directory to the search path for BibTeX
374 styles (.bst files).
375 dvipdfm.options <options>
377 Pass the specified command-line switches to dvipdfm.
378 dvips.options <options>
380 Pass the specified command-line switches to dvips.
381 index.tool (index) <name>
383 Specifies which tool is to be used to process the index. The
384 currently supported tools are makeindex(1) (the default choice)
385 and xindy(1). The argument index is optional, it may be used to
386 specify the list of indexes the command applies to. When
387 present, it must be enclosed in parentheses; the list is comma-
388 separated. When the argument is not present, the command applies
389 to all indices.
390 index.language (index) <language>
392 Selects the language used for sorting the index. This only
393 applies when using xindy(1) as the indexing tool. The optional
394 argument has the same semantics as above.
395 index.modules (index) <module>...
397 Specify which modules to use when processing an index with
398 xindy(1). The optional argument has the same semantics as
399 above.
400 index.order (index) <options>
402 Modifies the sorting options for the indexes. The arguments are
403 words (separated by spaces) among standard, german and letter.
404 This only applies when using makeindex(1). The optional argu‐
405 ment has the same semantics as above.
406 index.path (index) <directory>
408 Adds the specified directory to the search path for index styles
409 (.ist files). The optional argument has the same semantics as
410 above.
411 index.style (index) <style>
413 Specifies the index style to be used. The optional argument has
414 the same semantics as above.
415 makeidx.language, .modules, .order, .path, .style, .tool
417 These directives are the same as for the index module, except
418 that they don't accept the optional argument.
419
421 There are surely a some...
422 This page documents Rubber version 1.1. The program and this man-page
424 are maintained by Emmanuel Beffara <manu@beffara.org>. The homepage
425 for Rubber can be found at http://www.pps.jussieu.fr/~beffara/soft/rub‐
426 ber/.
427
430 The full documentation for rubber is maintained as a Texinfo manual.
431 If the info and rubber programs are properly installed at your site,
432 the command
433 info rubber
435 should give you access to the complete manual.
437 RUBBER(1)