3.11. Refdb

Alternative way for Bibliography

You are not confined to using RefDB whith my lyxtox script. If you don't feel like building your own bibliographic database, you can skip this section and just supply a bibliography.lyx file together with your LyX document. Set the process_RefDB variable in lyxtox to "0" and it will use your own bibliography.lyx to produce a bibliography.sgml file, instead of trying to create one automatically through RefDB. The bibliography.lyx file should then contain the SGML code for the references list, in the SGML environment of LyX. The GNU/Linux Command-Line Tools Summary HOWTO uses this approach, for example. See the bibliography.lyx and bibliography.sgml files in the Formats section of GNU/Linux Command-Line Tools Summary HOWTO. Be warned however, that writing a bibliography file with all your references in SGML is not fun and does not solve the problem of formatting those references to the style of the journal (or medium) you are submitting your work (for this you would need an extra DSSSL stylesheet). In the long run, these two disadvantages will work against you to the point of being a real pain, especially if you submit the same work to more than one journals with conflicting formatting style guidelines regarding references. Read Who should use refdb? - it will help you decide whether you need RefDB or not.

RefDB problems

Currently, version 0.9.4-pre5 of RefDB worked fine for some time, then, after adding a few citations and a few pages more to this document, refdbxp started to segfault. I tried 0.9.4, just released, but got installation problems and a "could not read from refdbd" message each time I tried anything. However, this does not mean that the following is untested or that RefDB does not work - during the short time I got it to work, it worked fine, as did all the scripts and stylesheets I present here. It also does not mean that refdbxp will segfault on your system - as always, YMMV.

RefDB is a reference database and bibliography tool for SGML, XML, and LaTeX/BibTeX documents. It allows users to share databases over a network. It is lightweight and portable to basically all platforms with a decent C compiler. And it's released under the GNU General Public License (2) .

RefDB is currently known to build and run out of the tarball on at least these platforms:

• Linux

• FreeBSD

• NetBSD

• Solaris (using gcc)

• OSX/Darwin

• Windows+Cygwin

RefDB appears to be the only available tool to create HTML, PostScript, PDF, DVI, MIF, or RTF output from DocBook or TEI sources with fully formatted citations and bibliographies according to publisher's specifications. If you want to include bibliographies in LyX , RefDB is the way to go. The standard way, using BibTeX, will NOT work in our SGML context.

To install RefDB, it is highly recommended to get the newest version currently available. Due to various bugs, versions older than 0.9.4-pre5 will not work. By the time you read this, version 0.9.4 should be out and you should use that one - here I will describe the installation procedure for the 0.9.4-pre5 version:

