Provided by: refdb-clients_1.0.2-3ubuntu1_amd64 
NAME
refdbib - the bibliography client of RefDB
SYNOPSIS
refdbib [-d database] [-D stylespec-directory] [-e log-destination] [-E encoding] [-f stdin] [-h]
[-i IP-address] [-l log-level] [-L log-file] [-m] [-N number] [-p port] [-q] [-r] [-S style]
[-t output-type] [-T time] [-u name] [-v] [-V] [-w password] [-x] [-y confdir] filename
DESCRIPTION
refdbib is a command-line client to generate bibliographies with RefDB(7). refdbib reads the contents of
filename, which contains a list of citations as an XML document according to citationlistx.dtd, and sends
a bibliography in the requested format to stdout. If no input file is specified, refdbib tries to read
the data from stdin. Unless suppressed, it also writes a style specification file (either a DSSSL or an
XSLT stylesheet) and a CSS stylesheet for HTML output to your disk.
refdbib is a low-level tool. It is advisable to use one of the wrappers shipped with RefDB. runbib(1) is
a shell script which creates the list of citations, runs refdbib on this list, and transforms the
document. refdbnd(1) is a Makefile-based system that encapsulates the bibliography generation and
document transformation conveniently.
This man page describes only the startup options of refdbib. Please consult the RefDB manual (see below)
for a description of the input and output formats, as well as for post-processing instructions that are
required for some output types.
OPTIONS
-d database
The name of the default database. You can change the database anytime during an interactive session.
-D stylespec-directory
Specify either a full path or . to use the current working directory for the output of the style
specification and CSS files. The latter case is what you usually want if you run refdbib from the
directory where your LaTeX or SMGL/XML document is stored. This is also the default if you do not
specify a directory at all.
-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.
-E encoding
Select an output character encoding. If this option is not used, the bibliography data will use the
character encoding of the database. See iconv_open(3) for a list of available encodings.
-f stdin
This is a crutch to make reading data from stdin possible on platforms that do not allow automatic
detection of data on stdin, like Windows/Cygwin. On other platforms, refdbib automatically reads data
from stdin if data are available.
-h
Displays help and usage screen, then exits.
-i IP-address
Set the IP address of the box which is running the application server refdbd(1). Instead of the IP
address you can also specify the hostname as long as it can be properly resolved by your system.
-l log-level
Specify the priority up to which events are logged. This is either a number between 0 and 7 or one of
the strings emerg, alert, crit, err, warning, notice, info, debug, respectively (see also Log level
definitions). -1 disables logging completely. A low log level like 0 means that only the most
critical messages are logged. A higher log level means that less critical events are logged as well.
7 will include debug messages. The latter can be verbose and abundant, so you want to avoid this log
level unless you need to track down problems.
-L log-file
Specify the full path to a log file that will receive the log messages. Typically this would be
/var/log/refdba.
-m
This switch turns errors caused by missing references (i.e. cited but not available in the database)
into warnings, causing refdbib to return 0 instead of an error code.
-N number
Use this option to specify where the numbering of the references is supposed to start. The default is
1. This option comes in handy if you need to cobble together composite bibliographies or per-chapter
bibliographies that still need to be numbered consecutively.
-p port
Set the port of the box which is running the application server.
-q
Start without reading the configuration files. The client will use the compile-time defaults for all
values that you do not set with command-line switches.
-r
Use this option to request a raw instead of a cooked bibliography. Raw bibliographies are not
formatted in any way and are processed with the standard DocBook or TEI stylesheets instead of with
the RefDB driver files.
-S style
Specifies the bibliography style. This controls the formatting of the bibliography and the in-text
citations when the document is processed.
-t output-type
Select the output type. Use db31 to generate DocBook SGML bibliographies, db31x for DocBook XML
bibliographies (DTD-based, up to 4.3), db50x for Docbook V5 XML bibliographies (schema-based), teix
for TEI P4 XML bibliographies, tei5x for TEI P5 XML bibliographies, bibtex for BibTeX bibliographies,
and rtf for RTF bibliographies. The type of output also determines the type of style specification
file, if any, that will be generated in addition to the bibliography for formatting purposes. This is
only a matter of concern if you want to process a DocBook XML document with the DSSSL stylesheets: In
this case you should use db31 with this option. The SGML bibliography element is also a valid XML
element, but you will get a DSSSL driver file instead of a XSL driver file when you use db31x.
Note: In the current implementation, the -t teix option will also return a DocBook bibliography which
needs to be transformed to a TEI bibliography with the bibdb2tei.xsl stylesheet. The -t tei5x option
creates a directly usable TEI bibliography.
-T time
Set the timeout for client/application server dialogue in seconds. A connection with unsuccessful
read or write attempts will be considered as dead and taken down after this amount of time has
elapsed.
-u name
Set the username for the database access. Note: This username need not be identical to the login name
of the user. This is the username required to access the database server.
-v
Prints version and copyright information, then exits.
-V
Switches to verbose mode.
-w password
Set the password for the database access. Note: This password need not be identical to the login
password of the user. This is the password required to access the database server.
-x
Send passwords unencrypted.
-y confdir
Specify the directory where the global configuration files are Note: By default, all RefDB
applications look for their configuration files in a directory that is specified during the configure
step when building the package. That is, you don't need the -y option unless you use precompiled
binaries in unusual locations, e.g. by relocating a rpm package.
DIAGNOSTICS
The exit code is 0 if all went fine. It will be 1 if the command returned an error, or if there was a
general error condition during startup like a lack of available memory.
CONFIGURATION
refdbib evaluates the refdbibrc configuration file at startup to initialize itself.
Table 1. refdbibrc
┌────────────────┬─────────────────────────┬──────────────────────────────┐
│ Variable │ Default │ Comment │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ refdblib │ (none) │ The path of a directory │
│ │ │ containing shareable files │
│ │ │ like DTDs, HTML templates │
│ │ │ etc. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ defaultdb │ (none) │ The default database. │
│ │ │ refdbib will use this │
│ │ │ database unless you specify │
│ │ │ the databases in the │
│ │ │ citation elements of your │
│ │ │ documents. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ pager │ stdout │ The command line of a pager │
│ │ │ that accepts the output of │
│ │ │ refdb on stdin to allow │
│ │ │ scrolling and other nifty │
│ │ │ things. “stdout” sends the │
│ │ │ data to stdout. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ passwd │ * │ The password which is used │
│ │ │ for authentication with the │
│ │ │ database server. It is │
│ │ │ potentially evil to store │
│ │ │ unencrypted passwords in │
│ │ │ disk files. At least make │
│ │ │ sure that the init file is │
│ │ │ not readable for anyone │
│ │ │ else. The default setting │
│ │ │ causes refdbib to ask for │
│ │ │ your password interactively. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ port │ 9734 │ The port on which refdbd │
│ │ │ listens. Change this for all │
│ │ │ clients and the server if │
│ │ │ this value interferes with │
│ │ │ another program using this │
│ │ │ port. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ serverip │ 127.0.0.1 │ The IP address or hostname │
│ │ │ of the machine where refdbd │
│ │ │ runs. Use the default │
│ │ │ (localhost) address if the │
│ │ │ clients and refdbd run on │
│ │ │ the same machine. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ timeout │ 180 │ The timeout in seconds. │
│ │ │ After this time has elapsed, │
│ │ │ a stalled connection is │
│ │ │ taken down. Increase this │
│ │ │ value if you encounter │
│ │ │ frequent timeout errors due │
│ │ │ to high network traffic or │
│ │ │ refdbs overload. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ username │ login name │ The username which is used │
│ │ │ for authentication with the │
│ │ │ database server. This may be │
│ │ │ different from the login │
│ │ │ name of the user. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ verbose │ f │ Set this to t if you prefer │
│ │ │ verbose error messages. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ logfile │ /var/log/refdbib.log │ The full path of a custom │
│ │ │ log file. This is used only │
│ │ │ if logdest is set │
│ │ │ appropriately. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ logdest │ 1 │ The destination of the log │
│ │ │ information. 0 = print to │
│ │ │ stderr; 1 = use the syslog │
│ │ │ facility; 2 = use a custom │
│ │ │ logfile. The latter needs a │
│ │ │ proper setting of logfile. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ loglevel │ 6 │ The log level up to which │
│ │ │ messages will be sent. A low │
│ │ │ setting (0) allows only the │
│ │ │ most important messages, a │
│ │ │ high setting (7) allows all │
│ │ │ messages including debug │
│ │ │ messages. -1 means nothing │
│ │ │ will be logged. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ outtype │ db31 │ The type of output │
│ │ │ generated. Use db31 for │
│ │ │ DocBook SGML bibliographies, │
│ │ │ db31x for DocBook XML │
│ │ │ bibliographies, teix for TEI │
│ │ │ XML bibliographies, and │
│ │ │ bibtex for BibTeX │
│ │ │ bibliographies. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ outformat │ (none) │ The bibliographic style to │
│ │ │ be used for the output. This │
│ │ │ is the name of a style as it │
│ │ │ was previously added to the │
│ │ │ database. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ stylespecdir │ . │ A path to a directory │
│ │ │ (including the trailing │
│ │ │ directory separator) that │
│ │ │ will receive the stylesheet │
│ │ │ driver files. The default │
│ │ │ setting will direct the │
│ │ │ driver files to the current │
│ │ │ working directory that most │
│ │ │ likely contains the input │
│ │ │ files. It should rarely be │
│ │ │ necessary to use a different │
│ │ │ setting. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ startnumber │ 1 │ The number where the │
│ │ │ reference numbering starts │
│ │ │ at. This option is mostly │
│ │ │ useful for compiling │
│ │ │ advanced bibliographies or │
│ │ │ for C boneheads who insist │
│ │ │ that counting starts at │
│ │ │ zero. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ toencoding │ (the database encoding) │ The character encoding for │
│ │ │ the bibliography output. If │
│ │ │ this is not specified, the │
│ │ │ data will use the same │
│ │ │ encoding as the database. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ ignore_missing │ f │ If this is set to "f", │
│ │ │ missing references (i.e. │
│ │ │ cited but not in the │
│ │ │ database) will throw an │
│ │ │ error. If set to "t", you'll │
│ │ │ get a warning but missing │
│ │ │ references will not cause │
│ │ │ refdbib to return an error. │
├────────────────┼─────────────────────────┼──────────────────────────────┤
│ no_encrypt │ f │ If set to 't', passwords are │
│ │ │ transmitted unencrypted. The │
│ │ │ default is to encrypt │
│ │ │ passwords. │
└────────────────┴─────────────────────────┴──────────────────────────────┘
EXAMPLES
The first example shows how to create a DocBook SGML bibliography file.
$~
refdbib -d myrefs -S "Br.J.Pharmacol." -t db31 -D "." mypaper.id.xml > mypaper.bib.sgml
This command will use the database “myrefs” to retrieve the references defined in mypaper.id.xml. They
will be formatted according to the bibliography style called “Br.J.Pharmacol.” and will be redirected
into the bibliography file mypaper.bib.sgml. The DSSSL driver file (it will be automatically named after
the bibliography style, that is Br.J.Pharmacol.dsl) will be stored in the current working directory.
The second example shows how to create the BibTeX bibliography from your LaTeX document (it is assumed
that you ran latex at least once before this command.
$~
refdbib -d myrefs -S "name" -t bibtex mypaper.aux > mypaper.bib
This command will use the database “myrefs” to retrieve the references defined in mypaper.aux. The
intermediate bibliography database will be stored in mypaper.bib and will serve as an input file for
bibtex.
Note
For the sake of consistency with bibtex, it is possible to specify the auxiliary file without the
.aux extension (mypaper in the above example).
If you are working on a long document that cites the same references over and over again, it may be
prudent to preprocess the .aux file in order to eliminate duplicates (duplicates do not confuse bibtex
but they waste space):
$~
sort mypaper.aux | uniq | refdbib -d myrefs -S "name" -t bibtex > mypaper.bib
Note
The runbib script does exactly this kind of preprocessing automatically.
FILES
PREFIX/etc/refdb/refdbibrc
The global configuration file of refdbib.
$HOME/.refdbibrc
The user configuration file of refdbib.
SEE ALSO
RefDB (7), refdbd (1), runbib (1), refdbnd (1), refdba (1), refdbc (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
refdbib was written by Markus Hoenicka <markus@mhoenicka.de>.
RefDB Manual 2005-10-15 REFDBIB(1)