This input filter attempts to convert bibliographic data in the DocBook format into the RIS format. A similar complaint as with the BibTeX import filter applies here: The design and purpose of the DocBook bibliography information is too different from the RIS format to warrant a simple and straightforward conversion, let alone a bi-directional one. The DocBook bibliography definition allows for a lot of freedom how to encode your information. To accommodate as wide a range of uses and abuses of the bibliographic elements as possible, this import filter is implemented as a DSSSL stylesheet rather than as a C application. This allows you to quickly change or extend the stylesheet to adapt it to your needs. The costs of maintaining several local copies with different modifications is also much lower than with a compiled program.
We use a shell script to run the db2ris.dsl stylesheet in our favourite DSSSL engine and post-process the output. The reason for this post-processing is the fact that Jade and OpenJade lack an official plain-text backend (Jade allows to abuse the SGML backend to create plain-text output but this does no longer work with OpenJade). We have to use the SGML backend and create elements, so each RIS output line is wrapped in SGML-like tags which have to be stripped off afterwards. Besides that, the use of a shell script allows us to keep some settings in configuration files.
Note: The -a and -r option and the corresponding init file variables authorlong and defaultreftype require OpenJade. Jade does not support passing arbitrary variable values on the command line. If you use Jade, please modify the db2ris.dsl stylesheet directly or create appropriate driver files.
db2ris [-a] [-e log-destination] [-h] [-L log-file] [-o file] [-O file] [-r reftype] [file...]
Remember that you don't have to specify all these options each time if you define the values in db2risrc.
Use the -a switch to use full first- and othernames if they are present in the DocBook source. By default, all first- and othernames will be abbreviated.
Note: You should keep in mind that currently not all refdb backends can handle full first- and othernames.
You can send error messages to a custom log file by setting the -e option to "2". By default, error messages appear on stderr.
Set the path to a custom log file with the -L ooption. This file will only be used if the -e option is set accordingly.
Redirect the output to a file with the -o and -O options which will overwrite or append to an existing file, respectively. By default, the output is sent to stdout.
Use the -r option to set the default RIS reference type. This type will be used if db2ris cannot infer the reference type from the BiblioEntry element.
All other command line parameters will be interpreted as input filenames.
The following example shows how db2ris processes DocBook input files.
~# db2ris -o foo.ris *.sgml |
This command will convert all .sgml files in the current directory and write the output to foo.ris.
Table 15-6. db2risrc
| Variable | Default | Comment |
|---|---|---|
| logfile | /var/log/db2ris.log | The full path of a custom log file. This is used only if logdest is set appropriately. |
| logdest | 0 | The destination of the log information. 0 = print to stderr; 2 = use a custom logfile. The latter needs a proper setting of logfile. |
| authorlong | f | Set this to t if full first- and othernames should be used if possible. |
| defaultreftype | GEN | The default RIS reference type will be used if a BiblioEntry element does not specify the type. |
Again we have to make a bunch of assumptions to arrive at a suitable output:
db2ris will handle only "raw" (as opposed to "cooked") bibliographic data. This basically means that you must encode all bibliographic data in BiblioEntry elements, not in BiblioMixed elements.
db2ris discards all publication date information from the PubDate except the first 4 characters of #PCDATA so these should better be a 4-digit year.
By default, the publication type is neither explicitly encoded in a BiblioEntry element nor can it be easily inferred. Therefore db2ris assumes that the BiblioEntry carry a role attribute with the RIS publication type as the value. If the attribute is missing, a default type is used instead. This means that you should add these attributes before the conversion in order to get useful RIS datasets (or fix the TY entries in the RIS file afterwards).
DocBook does not have a special element to encode the name of a journal or magazine that published an article. Instead the same Title element is used as for the article title, a book title, or a series title. To distinguish between a journal or magazine name and "real" titles, the Title element encoding the journal name is assumed to be nested in a BiblioSet whose relation attribute is set to "journal", "pub", "abbrev", or "full" (this more or less arbitrary list can of course be extended or changed, see below). The values "abbrev" and "full" furthermore decide whether the RIS tag "JO" or "JF" will be used.
As previously stated, db2ris is implemented as a DSSSL stylesheet that can be easily and quickly adapted to your needs. It may be prudent to create copies of the script and modify these in order to adapt them for particular "abuses" of the DocBook bibliographic elements in various documents or data sources. This section briefly lists the functions which you would most likely want to change.
This function attempts to infer the correct RIS publication type.
This function gives a hint whether a Title element is used as a journal/magazine name or as an article title or book title.
This function creates a valid string for the RIS PY tag from the PubDate element.