Provided by: refdb-clients_1.0.2-1_amd64 bug

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
       ┌───────────────┬─────────────────────────┬──────────────────────────┐
       │VariableDefaultComment                  │
       ├───────────────┼─────────────────────────┼──────────────────────────┤
       │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>.