RUBBER(1)

📦
version 1.6.7 · 3 versions
, in arch rolling, debian trixie, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 RUBBER(1) — General Commands Manual 🌸

okay bestie, pull up a chair, we're learning rubber today and honestly? it's iconic 💅 (also hi, this is part 1 of 3, so don't go anywhere)

✨ NAME ✨

rubber — a building system for LaTeX documents 🎀

🌈 SYNOPSIS 🌈

rubber [options] sources ...
rubber-pipe [options]

💖 DESCRIPTION 💖

So. Rubber is a wrapper for LaTeX and its little companion programs. The whole point of it, like, the entire vibe, is: you hand it a LaTeX source to process, and it compiles that thing enough times to resolve all the references — and along the way it might run satellite programs like BibTeX, makeindex, Metapost, etc. to produce the appropriate data files. yes bestie, it's doing all that so you don't have to 😭🫶

The command rubber builds the documents you specify completely. Those source files can be either LaTeX sources (in which case, cute news, you can totally omit the .tex suffix) or documents in a format Rubber knows how to translate into LaTeX. Now listen: 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. no mercy, periodt 💀

The command rubber-pipe does the same thing but for one document: it reads the LaTeX source from standard input and dumps the compiled document on standard output. stream queen behavior ✨

Now, some information simply cannot be extracted from the LaTeX sources. That's 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, you can add information for Rubber right in the comments of the LaTeX sources — see section DIRECTIVES. iykyk 🧚

🎀 OPTIONS 🎀

The options are used either to choose the action to be performed or to configure the building process. They're mostly the same in rubber and rubber-pipe. And options are parsed using GNU Getopt conventions, so you know it's the standard deal.

  • -b, --bzip2 — Compress the final document (in bzip2 format). This is equivalent to saying -o bzip2 after all other options. squeeze it, bestie 🍓
  • --clean — Remove all files produced by the compilation, instead of building the document. Heads up: this option is present in rubber only. And 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. it's giving "read the fine print" 💀
  • -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). Just so you know: 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. zip zip 🦋
  • -h, --help — Display the list of all available options and exit nicely. a polite queen 👑
  • --inplace — Go to the directory of the source files before compiling, so that compilation results are in the same place as their sources. stay home, stay cozy 🏠
  • --into <directory> — Go to the specified directory before compiling, so that all files are produced there and not in the current directory. relocation era ✈️
  • --jobname <name> — Specify a job name different from the base file name. This changes the name of output files and only applies to the first target. glow-up via rebranding ✨
  • -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. keeping receipts, love that for you 🧾
  • -n, --maxerr <num> — Set the maximum number of displayed errors. By default, up to 10 errors are reported, and saying -n -1 displays all errors. we're not gatekeeping the 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, and 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. selective and unbothered 💅
  • -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. two moods, one flag 😌
  • -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, and it cannot come after --pdf. no backsies 🚫
  • -q, --quiet — Decrease the verbosity level. This is the reverse of -v. shhh 🤫
  • -r, --read <file> — Read additional directives from the specified file (see also the directive "read"). homework era 📖
  • -S, --src-specials — Enable generation of source specials if the compiler supports it. This is equivalent to setting the variable src-specials to yes.
  • -s, --short — Display LaTeX's error messages in a compact form (one error per line). tl;dr but make it errors 🎯
  • -I, --texpath <directory> — Add the specified directory to TeX's search path. adding to the group chat 📥
  • --synctex — Enable SyncTeX support in the LaTeX run. sync so hard 🔥
  • --unsafe — Permit the document to invoke arbitrary external programs. > This is potentially dangerous, only use this option for documents coming from a trusted source. bestie I'm begging you, trust check first 🙏
  • -v, --verbose — Increase the verbosity level. Levels between 0 and 4 exist, and the default level is 1 for rubber and 0 for rubber-pipe. Beware: saying -vvv makes Rubber speak a lot. it will not stop talking and honestly, same 💀
  • --version — Print the version number and exit nicely. slay, identity confirmed 🎀
  • -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. pick your poison, gorgeous ⭐

🌸 part 1 done, part 2 incoming, don't touch that dial 🌸

✨ MODULES ✨

okay so bestie, here's the tea: Rubber's whole personality is shaped by its modules. Each module is in charge of one specific little niche — some package's extra needs, or some external program that has to get involved. 🧩

