Table of Contents
You can manage your references with the refdbc command line client. We will demonstrate the interactive use of refdbc, but feel free to use the non-interactive batch mode instead if you prefer. We'll also use a conservative, least error-prone approach whenever there are several ways to achieve the same goal. E.g. we'll use intermediate files instead of piping so we can verify what we got at every stage. Once you're sure about what you're doing, you can still speed up things.
Adding references boils down to running addref with proper input files. The input files have to be valid RIS files. They may contain one or more RIS datasets.
You can set some fields to default values with the -g option of the addref. This will add the tags given in the defaultfiledefaultfile to the end of every dataset before they are added to the database. This means that these values override any values given in the datasets. This option may be convenient e.g. to set the reprint status of all datasets that you add in one fell swoop instead of editing them individually.
Please be aware that any numerical values of the ID tag are ignored when you add references with the addref command. RefDB assigns an automatically generated ID to every new reference, so you can't enforce arbitrary IDs. You can however use the ID tag to provide an alphanumeric citation key, such as "Miller1999". The citation key should consist only of letters and numbers within the 7-bit ASCII range and has to be unique in the database. Remember that the citation key has to be all uppercase if you want to create bibliographies for SGML documents. If you do not specify a citation key, RefDB will generate a unique citation key based on the last name of the first author and the publication year.
If you want to overwrite an existing reference with a given numerical ID or a given citation key, use the updateref command instead.
Let's assume we just downloaded a bunch of references from PubMed (the largest database for biomedical publications). We saved them in the "Medline" format, ending up with several small files containing one or more references each. How do we get them into the database?
First we convert all references in the files (we prudently named them pm001.txt, pm002.txt and so on) to the RIS format and write the result into an intermediate file, using the med2ris.pl input filter:
~#med2ris.pl -o foo.ris pm*
We could now open foo.ris in our favourite text editor and make a few changes. We could enter additional keywords, provide personal notes (e.g. why we currently find the article worth the paper it is printed on, something that may not be apparent a few months later), or specify the reprint status and availability.
Then we switch to (or start) the refdbc command line client and type the following command at the prompt to add the references to the database bar (use the full path to foo.ris if necessary):
refdbc:addref -d bar foo.ris
You feel the urge to import MODS data, an XML data format developed by the Library of Congress. RefDB does not support this format natively or via converters at this time, so you'll have to resort to an external tool. Chris Putnam's bibutils package comes to the rescue, as it provides a set of command-line tools to interconvert a number of bibliography data formats. Both RIS and MODS are supported, so we have all it takes. The following command imports the MODS data into your default database in a single step, although you may first want to check the output of the converter before going ahead:
#xml2ris modsdata.xml|refdbc -C addref
If you prefer the XML data format instead, use the addref with the -A risx switch. As the data are imported using a non-validating XML parser you should make sure the documents are valid, either by using some nifty feature of your XML editor or by running the document through a suitable tool like xmllint.
Each entry in a risx document can specify a numerical ID value and an alphanumeric citation key. The ID is ignored by the import routines. If you want to update or replace an entry by ID, you have to use the updateref command instead. The citation key should only use letters and numbers within the 7-bit ASCII range. Remember that the citation key has to be all uppercase if you want to create bibliographies for SGML documents. If you do not specify a citation key, RefDB will automatically assign a citation key based on the first author and the publication year.
You've written a risx dataset from scratch and want to import it into your RefDB database. This is what you need to do:
First you need to make sure that your document is valid against the risx DTD. Unless your XML editor validates your document anyway, you'll have to use an external validator like onsgmls, which is a part of the OpenSP suite of SGML tools, or xmllint, which is shipped with libxml2.
~#onsgmls -s /usr/local/share/refdb/declarations/xml.dcl foo.xml~#xmllint --noout --dtdvalid "http://refdb.sourceforge.net/dtd/risx/risx.dtd" foo.xml
No news is good news in both cases: If your document is valid, the validator will not output anything. If you do get some error messages, go back to your editor and fix the problems.
Now switch to refdbc and run the following command to add the references in foo.xml to the reference database bar:
refdbc:addref -A risx -d bar foo.xml