Chapter 8. Reference management

Table of Contents
Add references
Find and view references
Delete references
Edit references
Use the personal reference list
Global edit references
Create periodical synonyms
Use pdfroot
Interaction with external applications

You can manage your references with the refdbc command line client. A subset of this functionality is also available through the web interface of refdb. The examples in this chapter will use only the 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.

Add references

RIS datasets

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 defaultfile option of the addref. This will add the tags given in the defaultfile 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.

Note: 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.

Example

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
    

risx datasets

If you prefer the XML data format instead, use the addref with the -t 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 nsgmls.

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.

Example

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.

    ~# onsgmls -s /usr/local/share/refdb/declarations/xml.dcl foo.xml
    

    No news is good news in this case: 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 -t risx -d bar foo.xml