Provided by: refdb-clients_1.0.2-3ubuntu1_amd64 bug

NAME

       db2ris - converts DocBook bibliographic data to the RIS format

SYNOPSIS

       db2ris [-a] [-e log-destination] [-h] [-L log-file] [-o file] [-O file] [-r reftype] file

DESCRIPTION

       db2ris converts DocBook bibliographic data into RIS files. 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. db2ris is a
       wrapper script which invokes OpenJade to do the actual transformation.

OPTIONS

       -a
           Use full first- and othernames if they are present in the DocBook source. By default,
           all first- and othernames will be abbreviated.

       -e log-destination
           log-destination can have the values 0, 1, or 2, or the equivalent strings stderr,
           syslog, or file, respectively. This value specifies where the log information goes to.
           0 (zero) means the messages are sent to stderr. They are immediately available on the
           screen but they may interfere with command output.  1 will send the output to the
           syslog facility. Keep in mind that syslog must be configured to accept log messages
           from user programs, see the syslog(8) man page for further information. Unix-like
           systems usually save these messages in /var/log/user.log.  2 will send the messages to
           a custom log file which can be specified with the -L option.

       -h
           Displays help and usage screen, then exits.

       -L log-file
           Specify the full path to a log file that will receive the log messages. Typically this
           would be /var/log/refdba.

       -o file
           Send output to file instead of to stdout. If file exists, its contents will be
           overwritten.

       -O file
           Send output to file instead of to stdout. If file exists, the output will be appended.

       -r reftype
           Set the default RIS reference type. This type will be used if db2ris cannot infer the
           reference type from the BiblioEntry element.

       file
           The names of one or more DocBook files.

CONFIGURATION

       db2ris evaluates the file db2risrc to initialize itself.

       Table 1. db2risrc
       ┌───────────────┬─────────────────────┬──────────────────────────┐
       │VariableDefaultComment                  │
       ├───────────────┼─────────────────────┼──────────────────────────┤
       │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.                │
       └───────────────┴─────────────────────┴──────────────────────────┘

DATA PROCESSING

       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.

MODIFYING DB2RIS

       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.

       reftype-heuristic
           This function attempts to infer the correct RIS publication type.

       titletype-heuristic
           This function gives a hint whether a Title element is used as a journal/magazine name
           or as an article title or book title.

       process-date
           This function creates a valid string for the RIS PY tag from the PubDate element.

FILES

       PREFIX/etc/refdb/db2risrc
           The global configuration file of db2ris.

       $HOME/.db2risrc
           The user configuration file of db2ris.

SEE ALSO

       RefDB (7), bib2ris (1), en2ris (1), marc2ris (1), med2ris (1).

       RefDB manual (local copy) PREFIX/share/doc/refdb-<version>/refdb-manual/index.html

       RefDB manual (web) <http://refdb.sourceforge.net/manual/index.html>

       RefDB on the web <http://refdb.sourceforge.net/>

AUTHOR

       db2ris was written by Markus Hoenicka <markus@mhoenicka.de>.