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

NAME

       runbib - creates RefDB bibliographies

SYNOPSIS

       runbib [-a fo-driver] [-b html-driver] [-c xhtml-driver] [-d database] [-E encoding]
              [-G css-file] [-h] [-i IP-address] [-I name] [-j jade-args] [-N number] [-r] [-s]
              [-S style] [-t output-type] [-u name] [-w password] filename

DESCRIPTION

       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).

OPTIONS

       -a fo-driver
           The full path of a custom XSL driver file for printed output. This file has to import
           the appropriate RefDB fo driver file.

       -b html-driver
           The full path of a custom XSL driver file for HTML output. This file has to import the
           appropriate RefDB html driver file.

       -c xhtml-driver
           The full path of a custom XSL driver file for XHTML output. This file has to import
           the appropriate RefDB xhtml driver file.

       -d database
           The name of the default database.

       -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.

       -G CSS-file
           Set the path or the URL of a CSS file to be used by the (x)html output

       -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.

       -I name
           Change the value of an entity declaration to include marked sections. Multiple entries
           are possible. These are passed as -i options to Jade/OpenJade.

       -j jade-args
           Set additional command line options for Jade/OpenJade

       -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.

       -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
           Skip the ID extraction step of runbib. You have to provide an aptly named XML file
           containing the requested IDs.

       -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, teix for TEI XML bibliographies, bibtex for BibTeX
           bibliographies, and rtf for RTF bibliographies.

       -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.

       -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.

CONFIGURATION

       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 $HOME. 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.

       Table 1. refdbjaderc
       ┌────────────────┬─────────┬──────────────────────────┐
       │VariableDefaultComment                  │
       ├────────────────┼─────────┼──────────────────────────┤
       │jade_includearg │ none    │ Change the value of an   │
       │                │         │ entity declaration to    │
       │                │         │ include marked sections. │
       │                │         │ Multiple entries are     │
       │                │         │ possible. These are      │
       │                │         │ passed as -i options to  │
       │                │         │ Jade/OpenJade.           │
       ├────────────────┼─────────┼──────────────────────────┤
       │jadeargs        │ none    │ Set additional command   │
       │                │         │ line options for         │
       │                │         │ Jade/OpenJade. Use e.g.  │
       │                │         │ "-E 0" to disable the    │
       │                │         │ maximum error limit      │
       ├────────────────┼─────────┼──────────────────────────┤
       │outformat       │ db31    │ 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.                     │
       └────────────────┴─────────┴──────────────────────────┘

SGML OUTPUT

       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:

       J.Biol.Chem.dsl
           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.

       foo.id.xml
           This is the intermediate XML file that encodes the citations in foo.sgml.

       foo.bib.sgml
           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.

       J.Biol.Chem.css
           This is a CSS file which contains formatting information used by the html output.

XML OUTPUT

       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'll 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:

       J.Biol.Chem.fo.xsl
           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.

       J.Biol.Chem.html.xsl
           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.

       foo.id.xml
           This is the intermediate XML file that encodes the citations in foo.xml.

       foo.bib.xml
           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.

       J.Biol.Chem.css
           This is a CSS file which contains formatting information used by the html or xhtml
           output.

BIBTEX OUTPUT

       refdbib creates one output file with the reference information. If your document is named
       foo.tex, latex 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 bibtex as an input file.

RTF OUTPUT

       refdbib creates one output file with the reference information. If your document is named
       foo.rtf, rtfcitations 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 refdbrtf as an input file.

EXAMPLE

       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.

       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.

                 ~$
                 runbib -d bar -S "J.Biol.Chem." -t db31 mypaper.sgml

FILES

       PREFIX/etc/refdb/refdbibrc
           The global configuration file of refdbib(1), which does most of the work of runbib.

       $HOME/.refdbibrc
           The user configuration file of refdbib.

SEE ALSO

       RefDB (7), refdbd (1), refdbib (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

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