External applications

refdb was designed with the fact in mind that good applications are out there for almost any purpose. Therefore it relies on a few external applications which have to be properly installed. The following list shows the applications which are absolutely required and some applications which will make your life easier.

SQL database server (required for all purposes)

refdb uses libdbi as a database abstraction layer to access SQL database servers. libdbi, and hence refdb, currently support MySQL homepage and PostgreSQL. Both database servers run on a wide variety of Unix- and Unix-like operating systems as well as on Windows. Sources and precompiled binaries are available. MySQL should be at least version 3.23.x, PostgreSQL should be 7.1 or later.

If you prefer not to run an external SQL database server, choose the SQLite based internal database engine as explained in the libraries section above.

Jade/OpenJade and SP/OSP-based tools (required for DocBook SGML bibliographies, import of DocBook bibliography data)

Jade is a freely available and well-proven DSSSL engine which is based on the SP parser. The Jade package contains a few more SP-based tools, e.g. the nsgmls validator and the sgmlnorm normalizer. refdb uses Jade both to extract the IDs of the references which are cited in SGML documents and to transform SGML documents using DSSSL stylesheets. sgmlnorm is required to preprocess multipart documents using the short notation for refdb citations. The Jade/SP package is available on James Clarks homepage. Prebuilt binaries are available for some platforms, and it builds out of the box on quite a number of platforms. Jade has seen some further development by an independent group of programmers. These newer versions were released as OpenJade/OpenSP and are available at the OpenJade homepage. Instructions to build OpenJade on Windows NT/Cygwin and precompiled binaries are available here (official Cygwin packages of OpenJade and related tools are in preparation).

Note: OpenJade has some advantages over Jade for our purposes. If it is possible to obtain or compile OpenJade on your platform, you should go for it. Both Jade and OpenJade can be installed on the same machine without conflicts. The configure script will look for both OpenJade and Jade and will use the former as the default DSSSL engine in the shell script customizations if it is available.

XSL processor (required for DocBook and TEI XML documents)

If you're working with XML documents and want to transform them using the XSL stylesheets, you'll need some sort of XSL processing machinery. Popular choices are Xalan, Saxon, and xsltproc. The latter is checked for in the configure script and will be used as the default processor if available. The Java-based tools among these need the Java Virtual Machine installed, of course. Generating printable output seems to work best through the TeX path (see below) using the PassiveTeX macros.

Stylesheets (required for SGML or XML bibliographies)

refdb ships with DSSSL stylesheet driver files for DocBook SGML documents, XSL stylesheet driver files for DocBook XML documents, and XSL stylesheet driver files for TEI XML documents. All of these rely on the respective stylesheets by Norm Walsh and Sebastian Rahtz. These must be installed on your system if you want to transform DocBook or TEI documents.

TeX (required for LaTeX bibliographies and recommended for printable output from SGML and XML documents)

Donald Knuth's famous typesetting system is available on almost any platform. You need a TeX system to generate LaTeX bibliographies. It is also convenient to generate nice-looking printable output from SGML and XML documents.

Unix-style text editor (required for all purposes)

This is nothing to worry about if you use some flavour of Unix or Linux: anything that lets you edit texts will do. However, if you have to use Windows, you should be aware that many run-of-the-mill Windows text editors are not suitable for use with refdb as they are not able to handle the Unix-style line endings (LF instead of CR/LF) properly. The standard Windows editors Notepad, WordPad, and MS Word will not work unless you use a DOS to Unix conversion filter like dos2unix. These line endings are important in almost all cases, especially when adding and editing references. Some freeware or shareware text-editors for programmers have an option to read and write Unix-style line endings. A few popular Unix text editors are available as Windows ports. Among them are vi clones like vim which is available as a native Windows application and as a Cygwin version, as well as Emacs. GNU Emacs is available as a native Windows application and also as a Cygwin package (even for the Cygwin XFree86 port if you wish). XEmacs can both be built as a native application and as a Cygwin program.

SGML/XML editor (recommended, but not mandatory)

If you plan to create bibliographies, you may need a SGML/XML editor for two reasons. First, the bibliography style specifications have to be written as XML documents (unless someone else has contributed such a file). Second, if you want to create bibliographies for DocBook documents, you want to use a SGML/XML editor anyway. But SGML is plain text after all, so SGML/XML editors make your life easier, but they are not strictly necessary to get something done.

Emacs/XEmacs and the PSGML mode for DTD-based SGML and XML documents or the nxml mode for RELAX NG-based XML documents are an excellent choice.

Web browser (recommended, but not mandatory)

Most likely you will not have a hard time to find some kind of web browser on your system. A web browser may be more pleasant to view the query results than the standard output on stdout or a pager. If you use refdb to manage a collection of PDF or Postscript files, the paths to these files will be displayed in the HTML output and you can open the files with one mouseclick.

If you plan to use the web interface of refdb, you certainly need a web browser to do so. Essentially any web browser available today should do as long as it supports cookies and JavaScript (this includes Netscape, Mozilla, MS Internet Explorer, Lynx, Konqueror, to name a few).

Web server (mandatory to run the web interface)

If you want to run the refdb web interface at your site or on your computer, you need a web server that can handle CGI programs. Apache is the most widely used web server and available for free for almost any platform, including all platforms that refdb currently supports.

Perl (import of MARC datasets, import of Pubmed XML datasets, import of EndNote RIS datasets, post-processing BibTeX import files)

The Perl interpreter is available for almost any platform. refdb currently uses Perl for two purposes: the first are the MARC and Pubmed XML import filters, the other is a non-mandatory post-processing step of bibliography data that you import from BibTeX .bib files. The MARC import filter requires at least Perl version 5.6.0 and the Perl modules MARC::Record and MARC::Charset. The Pubmed XML import filter requires the Perl modules XML::Parser and Text::Iconv. The latter is also required for the Endnote import filter. All things Perl are available at CPAN.

Z39.50 client

In order to retrieve datasets from one of the countless libraries offering their contents through the Z39.50 protocol you'll need a client. The free YAZ toolkit includes a sample client which should be sufficient for general use. The toolkit is available as source, RPM and Debian binaries, and as a Windows binary package.