RefDB RTF support

Rich Text Format (RTF) is a plain-text format which can be handled by most commercial and free word processors. The format was designed by Microsoft to facilitate document exchange between different word processors and across different operating systems. The internals of RTF somehow reflect the amount of interest that its inventor has in supporting competing products in that they are arcane, obfuscate, redundant, and sometimes plain weird (the RTF spec is your friend). Nevertheless, RTF is an obvious target if RefDB should ever support bibliographies for word processor documents.

As you will easily discern from the implementation details below, RefDB does not strive to be a Word plugin or to provide specific support for any other word processor. Instead of expecting from all m bibliography tools out there to develop plugins for n word processors, thus placing a burden of maintaining m*n interfaces on the community, each word processor should implement a standardized interface to query and retrieve bibliographic data from any number of bibliography tools, which in turn have to support the same interface. This reduces the number of maintained interfaces to m+n (which is favourable as soon as either m or n is larger than 1). The obvious candidate for this common interface is SRU. Needless to say, RefDB does support SRU.

Implementation details

RTF is basically a mixture of content and formatting instructions, a feature it shares with most other word processor formats. Although it is possible to cobble together a document from control symbols and text alone, groups come in handy to apply formatting information to a limited stretch of text. This is what comes closest to SGML or XML elements that most RefDB users should be familiar with. RefDB uses this similarity to implement RTF bibliography support with as much code reuse as possible. In fact, SGML/XML and RTF bibliographies share the low-level routines completely, whereas different higher-level routines are employed to write either elements with associated style information in a stylesheet (SGML/XML) or groups containing the same formatting information (RTF).

RTF support is fully integrated into the refdbnd way of keeping it simple. You can now request a RTF skeleton document along with a Makefile from refdbnd. There is actually nothing special about the skeleton document. You could start a RTF document from scratch with your favourite word processor, as long as you save it under exactly the same name. This name is hard-coded into the custom Makefile which you'll learn to appreciate as soon as you process your document. You can of course use any existing document in any word processor format and save it as RTF whenever you wish to add a bibliography.

Once you have entered your citations into this document (see below), running make will call a Perl script which extracts the citations and writes them into an XML document using the citationlistx DTD. This file serves as the input for refdbib which requests a bibliography file from refdbd. As RTF already contains all formatting information, there is no additional stylesheet as with SGML or XML bibliographies. Now another Perl script adds the bibliography to your document and reformats the citations. The result is written into a new RTF file, so your original document is never altered. You can now use this new file and save it in a native word processor format. However, if you make any changes that will alter the citations or the reference list, you'll have to go back to your original RTF document and reprocess it.

The bibliographies are structured in a similar fashion as SGML/XML bibliographies. Each bibliographic entry consists of several preformatted citation texts (for first and subsequent regular citation, first and subsequent author-only citation, and for year-only citation) and the bibliographic entry proper. The former are written as hidden text, so if you open the bibliography file with a word processor you should see only the bibliographic entries. The processing Perl script uses the citation texts as appropriate and adds only the bibliographic entries to the end of the document.

In theory, the Perl scripts and the generated RTF code are independent of the word processor. The author has successfully used bibliographies with OpenOffice 2.x and AbiWord. Needless to say, word processors are likely to interpret the RTF specification differently, so there may be some rough edges when you try a different word processor.


Your first step after generating the skeleton document (which we assume as "foo.rtf") with refdbnd is to write your text and to add your citations. Citations are written as plain-text using square brackets to enclose each citation, and another pair of square brackets around each reference within a citation. References are given as the citation key of the work in your RefDB database, followed by one of the modifiers "-X", "-A", and "-Y" which indicate regular, author-only, and year-only citations, respectively. The following line contains (in order of appearance) a regular citation, an author-only citation, a year-only citation, and a multi-head citation:

This was first shown by [[Miller1999-X]]. Using these results, [[Doe2000-A]][[Doe2000-Y]] employed a different approach
to expand the idea. Finally, these results were universally accepted [[Jones2002-X][Jamie2003-X][Foo2005-X]].

When the contents of your document are done, just run make. This will create a new document "foo.refdb.rtf" which you can open in your favourite word processor. This document contains the bibliography at the very end, but you can move it anywhere else if you desire. The plain-text citations are replaced by the formatted citations, which are links to the corresponding entries in the bibliography. Most word processors allow you to follow such a link (try the middle or right mouse button, or a context menu). The PDF export of OpenOffice preserves these links as well. If you see any need, you can now save the document in a native word processor format.

Where to get RTF support

The current Subversion revisions as well as the latest prerelease contain RTF support. It will be part of the next stable release as well.


Peruse the following files to see how it works: