Building documents with rubber

It’s common to compile our documents a couple of times to ensure, amongst other things, correct cross-referencing and indices. Sometimes, we also rely on a Makefile in order to make things easier. Now enters rubber, a powerful tool to help us on our building adventures.

Our first example

According to the man pages, rubber  “is  a wrapper for LaTeX and companion programs. Its purpose is, given a LaTeX source to process, to compile it enough times to  resolve all  references,  possibly  running  satellite programs such as BibTeX, makeindex, Metapost, etc.  to produce appropriate data files.”

All the major Linux distros have rubber in their repositories. A simple yum install rubber does the job for me. Let’s see an example, with mydoc.tex:

We should now run pdflatex, makeindex, pdflatex again. Hm let’s run it again three more times just to be sure (I know I do). Or we could go with rubber --pdf mydoc . Done. Of course, don’t mention Macbeth. :)

There we go! rubber calls pdflatex and makeindex as many times as need. The --pdf flag tells rubber to run the PDF tools instead the DVI ones. Do you think the current folder is messy, full of temporary files? Go with rubber --clean mydoc and voilà, now you’ll have only the resulting PDF file and your tex source file.

If you want to get rid of all generated files, except of course the sources, just add the --clean --pdf flags:

Thankfully, rubber is smart enough to check if the files are updated:

High hopes part II

Yes, there goes another rubber tree plant… again. Time for more advanced stuff with rubber.

I had the opportunity of answering a nice question on TeX.sx about rubber. It makes use of directives, the hidden gems.

A directive is a comment in the form of

% rubber: cmd args

which adds information for rubber. It’s very simple. Let’s say I want to use a custom mystyle.ist style for my index. A quick look into the rubber manual gives me the following entry:

  • index.style <style>: specifies the index style to be used. It’s important to note that each of these directives may be used with an optional first argument of the form (foo,bar,quux) in order to specify that the directive only applies to the indexes named foo, bar and quux. By default, directives are applied to all indices.

Now, I just need to add a line to mydoc.tex:

Well, it didn’t work. Why? I was wondering what happened. Then the manual tells me why:

  • When using the package makeidx instead of index, the directives must of course be prefixed by makeidx. instead of index., and the optional first argument is not accepted.

Since I’m using makeidx, a quick fix

does the trick.

There are several directives for you to play with. Have fun!

Mac users, don’t worry!

Of course, there’s an app for that… I mean, rubber can be used with Mac too! Go to the official rubber repository and download the current compressed file, e.g, rubber-1.1.tar.gz. Extract it to a folder and use ./configure and sudo make install.

Update: XeLaTeX, where are you?

Unfortunatelly, rubber offers no XeLaTeX support out of the box. But there a way to fix this.

Wouter Bolsterlee provided an elegant solution. Go here, download the attached xelatex.py file and copy it to rubber‘s rules/latex directory. In my Fedora system, the full path is /usr/lib/python2.7/site-packages/rubber/rules/latex. Now, just run

rubber --module xelatex mydoc

and XeLaTeX is recognized! I’m pretty sure a similar lualatex.py file might be used for LuaLaTeX.

Final thoughts

rubber has a lot more features than the ones I described in these examples. Take a look on the manual by running man rubber and info rubber for a complete reference. This tool is certainly a great addition to our TeX utility belt. :)

15 thoughts

  2. Hi — I have nothing against rubber, but for the record, there are a number of programs around to do this job. Off the top of my head, three are latexmk, mkjobtexmf, and texi2dvi/texi2pdf. I’m sure that perusing CTAN would turn up more. (For myself, I tend to write the rules I need directly in make instead of involving another tool.)

    Cheers.

  3. Hi Karl, thanks a lot for the feedback! Indeed, we have lots of tools around to do this job. :) I decided to write about rubber mostly because there was a question on TeX.sx and I actually put some effort on answering it. Apart from the man pages, I could not find a nice rubber introduction, so I thought of writing one. 🙂 IMHO rubber has its merit, unfortunately I miss some important features, like a built-in support for both emerging XeTeX and LuaTeX engines. Anyway, for simple documents, it’s quite suitable. For complex structures, I agree 100% with you, I also tend to write the rules in a Makefile.

  4. Cool! I used CMake in the past, but not for LaTeX files. I’ll give it a try, thanks!

  7. Thanks Roberto, fixed the code. :) I’m also a fan of rubber, thanks for sharing your Makefile. :)

  8. Thanks for presenting rubber! I did not know it and have in fact written a less-complete script with similar features.

    Note that --clean seems to ignore some files (hardcoded?). If you observe such behaviour, you can add a directive to your LaTeX file. Just put % rubber: clean file1 file2 ... before documentclass.

    --into does not work well for me. I have a document which includes files from several subfolders via input. rubber complains that it does not find files via relative paths. Does somebody have a fix?

    Any recommendations for runnings rubbe continuously? It seems suited for that kind of usage (--cache). I was thinking of just putting a call to rubber into a (timed) loop.

  9. Thanks for the feedback, Raphael! :)

    The clean directive is a lifesaver. In one of my initial attempts with rubber, two of the auxiliary files weren’t removed at all. I have no idea why some files are ignored, maybe they are indeed hardcoded. Anyway, at least we have a workaround. :P

    I tried to reproduce the error you mentioned, but my code worked. I’ll take a deeper look, your code is probably more sophisticated than mine. :)

    In other news, during my tests, I got surprised. It seems rubber requires a certain parameters order, with the project name appearing last. I tried rubber --pdf mydoc --into testfolder, but the pdf was generated in the current folder; rubber --pdf --into testfolder mydoc works. Anyway. :P

    I really like the timed loop approach. :) I was talking to a friend and he told me about incron (inotify cron). It’s similar to cron, but it handles filesystem events rather than time periods. He suggested to watch mydoc.tex for changes and call rubber. I’m quite reticent to try this approach. :)

  10. Pingback: What are the differences between latexmk and rubber? | Q&A System

  11. Hello there.

    I also had the clean directive not cleaning two file (.bbl and .blg). I noticed that using
    rubber –clean –pdf file
    or
    rubber –clean –pdf file.tex
    instead of
    rubber –clean –pdf file.pdf

    will remove the two files.

  12. Hello there,

    I should mention an alternative: AutoLaTeX.

    http://www.arakhne.org/autolatex/

    It is also available on CTAN.

    It is similar to Rubber.
    Additionally, it run tools (named translators) to generate PDF files from several figure sources files (svg, dia…) In this way you do not need any more to export manually your figures into PDF/PNG files.

    Stéphane.

  13. Hi all,

    I am trying to install rubber in mac OSX with ./configure and sudo make install and I have the next error:

    error: can’t copy ‘doc/rubber.info’: doesn’t exist or not a regular file
    make: *** [install] Error 1

    Someone knows what is the problem?

    Thanks in advanced

    Diego

  14. It’s been 4 years since this post has been written. I’m really keen on knowing how to make LuaTeX to work with rubber. As of today, I’m not able to compile a LuaTeX project with rubber.

  15. The author of the blog post has gone on to create the arara package. In my opinion it is much better than rubber and any of the other alternatives.

Leave a Reply to Roberto Bonvallet