In order to run refdb you'll need a few external apps. The most important thing are the Cygwin tools which provide a Unix-like environment on the otherwise incompatible Windows platform. Additionally you'll have to build or obtain prebuilt versions of a few libraries which are not part of the standard Cygwin distribution (unless you use prebuilt binaries that contain all non-standard libraries).
Cygwin toolkit, DLL version 1.5.0 or later (the current version as of this writing, 1.5.12, has serious problems with PostgreSQL, though). The Cygwin distribution uses individual packages for the various parts. In addition to what is installed automatically (the base distribution), please make sure to select the following packages: libxml2, libxslt, expat, Perl, and a full TeX installation if you wish to create Postscript or PDF files.
A SQL database engine. Currently you can choose between MySQL (version 3.23 or later) and PostgreSQL (version 7.1 or later). The database server does not have to physically run on the box(es) where you plan to install refdb, it is sufficient if it is accessible through the network.
Cygwin offers a prepackaged version of PostgreSQL (7.3.3 as of this writing) which used to be the most convenient way to run a database server on your Cygwin box, but as stated above it may be broke when you try. Please follow the instructions in the readme shipped with the package to install and initialize the database server. It is crucial that you install and run the separately available cygipc package, available only here.
SQLite is not available as a package, but current versions build straight out of the tarball and run with one minor annoyance (absolute paths to database files don't work). MySQL is currently not officially supported on this platform, but you may still get it to work.
If you want to import Pubmed or MARC datasets, please make sure to install the Perl interpreter available for Cygwin and get the refdb-perlmod package. This collection of Perl modules is required to run the Pubmed and MARC import filters shipped with refdb. These Perl modules in turn depend on MARC::Record, MARC::Charset, XML::Parser, available at CPAN.
The mentioned websites offer plenty of support as web documents or with mailing lists, so it should be possible to figure out how to do a basic install for these suites.
The libdbi library and headers, along with the libdbi-drivers package. Please follow the Cygwin-specific instructions that accompany both packages to build and install the software. Prebuilt binaries for both libdbi and libdbi-drivers are available here.
If you need the BibTeX import filter, you'll also want to have the btparse library. This builds out of the tarball on Cygwin.
Note: Depending on the permission settings, you may have to run the installation steps proper (as opposed to the build steps) as an administrator.
Unpack the sources in a convenient directory: tar -xzf refdb-x.y.z.tar.gz (the exact filename depends on the version).
If you do not want to build in the source directory, create an empty build directory.
Change into the new refdb-x.y.z source directory or into your separate build directory.
./configure --help
This command will display a list of things you can customize. If you build in a separate directory, use the relative path to configure in the source directory. Some important options are:
Note: All paths and URLs in the following options should be entered without a trailing slash.
By default, all files will be installed in the /usr/local tree. Use this option to use a different install root, e.g. /usr or /opt.
The data files will be installed in /usr/local/share/refdb unless you use this option. The data will be installed in the directory DIR/refdb. That is, specifying "--datadir=/usr/local/share" is equivalent to the default behaviour. The configuration variable refdblib (which will be automatically generated in the example configuration files) must point to the refdb data directory.
The global configuration files will be installed in /usr/local/etc/refdb unless you specify a different directory here.
Use this option to specify the directory that contains the libdbi library if it is not in the default library path.
Use this option to specify the directory that contains the expat library if it is not in the default library path.
Use this option to specify the directory that contains the btparse library if it is not in the default library path.
Specify the full path to a suitable SGML declaration for your SGML files. If this option is not used, refdb will use its own copy of docbook.dcl stolen from the DocBook DTD distribution. This SGML declaration also works for a variety of other DTDs.
Specify the full path to xml.dcl which is the SGML declaration for XML files. If this option is not used, refdb will use its own copy of xml.dcl which should work just fine.
Specify the full path to the root directory of the DocBook XSL stylesheets.
Note: This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. configure checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.
Specify the full path to the root directory of the TEI XSL stylesheets.
Note: The TEI Consortium ships tei-xsl-5.2.9.zip which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. /usr/local/share/xsl/tei-xsl-5.2.9.
The refdbxml script assumes that all Java classes for the Java parsers and xslt engines are stored in a class repository, i.e. all in the same directory. Specify this directory with this option. If you keep the relevant Java classes in different directories, either create symlinks or customize refdbxml manually.
The HTML files and templates for the web interface require absolute URLs matching your web server setup. Specify the URL of the directory that contains the refdb HTML files. If you follow the Apache setup instructions in this manual, this will be a string like "http://www.mycomp.com/refdb", where "www.mycomp.com" is the hostname of your computer running Apache and "refdb" is the directory alias used for the refdb web pages.
Note: This URL affects the links in the HTML files and templates. A wrong or missing value of this URL will break the navigation as well as the access to stylesheets and javascript files.
Use this option to specify a directory where refdbd can write its PID file (a file containing the process ID). By default, /var/run will be used.
Use this option to specify a directory where refdb programs can write log files to, if logging is directed to a custom file. By default, /var/log will be used.
By default, all configuration files are preconfigured for use with the MySQL database server. Use this option to preconfigure the configuration files for a different database server (currently mysql, pgsql, and sqlite are recognized as values for DBS).
Note: This option does not modify the binaries that you will create. These will work with all supported database engines regardless of what you select here. The only things affected by this option are a few settings in the refdbdrc configuration file. You can change them after the installation anytime.
refdb uses one main database to store citation styles and other stuff. There is exactly one such database per installation with the default name refdb. The only reason to change this name is if you want to run this and an older, incompatible version of refdb in parallel.
Finally, run ./configure with any options that you need. If you build in a separate directory, use the relative path to configure in the source directory. A complete set of options might look like this if you use PostgreSQL:
$~ ./configure --with-refdb-url=http://yourbox.com/refdb --with-db-server=pgsql --with-var-dir=/var/run \ --with-log-dir=/var/log --with-libdbi-dir=/uar/local/lib --with-docbook-xsl=/usr/local/share/sgml/stylesheets/docbook \ --with-tei-xsl=/usr/local/share/xsl/tei |
Run make. This will create the executables and adapt scripts and other files to your local installation.
make install will copy the application server and the clients to /usr/local/bin and the data files to /usr/local/share/refdb unless you chose different directories in the configure step.
To finish the installation, please follow the instructions in the section Finishing the refdb installation below.
Now you have everything in place to use the refdb clients and the application server from the command line. To install the application server as a service, the following additional steps are necessary:
Install the service with the command cygrunsrv -I refdbd -p /usr/local/bin/refdbd -a '-s' (adapt the paths to your local installation if necessary).
Start the service with the command cygrunsrv -S refdbd. To stop the service, use the command cygrunsrv -E refdbd. If you prefer, you can also start and stop the service with NT's own tools: Either use the NT system control panel or use the NT commands net start refdbd and net stop refdbd.
With this setup, the service will be automatically started at system startup. See cygrunsrv --help for additional options.
If you decide to grab the prebuilt binaries, the installation will be a little bit faster. The binaries are accompanied by a copy of libexpat. Please make sure to read the aptly named Readme files as they may have newer or additional information.
Unpack the archive in the root directory (/) with the command tar -xzf refdb-cygwin-bin-x.y.z.tar.gz (the exact archive name depends on the version you use). This will extract the files into the /usr/local hierarchy. The binaries and scripts go to /usr/local/bin, the Document Type Definitions, stylesheets, styles and example configuration files go to /usr/local/share/refdb and its subdirectories.
Unpack the prebuilt binaries for both libdbi and libdbi-drivers, available here, in the very same way.
Add /usr/local/share/refdb/refdb.cat to your SGML_CATALOG_FILES environment variable.
Create the configuration files in /usr/local/etc. Sample configuration files with a .example extension are created in the same directory during the installation. Provide personalized copies for the user's home directories as needed.
To install refdbd as a service, follow the instructions above.