ErbTeX: Ruby pre-processing for TeX and LaTeX Documents

Description

erbtex is a ruby gem that provides the erbtex command line program that pre-processes TeX and LaTeX source files with ruby’s erubis and then passes the resulting file along to a real TeX program.

Installation

Install erbtex with:

gem install erbtex

Usage

After the gem is installed, erbtex is placed in your PATH. erbtex recognizes only one command-line option, --invoke=<tex_program>, which specifies what TeX variant will process the TeX file after erubis has pre-proceesed the input file. By default, erbtex uses pdflatex if no –invoke option is given.

Erbtex reads the input file and executes any ruby code between the special delimiters {: and :}. This brace-colon form of delimiters is less disruptive of syntax highlighting than erubis’s default delimiters <% and %> delimiters, which often get confused by syntax-enabled editors with TeX and LaTeX comments.

If the opening delimiter is instead {:=, the delimited ruby expression is converted into a string (with ruby’s .to_s method) and inserted in-place into the TeX manuscript at that point. For example, the text {:= "Hello, world".reverse :} places the string dlrow ,olleH at that point in the TeX file.

Any text not enclosed in these delimiters is passed through untouched to the TeX program.

Without the `=` the ruby code is simply executed. You can use these, for example, to require ruby libraries or to embed loops into the file. Loops started in one delimited ruby fragment can be continued or terminated in a later fragment, and variables defined in one fragment are accessible in later fragments according to Ruby’s usual scoping rules. The result is that you can use the ruby programming language to greatly increase the computational capabilities of a normal TeX or LaTeX.

You can get the version with the –version flag and help with –help.

Examples

Square Roots

For example, the following LaTeX file will produce a table of square roots when run through erbtex. It uses a ruby iterator to supply the rows of the table, a feat that would tedious at best with bare TeX or LaTeX.

\documentclass{article}
\usepackage[mathbf]{euler}
\usepackage{longtable}

\begin{document}
    \begin{longtable}[c]{r|r}
\hline\hline
\multicolumn{1}{c|}{\mathversion{bold}$x$}&
\multicolumn{1}{c}{\mathversion{bold}\rule{0pt}{12pt}$\sqrt{x}$}\\
\hline\hline
\endhead
\hline\hline
\endfoot
% The following line starts a ruby enumerator loop but does not
% produce any output, since the delimiters are {: :}.
{: 0.upto(100).each do |x| :}

% But the following two lines produce output since the opening delimiter is
% '{:='. Both call the sprintf method in ruby via the percent operator, and the
% second line calls ruby's Math module to compute the square root. Notice that
% the '%' inside the delimiters does not have the effect of commenting out
% the following text. It is interpreted as a ruby '%' operator.

  {:= "\\mathversion{bold}$%0.4f$" % x :}&
  {:= "$%0.8f$" % Math.sqrt(x) :}\\

% End of the loop started above.
{: end :}
  \end{longtable}
\end{document}

With the above in file roots.tex, running $ erbtex roots.tex at the command line will generate a `PDF` file with a nicely typeset table of square roots. The generated pdf file can be seen here. As a by-product, the pre-processed file roots.etx is left in the same directory, so you can see what the effect of the erbtex fragments were. This is often very handy when you are trying to debug the document; otherwise, feel free to delete it. Here, for example is a portion of the `roots.etx` file generated by the foregoing:

\begin{document}
  \begin{longtable}[c]{r|r}
  \hline\hline
  \multicolumn{1}{c|}{\mathversion{bold}$x$}&
  \multicolumn{1}{c}{\mathversion{bold}\rule{0pt}{12pt}$\sqrt{x}$}\\
  \hline\hline
  \endhead
  \hline\hline
  \endfoot
  \mathversion{bold}$0.0000$&
  $0.00000000$\\
  \mathversion{bold}$1.0000$&
  $1.00000000$\\
  \mathversion{bold}$2.0000$&
  $1.41421356$\\
  \mathversion{bold}$3.0000$&
  $1.73205081$\\
  \mathversion{bold}$4.0000$&
  $2.00000000$\\
  \mathversion{bold}$5.0000$&
  $2.23606798$\\
  \mathversion{bold}$6.0000$&
  $2.44948974$\\
  \mathversion{bold}$7.0000$&
  $2.64575131$\\
  \mathversion{bold}$8.0000$&
  $2.82842712$\\
  \mathversion{bold}$9.0000$&
  $3.00000000$\\
  \mathversion{bold}$10.0000$&
  $3.16227766$\\
  \mathversion{bold}$11.0000$&
  $3.31662479$\\
  \mathversion{bold}$12.0000$&
  $3.46410162$\\
  \mathversion{bold}$13.0000$&
  $3.60555128$\\
  \mathversion{bold}$14.0000$&

And many more lines like it.

Trigonometry Table

The examples directory installed with the erbtex gem has a few more examples, including a large trigonometry table generated from a relatively small input file.