Download RefDB from the RefDB downloads page, along with the Perlmod package, currently RefDB-perlmod-0.3.tar.gz (you can skip the latter if you don't require the MARC and Pubmed import filters). First, install any Perl modules you need, such as RefDB-perlmod, MARC::Record and MARC::Charset:

For RefDB-perlmod:

tar -xzvf RefDB-perlmod-0.2.tar.gz
cd RefDB-perlmod-0.2/
perl Makefile.PL

You get an output like:

Checking if your kit is complete...
Looks good
Writing Makefile for RefDB::perlmod

After that, install perlmod with

make install

For the other two modules, MARC::Record and MARC::Charset, the installation can be done in the usual manner for CPAN modules:

perl -MCPAN -eshell
install MARC::Record
install MARC::Charset

I could not install MARC::Charset because it needs Perl 5.8.0 - however, this does not interfere with my method here, so you can safely skip it.

After the Perl modules, you must install the libdbi package: Go to the libdbi homepage and download the latest libdbi version libdbi-0.7.2.tar.gz. Then go to the libdbi-drivers homepage and download the latest libdbi-drivers package libdbi-drivers-0.7.1.tar.gz. Then, uninstall any previous libdbi or RefDB package with

make uninstall

from their source directory and you are ready for the installation of libdbi:

cd /usr/src/libdbi-0.7.2
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --infodir=/usr/share/info 
--mandir=/usr/share/man --with-gnu-ld
make
make install

Adapt the configure options to your situation, those above are the ones I use in my old SuSE system. The installation of libdbi-drivers is accomplished similarly:

cd /usr/src/libdbi-drivers-0.7.1
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --infodir=/usr/share/info 
--mandir=/usr/share/man --with-gnu-ld --with-mysql --with-pgsql
make
make install
make check

Note the “--with-mysql” and “--with-pgsql” options in the configure command above: for every libdbi database driver you plan to use, you have to insert the aproppriate “--with-” option. Type “./configure --help” to see all options. However, it makes no sense to say you want libdbi-drivers to be compiled with the pgsql driver, for example, if you don't have PostgreSQL installed and running.

In the "make check", you must give the database administrator's name and password (not that of a user, as in the 0.6.x version). Just accept the other values offered:

database hostname? [(blank for local socket if possible)]
database name? [libdbitest]

The output of “make check” starts with:

Plugin information:
-------------------
        Name:       mysql
        Filename:   /usr/lib/dbd/libmysql.so
        Desc:       MySQL database support (using libmysqlclient)
        Maintainer: Mark M. Tobenkin <mark@brentwoodradio.com>
        URL:        http://libdbi-drivers.sourceforge.net
        Version:    dbd_mysql v0.7.1
        Compiled:   Jan 30 2004
Successfully connected!

and continues with the outcome of various tests (create a database, select a database, list tables etc.). After all tests are completed successfully, you will (hopefully) see

SUCCESS! All done, disconnecting and shutting down libdbi. Have a nice day.
PASS: test_dbi
==================
All 1 tests passed
==================

Finally, you are ready for the installation of RefDB (instructions pertain to version 0.9.4-pre5:

cd /usr/src/refdb-0.9.4-pre5
./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --infodir=/usr/share/info
--mandir=/usr/share/man --with-sgml-declaration=/usr/share/sgml/docbook_4/docbook.dcl
--with-xml-declaration=/usr/share/sgml/openjade/xml.dcl
--with-docbook-xsl=/usr/share/sgml/docbook/docbook-xsl-stylesheets
--with-refdb-url=http://midas/refdb --with-libdbi-lib=/usr/lib
make
make install

You must adapt the options of the configure command to your situation. Read the excellent RefDB documentation for more details.

This completes the RefDB installation - but you are not done yet! You must create the refdb database and grant yourself all privileges on it. In MySQL, on the mysql promt, you type:

CREATE DATABASE refdb;
grant all privileges on refdb1.* to chris@localhost identified by 'password';

On the shell prompt, type:

mysql -u root -p refdb < /usr/share/refdb/sql/refdb.dump

to populate the refdb database. Note that the refdb database is NOT the database you will use for your bibliography entries, but a central repository of information necessary for RefDB's internal functions.

The refdb name has changed between versions!

For version 0.9.4-pre5, the database is called refdb, NOT refdb1! That "central repository" of RefDB used to be called "refdb", then it became "refdb1" and in 0.9.4-pre5 "refdb" again. I didn't know this and I kept on getting errors saying failed to connect to database server without telling me why! After I changed if (dbi_conn_connect(conn) < 0) { /* -1 and -2 indicate errors */ LOG_PRINT(LOG_WARNING, "failed to connect to database server"); dbi_conn_close(conn); return NULL; } in src/refdba.c to const char *errmsg; if (dbi_conn_connect(conn) < 0) { /* -1 and -2 indicate errors */ dbi_conn_error(conn, &errmsg); printf("\nUnable to connect! Error message: %s\n", errmsg); LOG_PRINT(LOG_WARNING, "failed to connect to database server"); dbi_conn_close(conn); return NULL; } I was able to see that the reason was that it was trying to connect to refdba, and NOT to refdba1: Unable to connect! Error message: 1044: Access denied for user: 'chris@localhost' to database 'refdb' failed to connect to database server command processing done, finish dialog now child finished client on fd 5 child exited with code 0 server waiting n_max_fd=4

The next step is to create the global configuration files. There are half a dozen of them, one for each RefDB tool. They are very well commented, so you will not encounter any problems in setting up the options there.

Further, you will have to import some citation styles. There are only two readily available: J.Biol.Chem.xml and Eur.J.Pharmacol.xml, both in the /usr/src/refdb-0.9.4pre5/styles directory. To import them, start the RefDB administration tool refdba and type:

addstyle /usr/src/refdb-0.9.4-pre5/styles/J.Biol.Chem.xml
addstyle /usr/src/refdb-0.9.4-pre5/styles/Eur.J.Pharmacol.xml

in the refdba prompt. Then, you can check which styles you have using the liststyle command in refdba:

refdba: liststyle .*

which will produce:

J.Biol.Chem.
Eur.J.Pharmacol.

You must also create at least one database that will hold your bibliographic entries. For example, to create the ck_refdb database, start refdba and type on the refdba prompt:

createdb ck_refdb
adduser -d ck_refdb chris -N newpassword

If you want to enter the bibliographic entries via a web interface and not from the command line, you have to configure Apache by inserting the following in its configuration file (adapt it to your situation accordingly):

Alias /refdb/ /usr/share/refdb/www/
<Directory "/refdb">
Options Indexes MultiViews
AllowOverride None
Order allow,deny
# Allow from all
Allow from 192.168.0.0/24
</Directory>

then copy some programs in the cgi-bin directory:

cd /usr/bin/
cp refdbc bib2ris nmed2ris /usr/local/httpd/cgi-bin/

and restart Apache.

To test RefDB, start the refdbd daemon with:

refdbd -s -e 0 -l 7

You should see something like:

refdbd -s -e 0 -l 7
dbi_driver_dir went to:
libdbi: Failed to load driver: /usr/lib/dbd/libpgsql.so
dbi is up using default driver dir
Available libdbi database drivers:
mysql
application server started
use /tmp/refdbd_fifo25577 as fifo
server waiting n_max_fd=4

If you don't have a database server correctly configured, although you asked for support of it in the libdbi-drivers configure command on compilation time, you will get an error like the above for PostgreSQL (libpgsql.so). In refdba, type

viewstat

If the server outputs look like the following:

You are served by: refdb 0.9.4-pre5
Client IP: 127.0.0.1
Connected via mysql driver (dbd_mysql v0.7.1)
to: 3.23.44-log
serverip: localhost
timeout: 60
dbs_port: 3306
logfile: /var/log/refdbd.log
logdest: 0
loglevel: 7
remoteadmin: off
pidfile: /var/run/refdbd.pid

then you know that everything is working fine. See the RefDB documentation for more details.