'\" t
.\"     Title: refdbib
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 2005-10-15
.\"    Manual: RefDB Manual
.\"    Source: RefDB Manual
.\"  Language: English
.\"
.TH "REFDBIB" "1" "2005\-10\-15" "RefDB Manual" "RefDB Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
refdbib \- the bibliography client of RefDB
.SH "SYNOPSIS"
.HP \w'\fBrefdbib\fR\ 'u
\fBrefdbib\fR [\fB\-d\fR\ \fIdatabase\fR] [\fB\-D\fR\ \fIstylespec\-directory\fR] [\fB\-e\fR\ \fIlog\-destination\fR] [\fB\-E\fR\ \fIencoding\fR] [\fB\-f\fR\ \fIstdin\fR] [\fB\-h\fR] [\fB\-i\fR\ \fIIP\-address\fR] [\fB\-l\fR\ \fIlog\-level\fR] [\fB\-L\fR\ \fIlog\-file\fR] [\fB\-m\fR] [\fB\-N\fR\ \fInumber\fR] [\fB\-p\fR\ \fIport\fR] [\fB\-q\fR] [\fB\-r\fR] [\fB\-S\fR\ \fIstyle\fR] [\fB\-t\fR\ \fIoutput\-type\fR] [\fB\-T\fR\ \fItime\fR] [\fB\-u\fR\ \fIname\fR] [\fB\-v\fR] [\fB\-V\fR] [\fB\-w\fR\ \fIpassword\fR] [\fB\-x\fR] [\fB\-y\fR\ \fIconfdir\fR] \fIfilename\fR
.SH "DESCRIPTION"
.PP
refdbib is a command\-line client to generate bibliographies with RefDB(7)\&. refdbib reads the contents of
\fIfilename\fR, which contains a list of citations as an XML document according to
\fIcitationlistx\&.dtd\fR, 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\&.
.PP
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\&.
.PP
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\&.
.SH "OPTIONS"
.PP
\fB\-d\fR \fIdatabase\fR
.RS 4
The name of the default database\&. You can change the database anytime during an interactive session\&.
.RE
.PP
\fB\-D\fR \fIstylespec\-directory\fR
.RS 4
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\&.
.RE
.PP
\fB\-e\fR \fIlog\-destination\fR
.RS 4
log\-destination can have the values 0, 1, or 2, or the equivalent strings
\fIstderr\fR,
\fIsyslog\fR, or
\fIfile\fR, 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
\fB\-L\fR
option\&.
.RE
.PP
\fB\-E\fR \fIencoding\fR
.RS 4
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\&.
.RE
.PP
\fB\-f\fR \fIstdin\fR
.RS 4
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\&.
.RE
.PP
\fB\-h\fR
.RS 4
Displays help and usage screen, then exits\&.
.RE
.PP
\fB\-i\fR \fIIP\-address\fR
.RS 4
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\&.
.RE
.PP
\fB\-l\fR \fIlog\-level\fR
.RS 4
Specify the priority up to which events are logged\&. This is either a number between
0
and
7
or one of the strings
\fIemerg\fR,
\fIalert\fR,
\fIcrit\fR,
\fIerr\fR,
\fIwarning\fR,
\fInotice\fR,
\fIinfo\fR,
\fIdebug\fR, respectively (see also Log level definitions)\&.
\fB\-1\fR
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\&.
.RE
.PP
\fB\-L\fR \fIlog\-file\fR
.RS 4
Specify the full path to a log file that will receive the log messages\&. Typically this would be
/var/log/refdba\&.
.RE
.PP
\fB\-m\fR
.RS 4
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\&.
.RE
.PP
\fB\-N\fR \fInumber\fR
.RS 4
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\&.
.RE
.PP
\fB\-p\fR \fIport\fR
.RS 4
Set the port of the box which is running the application server\&.
.RE
.PP
\fB\-q\fR
.RS 4
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\&.
.RE
.PP
\fB\-r\fR
.RS 4
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\&.
.RE
.PP
\fB\-S\fR \fIstyle\fR
.RS 4
Specifies the bibliography style\&. This controls the formatting of the bibliography and the in\-text citations when the document is processed\&.
.RE
.PP
\fB\-t\fR \fIoutput\-type\fR
.RS 4
Select the output type\&. Use
\fIdb31\fR
to generate DocBook SGML bibliographies,
\fIdb31x\fR
for DocBook XML bibliographies (DTD\-based, up to 4\&.3),
\fIdb50x\fR
for Docbook V5 XML bibliographies (schema\-based),
\fIteix\fR
for TEI P4 XML bibliographies,
\fItei5x\fR
for TEI P5 XML bibliographies,
\fIbibtex\fR
for BibTeX bibliographies, and
\fIrtf\fR
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
\fIdb31\fR
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
\fIdb31x\fR\&.
.sp
Note: In the current implementation, the
\fB\-t\fR
\fIteix\fR
option will also return a DocBook bibliography which needs to be transformed to a TEI bibliography with the
\fIbibdb2tei\&.xsl\fR
stylesheet\&. The
\fB\-t\fR
\fItei5x\fR
option creates a directly usable TEI bibliography\&.
.RE
.PP
\fB\-T\fR \fItime\fR
.RS 4
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\&.
.RE
.PP
\fB\-u\fR \fIname\fR
.RS 4
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\&.
.RE
.PP
\fB\-v\fR
.RS 4
Prints version and copyright information, then exits\&.
.RE
.PP
\fB\-V\fR
.RS 4
Switches to verbose mode\&.
.RE
.PP
\fB\-w\fR \fIpassword\fR
.RS 4
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\&.
.RE
.PP
\fB\-x\fR
.RS 4
Send passwords unencrypted\&.
.RE
.PP
\fB\-y\fR \fIconfdir\fR
.RS 4
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\*(Aqt need the
\fB\-y\fR
option unless you use precompiled binaries in unusual locations, e\&.g\&. by relocating a rpm package\&.
.RE
.SH "DIAGNOSTICS"
.PP
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\&.
.SH "CONFIGURATION"
.PP
refdbib evaluates the
refdbibrc
configuration file at startup to initialize itself\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&refdbibrc
.TS
allbox tab(:);
lB lB lB.
T{
Variable
T}:T{
Default
T}:T{
Comment
T}
.T&
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l
l l l.
T{
refdblib
T}:T{
(none)
T}:T{
The path of a directory containing shareable files like DTDs, HTML templates etc\&.
T}
T{
defaultdb
T}:T{
(none)
T}:T{
The default database\&. refdbib will use this database unless you specify the databases in the citation elements of your documents\&.
T}
T{
pager
T}:T{
stdout
T}:T{
The command line of a pager that accepts the output of refdb on stdin to allow scrolling and other nifty things\&. \(lqstdout\(rq sends the data to stdout\&.
T}
T{
passwd
T}:T{
*
T}:T{
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\&.
T}
T{
port
T}:T{
9734
T}:T{
The port on which refdbd listens\&. Change this for all clients and the server if this value interferes with another program using this port\&.
T}
T{
serverip
T}:T{
127\&.0\&.0\&.1
T}:T{
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\&.
T}
T{
timeout
T}:T{
180
T}:T{
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\&.
T}
T{
username
T}:T{
login name
T}:T{
The username which is used for authentication with the database server\&. This may be different from the login name of the user\&.
T}
T{
verbose
T}:T{
f
T}:T{
Set this to t if you prefer verbose error messages\&.
T}
T{
logfile
T}:T{
/var/log/refdbib\&.log
T}:T{
The full path of a custom log file\&. This is used only if logdest is set appropriately\&.
T}
T{
logdest
T}:T{
1
T}:T{
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\&.
T}
T{
loglevel
T}:T{
6
T}:T{
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\&.
T}
T{
outtype
T}:T{
db31
T}:T{
The type of output generated\&. Use \fIdb31\fR for DocBook SGML bibliographies, \fIdb31x\fR for DocBook XML bibliographies, \fIteix\fR for TEI XML bibliographies, and \fIbibtex\fR for BibTeX bibliographies\&.
T}
T{
outformat
T}:T{
(none)
T}:T{
The bibliographic style to be used for the output\&. This is the name of a style as it was previously added to the database\&.
T}
T{
stylespecdir
T}:T{
\&.
T}:T{
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\&.
T}
T{
startnumber
T}:T{
1
T}:T{
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\&.
T}
T{
toencoding
T}:T{
(the database encoding)
T}:T{
The character encoding for the bibliography output\&. If this is not specified, the data will use the same encoding as the database\&.
T}
T{
ignore_missing
T}:T{
f
T}:T{
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\*(Aqll get a warning but missing references will not cause refdbib to return an error\&.
T}
T{
no_encrypt
T}:T{
f
T}:T{
If set to \*(Aqt\*(Aq, passwords are transmitted unencrypted\&. The default is to encrypt passwords\&.
T}
.TE
.sp 1
.SH "EXAMPLES"
.PP
The first example shows how to create a DocBook SGML bibliography file\&.
.sp
.if n \{\
.RS 4
.\}
.nf
      $~ 
      \fBrefdbib \-d myrefs \-S "Br\&.J\&.Pharmacol\&." \-t db31 \-D "\&." mypaper\&.id\&.xml > mypaper\&.bib\&.sgml\fR
    
.fi
.if n \{\
.RE
.\}
.PP
This command will use the database
\(lqmyrefs\(rq
to retrieve the references defined in
mypaper\&.id\&.xml\&. They will be formatted according to the bibliography style called
\(lqBr\&.J\&.Pharmacol\&.\(rq
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\&.
.PP
The second example shows how to create the BibTeX bibliography from your LaTeX document (it is assumed that you ran
\fBlatex\fR
at least once before this command\&.
.sp
.if n \{\
.RS 4
.\}
.nf
      $~ 
      \fBrefdbib \-d myrefs \-S "name" \-t bibtex mypaper\&.aux > mypaper\&.bib\fR
    
.fi
.if n \{\
.RE
.\}
.PP
This command will use the database
\(lqmyrefs\(rq
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
\fBbibtex\fR\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
For the sake of consistency with
\fBbibtex\fR, it is possible to specify the auxiliary file without the
\&.aux
extension (mypaper
in the above example)\&.
.sp .5v
.RE
.PP
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
\fBbibtex\fR
but they waste space):
.sp
.if n \{\
.RS 4
.\}
.nf
      $~ 
      \fBsort mypaper\&.aux | uniq | refdbib \-d myrefs \-S "name" \-t bibtex > mypaper\&.bib\fR
    
.fi
.if n \{\
.RE
.\}
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
The
runbib
script does exactly this kind of preprocessing automatically\&.
.sp .5v
.RE
.SH "FILES"
.PP
PREFIX/etc/refdb/refdbibrc
.RS 4
The global configuration file of refdbib\&.
.RE
.PP
\fI$HOME/\&.refdbibrc\fR
.RS 4
The user configuration file of refdbib\&.
.RE
.SH "SEE ALSO"
.PP
\fBRefDB\fR
(7),
\fBrefdbd\fR
(1),
\fBrunbib\fR
(1),
\fBrefdbnd\fR
(1),
\fBrefdba\fR
(1),
\fBrefdbc\fR
(1)\&.
.PP
\fIRefDB manual (local copy) \fR
PREFIX/share/doc/refdb\-<version>/refdb\-manual/index\&.html
.PP
\fIRefDB manual (web) \fR
<\m[blue]\fBhttp://refdb\&.sourceforge\&.net/manual/index\&.html\fR\m[]>
.PP
\fIRefDB on the web \fR
<\m[blue]\fBhttp://refdb\&.sourceforge\&.net/\fR\m[]>
.SH "AUTHOR"
.PP
refdbib was written by Markus Hoenicka <markus@mhoenicka\&.de>\&.