'\" t
.\"     Title: runbib
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 2005-10-16
.\"    Manual: RefDB Manual
.\"    Source: RefDB Manual
.\"  Language: English
.\"
.TH "RUNBIB" "1" "2005\-10\-16" "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"
runbib \- creates RefDB bibliographies
.SH "SYNOPSIS"
.HP \w'\fBrunbib\fR\ 'u
\fBrunbib\fR [\fB\-a\fR\ \fIfo\-driver\fR] [\fB\-b\fR\ \fIhtml\-driver\fR] [\fB\-c\fR\ \fIxhtml\-driver\fR] [\fB\-d\fR\ \fIdatabase\fR] [\fB\-E\fR\ \fIencoding\fR] [\fB\-G\fR\ \fIcss\-file\fR] [\fB\-h\fR] [\fB\-i\fR\ \fIIP\-address\fR] [\fB\-I\fR\ \fIname\fR] [\fB\-j\fR\ \fIjade\-args\fR] [\fB\-N\fR\ \fInumber\fR] [\fB\-r\fR] [\fB\-s\fR] [\fB\-S\fR\ \fIstyle\fR] [\fB\-t\fR\ \fIoutput\-type\fR] [\fB\-u\fR\ \fIname\fR] [\fB\-w\fR\ \fIpassword\fR] \fIfilename\fR
.SH "DESCRIPTION"
.PP
This shell script is a wrapper for the bibliography client
refdbib(1) to simplify the creation of bibliographies\&. For SGML and XML documents, runbib first runs openjade or xsltproc(1), respectively, to retrieve a list of citations from your source document\&. Then it runs refdbib(1) to generate the bibliography as an external entity based on the extracted citation information\&. It will also create stylesheet driver files with the formatting information for subsequent document transformations\&. For BibTeX documents, runbib uses the information in the \&.aux file to retrieve a bibliography file that you can use as an input file for bibtex(1)\&.
.SH "OPTIONS"
.PP
\fB\-a\fR \fIfo\-driver\fR
.RS 4
The full path of a custom XSL driver file for printed output\&. This file has to import the appropriate RefDB fo driver file\&.
.RE
.PP
\fB\-b\fR \fIhtml\-driver\fR
.RS 4
The full path of a custom XSL driver file for HTML output\&. This file has to import the appropriate RefDB html driver file\&.
.RE
.PP
\fB\-c\fR \fIxhtml\-driver\fR
.RS 4
The full path of a custom XSL driver file for XHTML output\&. This file has to import the appropriate RefDB xhtml driver file\&.
.RE
.PP
\fB\-d\fR \fIdatabase\fR
.RS 4
The name of the default database\&.
.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\-G\fR \fICSS\-file\fR
.RS 4
Set the path or the URL of a CSS file to be used by the (x)html output
.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\-I\fR \fIname\fR
.RS 4
Change the value of an entity declaration to include marked sections\&. Multiple entries are possible\&. These are passed as
\fB\-i\fR
options to Jade/OpenJade\&.
.RE
.PP
\fB\-j\fR \fIjade\-args\fR
.RS 4
Set additional command line options for Jade/OpenJade
.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\-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
.RS 4
Skip the ID extraction step of runbib\&. You have to provide an aptly named XML file containing the requested IDs\&.
.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,
\fIteix\fR
for TEI XML bibliographies,
\fIbibtex\fR
for BibTeX bibliographies, and
\fIrtf\fR
for RTF bibliographies\&.
.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\-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
.SH "CONFIGURATION"
.PP
Instead of using the command\-line switches, runbib can also be configured by means of the runbib configuration file\&. As with all refdb configuration files, you may maintain a global copy in
/usr/local/etc/refdb/
and one copy per user in
\fB$HOME\fR\&. Keep in mind that the runbib configuration file covers only those options which are not passed to refdbib(1) as that tool has its own configuration file\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&refdbjaderc
.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.
T{
jade_includearg
T}:T{
none
T}:T{
Change the value of an entity declaration to include marked sections\&. Multiple entries are possible\&. These are passed as \fB\-i\fR options to Jade/OpenJade\&.
T}
T{
jadeargs
T}:T{
none
T}:T{
Set additional command line options for Jade/OpenJade\&. Use e\&.g\&. "\-E 0" to disable the maximum error limit
T}
T{
outformat
T}:T{
db31
T}:T{
Set the default output format\&. Supported values are db31 (DocBook SGML 3\&.1 and later), db31x (DocBook XML 3\&.1 and later), db50x (DocBook XML 5\&.0 and later), teix (TEI P4), bibtex, and rtf\&.
T}
.TE
.sp 1
.SH "SGML OUTPUT"
.PP
refdbib generates two output files in addition to the ID listing created by Jade/OpenJade\&. runbib creates another output file from these\&. Assuming you have a source file
foo\&.sgml
and use the bibliography style
J\&.Biol\&.Chem\&.
you will get:
.PP
J\&.Biol\&.Chem\&.dsl
.RS 4
This is the DSSSL driver file file that encodes some additional formatting information specific for the chosen bibliography style for use in subsequent document transformations\&. This file will be written to the present working directory\&. The driver file is a dual\-purpose stylesheet for HTML and printable output\&.
.RE
.PP
foo\&.id\&.xml
.RS 4
This is the intermediate XML file that encodes the citations in foo\&.sgml\&.
.RE
.PP
foo\&.bib\&.sgml
.RS 4
This is the file that holds the DocBook
bibliography
element\&. You have to include this file as an external entity into your source document to integrate the bibliography into your text\&.
.RE
.PP
J\&.Biol\&.Chem\&.css
.RS 4
This is a CSS file which contains formatting information used by the html output\&.
.RE
.SH "XML OUTPUT"
.PP
refdbib again generates two output files as for the DocBook SGML output above, and we also count the ID listing created by xsltproc\&. However, runbib does a little post\-processing, so you\*(Aqll get two additional files in the end\&. Assuming you have a source file
foo\&.xml
and use the bibliography style
J\&.Biol\&.Chem\&.
you will get:
.PP
J\&.Biol\&.Chem\&.fo\&.xsl
.RS 4
This is the XSL driver file used for printable output, containing additional formatting information specific for the chosen bibliography style\&. This file will be written to the present working directory\&.
.RE
.PP
J\&.Biol\&.Chem\&.html\&.xsl
.RS 4
This is the XSL driver file used for HTML output, containing additional formatting information specific for the chosen bibliography style\&. This file will be written to the present working directory\&.
.RE
.PP
foo\&.id\&.xml
.RS 4
This is the intermediate XML file that encodes the citations in foo\&.xml\&.
.RE
.PP
foo\&.bib\&.xml
.RS 4
This is the file that holds the DocBook or TEI bibliography\&. You have to include this file as an external entity into your source document to integrate the bibliography into your text\&.
.RE
.PP
J\&.Biol\&.Chem\&.css
.RS 4
This is a CSS file which contains formatting information used by the html or xhtml output\&.
.RE
.SH "BIBTEX OUTPUT"
.PP
refdbib creates one output file with the reference information\&. If your document is named
foo\&.tex,
\fBlatex\fR
will create a file
foo\&.aux
which refdbib uses as an input file\&. The refdbib output file will then be named
foo\&.bib
and can be used by
\fBbibtex\fR
as an input file\&.
.SH "RTF OUTPUT"
.PP
refdbib creates one output file with the reference information\&. If your document is named
foo\&.rtf,
\fBrtfcitations\fR
extracts the citations and writes them into
foo\&.id\&.xml
which refdbib uses as an input file\&. The refdbib output file will then be named
foo\&.bib\&.rtf
and can be used by
\fBrefdbrtf\fR
as an input file\&.
.SH "EXAMPLE"
.PP
You should run this script from the directory where your document files are stored, as all output will be written to the present working directory by default\&.
.PP
The following command will create a DocBook SGML bibliography file together with a DSSSL stylesheet driver file for the DocBook SGML document
mypaper\&.sgml\&. The output files are tweaked to match the citation and bibliography style of the "Journal of Biological Chemistry", which was added to the database with the name "J\&.Biol\&.Chem\&." previously\&. All references which do not contain a hard\-coded database name are assumed to be in the database
bar\&.
.sp
.if n \{\
.RS 4
.\}
.nf
      ~$ 
      \fBrunbib \-d bar \-S "J\&.Biol\&.Chem\&." \-t db31 mypaper\&.sgml\fR
    
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.PP
PREFIX/etc/refdb/refdbibrc
.RS 4
The global configuration file of refdbib(1), which does most of the work of runbib\&.
.RE
.PP
$HOME/\&.refdbibrc
.RS 4
The user configuration file of refdbib\&.
.RE
.SH "SEE ALSO"
.PP
\fBRefDB\fR
(7),
\fBrefdbd\fR
(1),
\fBrefdbib\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
runbib was written by Markus Hoenicka <markus@mhoenicka\&.de>\&.