🎀 Packages 🎀

So the way this works: for every single package your document pulls in, Rubber goes looking for a module with that exact same name, and that module handles whatever extra tasks the package needs beyond LaTeX just doing its normal compile thing. And yes, you can absolutely stack more modules on top of the default ones to get new features — that's literally the entire point of the module system. 💅

The standard modules are these ones, right here:

  • asymptote — processes the .asy files that the LaTeX package generates, and then it triggers a recompilation. obsessed.
  • beamer — this module handles Beamer's extra files exactly the same way it handles other tables of contents.
  • bibtex, biblatex — takes care of processing your document's bibliography with BibTeX whenever it's needed. This one loads itself automatically if your document has the \bibliography macro in it (and hey, check DIRECTIVES for the options, iykyk).
  • combine — the combine package is all about gathering several LaTeX documents into one single document, and this module handles the dependencies in that whole situation.
  • epsfig — this module handles graphics inclusion for documents using the old style \psfig macro. Ngl it's actually just an interface for the graphics module — go look at that one for the details.
  • glossaries — runs makeglossaries and recompiles whenever the .glo file changes.
  • graphics, graphicx — these modules clock which graphics are included in your document and treat them as dependencies for compilation. They also use standard rules to build those files with external programs. See the info documentation for the full rundown.
  • hyperref — handles the extra files this package produces in some cases.
  • index, makeidx, nomencl — processes your document's indexes and nomenclatures with makeindex(1) when needed (again, DIRECTIVES has the options).
  • ltxtable — adds dependencies for files inserted via the ltxtable LaTeX package.
  • minitoc, minitoc-hyper — on cleaning, these remove the additional files that were 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 this package creates, and removes those extra files when cleaning.
  • xr — adds the additional .aux files used for external references to the list of dependencies, so recompiling happens automatically when the referenced document gets changed. iconic behaviour tbh.

🌸 Pre-processing 🌸

These next modules are for when you're using programs that generate a LaTeX source out of a totally different file format:

  • cweb — this module's whole purpose is to run cweave(1) if needed before the compiling process, so it can produce the LaTeX source. It loads itself automatically if the file you named 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 gets triggered automatically if your input file's name ends with .lhs.

🦋 Post-processing 🦋

These modules are here to support different kinds of post-processing. And heads up bestie, the order matters when you use them: if you want a processing chain like

foo.tex -> foo.dvi -> foo.ps -> foo.pdf -> foo.pdf.gz

then you have to load the modules dvips, ps2pdf and gz in that order — for instance with the command line

rubber -p -o ps2pdf -z foo.tex
  • bzip2 — produce a version of the final file compressed with bzip2(1).
  • 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 also gets loaded by the command line option --ps.
  • expand — produce an expanded LaTeX source by replacing \input macros with the included files, bibliography macros with the bibliography that bibtex(1) produced, and local classes and packages with their source. If the main file is foo.tex then the 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 the compilation produces a PostScript document (for instance by using the dvips module), convert that document to PDF using ps2pdf(1).

👑 Compiler choice 👑

These modules exist purely to swap out your LaTeX compiler:

  • aleph — use the Aleph compiler instead of TeX, i.e. it compiles the document using lamed(1) instead of latex.
  • omega — use the Omega compiler instead of TeX, i.e. it compiles the document using lambda(1) instead of latex. And if the dvips module is being used too, it'll use odvips(1) to translate the DVI file. Little note: this module gets triggered automatically when your document uses the omega package.
  • 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 you load the module with the option dvi (like if you say -m pdftex:dvi) the document gets 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 you say "rubber -m vtex:ps foo.tex") the compiler used is vlatexp and the result is a PostScript file.
  • xelatex — instructs Rubber to use xelatex(1) instead of latex.

💖 DIRECTIVES 💖

So like, Rubber is normally mad smart — it just sniffs around your LaTeX sources looking for macros and figures stuff out on its own. But bestie, sometimes that's just not enough?? And when it's not enough, you drop a directive in the comments of your source. A directive is a line that looks like this:

% rubber: cmd args

The rules, exactly: the line has to begin with a %, then any sequence of % signs and spaces, then the text rubber:, followed by spaces and a command name, and possibly more spaces and arguments after that. That's it, that's the whole vibe. ✨

