How to Create Templates

Overview

Templates are simply ERB files that have a few special variables and functions in their environment. If you're not familiar with Ruby, ERB is a library that allows you to embed Ruby code in arbitrary text files. A template is simply a regular text file where:

• Any text within <% %> is evaluated as Ruby code
• Any text within <%= %> is evaluated as Ruby code, and the result is included in the output

Template files are literally passed to ERB unchanged, so anything that is legal in ERB is OK in a template file.

Here is a simple example of a template file. This template will output the year, authors, and title of every paper in the bibliography, embedded within an HTML ordered list. The entries will be sorted by year.

<ol>
  <% bib.sort_by { |e| e.year }.reverse.each do |entry| %>
      <li><%= entry.year %>. <%= entry.author.pretty %>. <%= entry.title %></li>
  <% end %>
</ol>

Notice how the end in the fourth line closes the do two lines above. The variable bib as well as the functions year, author, pretty, and title are all provided by BibOut, and are described in the next section.

Special functions available to BibOut templates

The Ruby code that lives in a template is run within the context of an object of type ErbBinding. This class provides variables and methods that are useful within templates.

Additionally, the BibOut package is mostly just a thin wrapper over another package which is called bibtex-ruby. You'll need to know about several of the packages from bibtex-ruby in order to create your own templates.

The main two members that you need to know from the ErbBinding are:

• bib : this variable contains the bibliography that is currently being processed. It is an object of type BibTeX::Bibliography. This
• embed : this function allows you to call through to other template files within the current template. It also allows you to pass arguments into the sub-template.

Both of these are available within the binding that is used to evaluate your template. What this means is that you can just use the identifier bib within your template code, and it will work.

There are also two classes that you need to know about, both of them inherited from the bibtex-ruby package. These are described in the next two sections.

Bibliography

The bib local variable is a variable of type Bibliography, which is a bibtex-ruby class that contains all of the information in your bibliography. One important thing that it lets you access all of the entries in the bibliography, and search for particular entries of interest.

The Bibliography object also contains a rich query language that allows you to access subset of the bibliography. For example,

bib["@entry[year=1983]"]

returns a list of all entries in the bibliography whose year is 1983. If the year you want lives in a variable called y, then you can just use Ruby string interpolation syntax like this:

bib["@entry[year=#{y}]"]

For more examples, see the bibtex-ruby readme and the documentation for the bibtex-ruby query function.

Entry

Each entry that you retreive from a Bibliography object will be an object of type BibTeX::Entry. This is another class from bibtex-ruby. This class will let you access the information of each field within a BibTeX entry. The methods of the Entry class that you will be most interested in are:

• The common required field types, such as author, year, and title have appropriate accessor methods. For less common fields, use a construct like entry[:booktitle] (assuming that entry names your object of type Entry)
• The author function returns an object of type Names. This object has a method called pretty which returns a string that describes all of the authors of the publication, with commas and the word "and" inserted in the appropriate places.
• type returns a Symbol that describes the type of the entry.
• key returns a Symbol that gives key of the entry

Examples of Templates

Here are some examples to get you started.

• simple-template.tmpl. A slightly expanded version of the template from the previous example.
• sutton-publications.tgz. The template that I use for my publications page. I run this on a bib file that contains only my own papers. This template features (a) the use of the embed function to include one template in other, and (b) all of the publications are grouped by year, with a special heading for each year.