Now you've had some success lately with your research and would like to publish your results (or rather, you have to publish something in order to get the next grant). Your data are ready, all papers that you've read are in your refdb database, and you have the instructions for authors of your favourite journal. refdb can create formatted citations and bibliographies for several document type definitions:
DocBook SGML (3.1 or later)
DocBook XML (all published versions)
TEI XML (P4 or later)
LaTeX
We'll leave out LaTeX here as refdb merely acts as a substitute for the flat file database of the BibTeX system in this case; see the manual for details. Instead we'll focus on the two DocBook variants and show the processing steps for both the SGML/DSSSL and the XML/XSL combos. This tutorial assumes that you are familiar with the basics of either SGML or XML authoring and transformation. This tutorial also assumes that suitable bibliography styles are available on your refdb installation.
refdb ships with a couple of example documents. They are usually installed in /usr/local/share/refdb/examples/ (ask your administrator if you can't find the files). If you want to follow the instructions using these test documents, please copy these files to a private folder so you can mess around as much as you like.
In order to use an existing DocBook or TEI document with refdb, you need just a few small changes in the document itself. You do not need any changes to either the DTD or the stylesheets for the subsequent transformation. The basic idea is outlined in the following three steps:
Declare an external entity in the local DTD subset that points to a file to be generated by refdb.
Include this external entity at a location where you wish the bibliography to appear
Whenever you cite a publication in your text, mark this citation element for use with refdb.
For the purpose of this tutorial we'll start from scratch and create a new file rather than modifying an existing one. refdb ships with a script that does the first step for you: It creates an empty file with the appropriate document type declaration and declares the external entity. There's no magic involved, though, so if you want to do this manually, feel free to do so. Now we'll first have a look at that script and at the files it creates.
If you want to start a new document for use with refdb from scratch, create a new subdirectory and cd to it:
~$ mkdir publications/refdbtest |
~$ cd publications/refdbtest |
Now run the refdbnd (like in New Document) script. This is a simple interactive shell script that will ask you some questions. Based on your answers it will then create a new skeleton document and a custom-tailored Makefile which makes the subsequent processing steps a breeze.
Let's have a look at an example session. The displayed help messages should be sufficient to guide you through the process:
~$ refdbnd I'll be happy to assist you in setting up a new document along with a Makefile. First we'll collect a few answers, and only if you accept your settings any files will be created. Press Ctrl-C anytime to exit. Each question will present a default value which you can accept by pressing ENTER Please enter the basename of your document. This is the name without any suffix. For example, if your printed output file is supposed to be called refdbtest.pdf, the basename will be 'refdbtest' [refdbtest] Please enter the type of the document. Available types are 'db31', 'db40', and 'db41' for DocBook SGML versions 3.1, 4.0, and 4.1, respectively, 'db41x' for DocBook XML version 4.1.2, and 'teix' for TEI XML P4 [db41] db41x Please enter the element root which determines the type of the publication. Common are 'set', 'book', and 'article' for DocBook documents and 'TEI.2' for TEI documents [book] Please enter the name of the RefDB database where you take your references from [refdbtest] Please enter the bibliography style that your document should use [J.Biol.Chem.] Eur.J.Pharmacol. You've selected the following values: Basename: refdbtest Document type: db41x Publication type: book Database: refdbtest Bibliography style: Eur.J.Pharmacol. Is this ok? [y] Fine, so then ... Makefile created. Document refdbtest.short.xml created. After editing this file you can use the following commands to create formatted output: make pdf to create a Portable Document Format (PDF) file (refdbtest.pdf) make html to create HTML output (book1.html) make rtf to create a Rich Text Format (RTF) file (refdbtest.rtf) make all to create all available output formats |
The defaults and the messages might be slightly different if you select a different document type. As the session log tells you, the script creates these two files: the Makefile and your new document's source file. Why is the source file called refdbtest.short.sgml? The Makefile assumes that you will be using the short notation for citations, as explained in the next section. This warrants an additional processing step to create the file refdbtest.sgml which uses the full notation for citations. This document in turn determines the name of the output files.
The source file contains the document type declaration and the declaration of your bibliography as an external entity in the internal subset. Feel free to add any additional entity declarations that your document requires. The documents look like the following examples. The first one is a DocBook SGML document:
<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!ENTITY bibliography SYSTEM "refdbtest.bib.sgml">
]>
|
The corresponding chunk of a DocBook XML file looks like this:
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY bibliography SYSTEM "refdbtest.bib.xml">
]>
|
Note: Your local tools might not support using URLs as system identifiers (or you loathe the inconvenience to fire up your modem connection each time you validate or transform the document). Then you'll have to use a local copy of the DTD instead and replace the URL with the full path of your local copy.
refdb bibliographies are wrapped in bibliography and div elements for DocBook and TEI, respectively. Include the external entity at a location where such an element is valid, like in the following chunk:
... </chapter> &bibliography; </book> |
refdb offers two ways to enter citations in your documents. The short notation which will be described shortly is simpler but requires a mandatory preprocessing step before the bibliography can be created and before the document can be transformed (you won't notice, though, as all this is handled by the Makefile). Working with multipart documents is also a little trickier. If you have good reasons to use the full notation, please consult the manual.
refdb citations in SGML and XML documents use the native elements for citations, which are citation and seg elements in DocBook and TEI, respectively. However, you need to set an attribute in order to "tag" these elements for use with refdb. This way refdb can easily distinguish between citations which it is supposed to process and citations which are not meant as refdb citations. Citations in both DocBook SGML and DocBook XML documents look like this:
<citation role="REFDB">2;5;9</citation>
<citation role="REFDB">miller1999;jones2001</citation>
|
The first example shows a citation of three publications whose IDs are listed in a semicolon-separated list. The second example shows that you can use the citation keys as well.
The corresponding syntax for TEI XML documents is quite similar, except that we abuse the general-purpose seg element and tag it for use with refdb by setting the type attribute to REFDBCITATION in all caps:
<seg type="REFDBCITATION" part="N" TEIform="seg">2;5;9</seg>
|
All of the above examples will create citations which are separate from the flow of your text. This is shown in the following example output:
The pharmacological effect of YC-1 was discovered in a rat model (Doe, 1993). |
Occasionally you might prefer to include parts of the citation in the flow of the text, like in the following text:
Miller et al. suggested in a recent review (2000) that ... |
You can achieve this effect by preceeding the ID or citation key with either "A:" or "Y:" for an author-only and a year-only citation, respectively:
<para><citation role="REFDB">A:miller2000</citation> suggested in a recent review <citation role="REFDB">Y:miller2000</citation> that ...</para>
|