FreeBSD Manual Pages
REFDBIB(1) RefDB Manual REFDBIB(1) NAME refdbib - the bibliography client of RefDB SYNOPSIS refdbib [-d database] [-D stylespec-directory] [-e log-destination] [-E en- coding] [-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] [-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 for- mats, 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 sys- log facility. Keep in mind that syslog must be configured to accept log messages from user programs, see the syslog(8) man page for further in- formation. 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 Win- dows/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 defini- tions). -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 de- bug 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 bibli- ographies 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 com- mand-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 bibliogra- phies, 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, and bibtex for BibTeX 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 con- cern 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 re- turn a DocBook bibliography which needs to be transformed to a TEI bib- liography with the bibdb2tei.xsl stylesheet. The -t tei5x option cre- ates 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 re- quired 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. -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 precom- piled 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 direc- | | | | tory containing | | | | shareable files like | | | | DTDs, HTML templates | | | | etc. | +----------------+----------------------+----------------------+ | logfile | /var/log/refdbib.log | The full path of a | | | | custom log file. | | | | This is used only if | | | | logdest is set ap- | | | | propriately. | +----------------+----------------------+----------------------+ | 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 set- | | | | ting (0) allows only | | | | the most important | | | | messages, a high | | | | setting (7) allows | | | | all messages includ- | | | | ing 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 data- | | | | base. | +----------------+----------------------+----------------------+ | stylespecdir | | A path to a direc- | | | | tory (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 op- | | | | tion is mostly use- | | | | ful for compiling | | | | advanced bibliogra- | | | | phies or for C bone- | | | | heads who insist | | | | that counting starts | | | | at zero. | +----------------+----------------------+----------------------+ | toencoding | (the database encod- | The character encod- | | | ing) | ing for the bibliog- | | | | raphy output. If | | | | this is not speci- | | | | fied, the data will | | | | use the same encod- | | | | ing as the database. | +----------------+----------------------+----------------------+ | ignore_missing | f | If this is set to | | | | "f", missing refer- | | | | ences (i.e. cited | | | | but not in the data- | | | | base) will throw an | | | | error. If set to | | | | "t", you'll get a | | | | warning but missing | | | | references will not | | | | cause refdbib to re- | | | | turn an error. | +----------------+----------------------+----------------------+ | defaultdb | (none) | The default data- | | | | base. 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. "std- | | | | out" sends the data | | | | to stdout. | +----------------+----------------------+----------------------+ | passwd | * | The password which | | | | is used for authen- | | | | tication 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 pass- | | | | word interactively. | +----------------+----------------------+----------------------+ | port | 9734 | The port on which | | | | refdbd listens. | | | | Change this for all | | | | clients and the | | | | server if this value | | | | interferes with an- | | | | other program using | | | | this port. | +----------------+----------------------+----------------------+ | serverip | 127.0.0.1 | The IP address or | | | | hostname of the ma- | | | | chine where refdbd | | | | runs. Use the de- | | | | fault (localhost) | | | | address if the | | | | clients and refdbd | | | | run on the same ma- | | | | chine. | +----------------+----------------------+----------------------+ | timeout | 180 | The timeout in sec- | | | | onds. After this | | | | time has elapsed, a | | | | stalled connection | | | | is taken down. In- | | | | crease this value if | | | | you encounter fre- | | | | quent timeout errors | | | | due to high network | | | | traffic or refdbs | | | | overload. | +----------------+----------------------+----------------------+ | username | login name | The username which | | | | is used for authen- | | | | tication with the | | | | database server. | | | | This may be differ- | | | | ent from the login | | | | name of the user. | +----------------+----------------------+----------------------+ | verbose | f | Set this to t if you | | | | prefer verbose error | | | | messages. | +----------------+----------------------+----------------------+ 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 de- fined in mypaper.id.xml. They will be formatted according to the bibliogra- phy style called "Br.J.Pharmacol." and will be redirected into the bibli- ography file mypaper.bib.sgml. The DSSSL driver file (it will be automati- cally named after the bibliography style, that is Br.J.Pharmacol.dsl) will be stored in the current working directory. For further information how to generate the citation listing in mypaper.id.xml, see DocBook. 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. See LaTeX/BibTeX for further explanations). $~ refdbib -d myrefs -S "name" -t bibtex mypaper.aux > mypaper.bib This command will use the database "myrefs" to retrieve the references de- fined 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 aux- iliary 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 /usr/local/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-man- ual/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>. 2005-10-15 2005-10-15 REFDBIB(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | DIAGNOSTICS | CONFIGURATION | EXAMPLES | FILES | SEE ALSO | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=refdbib&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>