🌸 General directives 🌸

  • alias <name1> <name2> — Pretend the LaTeX macro name1 is equivalent to name2. Super handy when you're defining wrappers around macros that Rubber already supports. 🫶
  • clean <file> — Says that this file should get yeeted when you clean with --clean. Bye bestie 💅
  • depend <file> — Treat the file as a dependency, so Rubber will check its modification time. Obsessed with staying up to date.
  • make <file> [<options>] — Declares that the file has to be generated. The options can specify the way it should be produced: from <file> to specify the source, and with <rule> to specify the conversion rule. For instance, saying make foo.pdf from foo.eps means foo.pdf should be produced from foo.eps, using any conversion rule that can pull it off. (The info documentation has the deets on file conversion. 📚)
  • module <module> [<options>] — Loads the specified module, possibly with options. It's literally the same as the command-line option --module.
  • onchange <file> <command> — Runs the specified shell command after compiling if the contents of the file have changed. Heads up: the file name ends at the first space. 🔥
  • path <directory> — Adds the directory to the search path for TeX (and for Rubber). The name of the directory is everything that follows the spaces after path, so go wild.
  • produce <file> — Declares that the LaTeX run is gonna create or update the file(s). Iconic.
  • read <file> — Reads a file of directives. It must contain one directive per line. Empty lines and lines that begin with % are ignored. 🎀
  • rules <file> — Reads extra conversion rules from the file. The format is the same as rules.ini — see the info documentation for details.
  • set <name> <value> — Sets the value of a variable as a string. For all the existing variables and what they mean, check the info documentation.
  • setlist <name> <values> — Sets the value of a variable as a (space-separated) list of strings. Same deal, info documentation has the lore.
  • shell_escape — Marks the document as requiring external programs (shell-escape or write18). > Ngl this one's important: Rubber does not actually enable this unless it's called with the option --unsafe. Safety first, bestie. 🛡️
  • synctex — Enables SyncTeX support in the LaTeX run.
  • watch <file> — Watches the file for changes. If its contents changed after a compilation, another compilation gets triggered. Perfect for tables of contents and that kind of "wait, run it again" situation. 👑

🦋 Module-specific directives 🦋

If a command has the form foo.bar, it's considered a command bar for the module foo. And if that module isn't registered when the directive is found, the command is silently ignored — no drama, no error, it just moves on. 🙈

For the standard modules, the directives are these:

  • biblatex.path <directory> — Adds the directory to the search path for BibTeX databases (.bib files).
  • bibtex.crossrefs <number> — Sets the minimum number of crossref required for automatic inclusion of the referenced entry in the citation list. This sets the option -min-crossrefs when calling bibtex(1).
  • bibtex.path <directory> — Adds the directory to the search path for BibTeX databases (.bib files).
  • bibtex.stylepath <directory> — Adds the directory to the search path for BibTeX styles (.bst files).
  • bibtex.tool <command> — Use a different bibliography tool instead of BibTeX.
  • dvipdfm.options <options> — Passes the specified command-line switches to dvipdfm.
  • dvips.options <options> — Passes the specified command-line switches to dvips.
  • index.tool (index) <name> — Specifies which tool processes the index. Currently supported: makeindex(1) (the default choice) and xindy(1). The argument index is optional — you can use it to specify the list of indexes the command applies to. When it's present it must be enclosed in parentheses, and the list is comma-separated. When it's 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>... — Specifies 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 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 are the same as for the index module, except they don't accept the optional argument. 💀
  • multibib.crossrefs, .path, .stylepath, .tool — Same as for the bibtex module, but they apply to bibliographies managed by the multibib package. They take an optional first argument, with the same convention as the directives of the index module, which can specify the list of bibliographies the command applies to.

💀 BUGS 💀

There are surely a some...

(Yeah, that's the whole thing. We love an honest queen.)

This page documents Rubber version 1.6.7. The program and this man-page are maintained by Florian Schmaus <flo@geekplace.eu>. The homepage for Rubber can be found at https://gitlab.com/latex-rubber/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. Go read it, it's giving encyclopedia but make it cute. 📖

And that's the whole page, bestie 🫶 — that was the RUBBER(1) manual, version 1.6.7, brought to you by Florian Schmaus <flo@geekplace.eu> over at https://gitlab.com/latex-rubber/rubber. Now go compile something iconic. 💅🌸

📦 where this page comes from