/usr/share/doc/refdb/refdb-manual/re12.html is in refdb-doc 1.0.2-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>bib2ris</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="RefDB handbook" /><link rel="up" href="ch14.html#idp69978912" title="Tools" /><link rel="prev" href="re11.html" title="refdbc" /><link rel="next" href="re13.html" title="db2ris" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">bib2ris</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="re11.html">Prev</a> </td><th width="60%" align="center">Tools</th><td width="20%" align="right"> <a accesskey="n" href="re13.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="refentry-bib2ris"></a><div class="titlepage"></div><div class="refnamediv"><a id="bib2ris-name2"></a><h2>Name</h2><p>bib2ris, bib2ris-utf8 — converts bibtex bibliographic data to the RIS format</p></div><div class="refsynopsisdiv"><a id="bib2ris-synopsis"></a><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">bib2ris</code> [-e <em class="replaceable"><code>log-destination</code></em>] [-h ] [-j ] [-l <em class="replaceable"><code>log-level</code></em>] [-L <em class="replaceable"><code>log-file</code></em>] [-q ] [-s <em class="replaceable"><code>separator</code></em>] [-v ] [-y <em class="replaceable"><code>confdir</code></em>] <em class="replaceable"><code>file</code></em> </p></div><div class="cmdsynopsis"><p><code class="command">bib2ris-utf8</code> [-e <em class="replaceable"><code>log-destination</code></em>] [-h ] [-j ] [-l <em class="replaceable"><code>log-level</code></em>] [-L <em class="replaceable"><code>log-file</code></em>] [-q ] [-s <em class="replaceable"><code>separator</code></em>] [-v ] [-y <em class="replaceable"><code>confdir</code></em>] <em class="replaceable"><code>file</code></em> </p></div></div><div class="refsect1"><a id="bib2ris-description"></a><h2>Description</h2><p>bib2ris converts BibTeX bibliography files into RIS files. Latex commands, including non-ASCII characters written as commands, are preserved in the output. Importing the output of the bib2ris utility directly into RefDB is useful only if you use the data exclusively for LaTeX.</p><p>bib2ris-utf8 is a variant which converts foreign characters to UTF-8 and strips all other LaTeX commands by means of the <a class="link" href="re19.html" title="refdb_latex2utf8txt">refdb_latex2utf8txt</a> (1) tool. The output of bib2ris-utf8 is the preferred format for import into RefDB as it is suitable for both LaTeX and SGML/XML bibliographies.</p><p>Unfortunately the concepts underlying BibTeX and RIS bibliographic data are quite different so that BibTeX data do not readily lend themselves to a clean conversion to the RIS format. This is not meant as an excuse to provide a bad filter but you should be aware that a few compile-time assumptions have to be made in order to get reasonable results. In any case, as the data models differ considerably, a loss-free round-trip conversion between the two data types is not possible: If you convert a BibTeX bibliography file to RIS and then back, the result will differ considerably from your input.</p><p>The following considerations apply to the data import into RefDB and the data export from RefDB:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>BibTeX input data that are not written in UTF-8, that use formatting commands like font name, weight, or posture specifications, or that use LaTeX commands to write foreign and special characters should always be converted with bib2ris-utf8.</p></li><li class="listitem"><p>BibTeX output data will have the LaTeX command characters properly escaped. The data will use the default encoding of your reference database unless you specifically request a different encoding with the <a class="link" href="re11.html#app-c-command-getref" title="getref">getref</a> command or with the <a class="link" href="re20.html" title="refdbib">refdbib</a> tool. Keep in mind that recent LaTeX installations can work with UTF-8 data using the following incantation in the prolog, allowing the easiest support for all kinds of foreign characters:</p><pre class="programlisting">
\usepackage[utf8]{inputenc}
</pre></li></ol></div></div><div class="refsect1"><a id="bib2ris-options"></a><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-e</code> <em class="replaceable"><code>log-destination</code></em></span></dt><dd><p>log-destination can have the values 0, 1, or 2, or the equivalent strings <span class="emphasis"><em>stderr</em></span>, <span class="emphasis"><em>syslog</em></span>, or <span class="emphasis"><em>file</em></span>, respectively. This value specifies where the log information goes to. <code class="literal">0</code> (zero) means the messages are sent to stderr. They are immediately available on the screen but they may interfere with command output. <code class="literal">1</code> 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 <code class="filename">/var/log/user.log</code>. <code class="literal">2</code> will send the messages to a custom log file which can be specified with the <code class="option">-L</code> option.</p></dd><dt><span class="term"><code class="option">-h</code></span></dt><dd><p>Displays help and usage screen, then exits.</p></dd><dt><span class="term"><code class="option">-j</code></span></dt><dd><p>Force bib2ris to use <span class="emphasis"><em>JO</em></span> RIS fields in all cases. If this option is not used, bib2ris tries to infer whether a journal name is an abbreviation or not. If the string contains at least one period, <span class="emphasis"><em>JO</em></span> will be used, otherwise <span class="emphasis"><em>JF</em></span> will be used.</p></dd><dt><span class="term"><code class="option">-l</code> <em class="replaceable"><code>log-level</code></em></span></dt><dd><p>Specify the priority up to which events are logged. This is either a number between <code class="literal">0</code> and <code class="literal">7</code> or one of the strings <span class="emphasis"><em>emerg</em></span>, <span class="emphasis"><em>alert</em></span>, <span class="emphasis"><em>crit</em></span>, <span class="emphasis"><em>err</em></span>, <span class="emphasis"><em>warning</em></span>, <span class="emphasis"><em>notice</em></span>, <span class="emphasis"><em>info</em></span>, <span class="emphasis"><em>debug</em></span>, respectively (see also Log level definitions). <code class="option">-1</code> disables logging completely. A low log level like <code class="literal">0</code> means that only the most critical messages are logged. A higher log level means that less critical events are logged as well. <code class="literal">7</code> 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.</p></dd><dt><span class="term"><code class="option">-L</code> <em class="replaceable"><code>log-file</code></em></span></dt><dd><p>Specify the full path to a log file that will receive the log messages. Typically this would be <code class="filename">/var/log/refdba</code>.</p></dd><dt><span class="term"><code class="option">-q</code></span></dt><dd><p>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.</p></dd><dt><span class="term"><code class="option">-s</code> <em class="replaceable"><code>separator</code></em></span></dt><dd><p>Specify the delimiter which separates individual keywords in a non-standard keyword field. Use the string <span class="emphasis"><em>spc</em></span> for whitespace-separated lists (spaces and tabs).</p></dd><dt><span class="term"><code class="option">-v</code></span></dt><dd><p>Prints version and copyright information, then exits.</p></dd><dt><span class="term"><code class="option">-y</code> <em class="replaceable"><code>confdir</code></em></span></dt><dd><p>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 <code class="option">-y</code> option unless you use precompiled binaries in unusual locations, e.g. by relocating a rpm package.</p></dd><dt><span class="term"><span class="emphasis"><em>file</em></span></span></dt><dd><p>If used, this parameter denotes the names of one or more bibtex files. If no file is specified, bib2ris tries to read the data from stdin. Output is always sent to stdout.</p></dd></dl></div></div><div class="refsect1"><a id="idp73860368"></a><h2>Diagnostics</h2><p>The exit code of <span class="command"><strong>bib2ris</strong></span> indicates what went wrong in general (the details can be found in the log output). The code is the sum of the following error values:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="emphasis"><em>1</em></span></span></dt><dd><p>general error; includes out of memory situations and invalid command-line options</p></dd><dt><span class="term"><span class="emphasis"><em>2</em></span></span></dt><dd><p>incomplete entry (at least one essential field in an entry was missing)</p></dd><dt><span class="term"><span class="emphasis"><em>4</em></span></span></dt><dd><p>unknown field name</p></dd><dt><span class="term"><span class="emphasis"><em>8</em></span></span></dt><dd><p>unknown publication type</p></dd><dt><span class="term"><span class="emphasis"><em>16</em></span></span></dt><dd><p>invalid BibTeX->RIS type mapping</p></dd><dt><span class="term"><span class="emphasis"><em>32</em></span></span></dt><dd><p>parse error; includes file access errors</p></dd></dl></div></div><div class="refsect1"><a id="bib2ris-configuration"></a><h2>Configuration</h2><p><span class="command"><strong>bib2ris</strong></span> evaluates the file <code class="filename">bib2risrc</code> to initialize itself.</p><div class="table"><a id="idp73879056"></a><p class="title"><strong>Table 14.2. bib2risrc</strong></p><div class="table-contents"><table summary="bib2risrc" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Variable</th><th>Default</th><th>Comment</th></tr></thead><tbody><tr><td>logfile</td><td>/var/log/bib2ris.log</td><td>The full path of a custom log file. This is used only if logdest is set appropriately.</td></tr><tr><td>logdest</td><td>1</td><td>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.</td></tr><tr><td>loglevel</td><td>6</td><td>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.</td></tr><tr><td>abbrevfirst</td><td>t</td><td>If this option is set to "t", the first names of all authors and editors will be abbreviated to the initials. If set to "f", the first names will be used as they are found in the BibTeX bibliography file.</td></tr><tr><td>listsep</td><td>;</td><td>This is the delimiter which separates individual keywords in a non-standard keyword field. Use the string "spc" for whitespace-separated lists (spaces and tabs).</td></tr><tr><td>forcejabbrev</td><td>f</td><td>If this is set to "t", journal names will be wrapped in RIS "JO" entries. If it is set to "f", bib2ris will use "JO" entries only if the journal name contains at least one period, otherwise it will use "JF".</td></tr><tr><td>maparticle</td><td>JOUR</td><td>map the BibTeX article publication type to a RIS type</td></tr><tr><td>mapbook</td><td>BOOK</td><td>map the BibTeX book publication type to a RIS type</td></tr><tr><td>mapbooklet</td><td>PAMP</td><td>map the BibTeX booklet publication type to a RIS type</td></tr><tr><td>mapconference</td><td>CHAP</td><td>map the BibTeX conference publication type to a RIS type</td></tr><tr><td>mapinbook</td><td>CHAP</td><td>map the BibTeX inbook publication type to a RIS type</td></tr><tr><td>mapincollection</td><td>CHAP</td><td>map the BibTeX incollection publication type to a RIS type</td></tr><tr><td>mapinproceedings</td><td>CHAP</td><td>map the BibTeX inproceedings publication type to a RIS type</td></tr><tr><td>mapmanual</td><td>BOOK</td><td>map the BibTeX manual publication type to a RIS type</td></tr><tr><td>mapmastersthesis</td><td>THES</td><td>map the BibTeX mastersthesis publication type to a RIS type</td></tr><tr><td>mapmisc</td><td>GEN</td><td>map the BibTeX misc publication type to a RIS type</td></tr><tr><td>mapphdthesis</td><td>THES</td><td>map the BibTeX phdthesis publication type to a RIS type</td></tr><tr><td>mapproceedings</td><td>CONF</td><td>map the BibTeX proceedings publication type to a RIS type</td></tr><tr><td>maptechreport</td><td>RPRT</td><td>map the BibTeX techreport publication type to a RIS type</td></tr><tr><td>mapunpublished</td><td>UNPB</td><td>map the BibTeX unpublished publication type to a RIS type</td></tr><tr><td>nsf_xyz</td><td>(none)</td><td>You can specify an unlimited number of these entries to map non-standard BibTeX fields to RIS tags. The BibTeX field name in this variable has to be in lowercase, regardless of the case in your input data (bib2ris treats field names as case-insensitive). The two-letter RIS tag has to be in uppercase. E.g. to map your BibTeX "Abstract" field to the RIS "N2" tag, the entry would read: "nsf_abstract N2".</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="refsect1"><a id="bib2ris-data-processing"></a><h2>Data Processing</h2><p>This section provides a few hints about the data conversion itself and the BibTeX format requirements.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The parsing of the input data is done by the <code class="filename">btparse</code> library. All limitations of that library apply to bib2ris as well. This applies very specifically to two hardcoded settings in <code class="filename">btparse</code> which, simply put, limit the size and complexity (in terms of macros) of an input file that btparse can handle. If you run into this kind of problem (I had to pull a 2 MB BibTeX bibliography from the net in order to verify this limit) you should increase the values of <code class="varname">NUM_MACROS</code> and <code class="varname">STRING_SIZE</code> in the source file <code class="filename">macros.c</code> and recompile the <code class="filename">btparse</code> library.</p></li><li class="listitem"><p>All entry names and field names in the BibTeX input file are treated as case-insensitive, i.e. "BoOk" is the same as "book" and "AUTHOR" is the same as "aUthoR".</p></li><li class="listitem"><p>The entries are checked for completeness. An error is generated if an entry lacks fields which are considered essential for the particular publication type.</p></li><li class="listitem"><p>Non-standard fields can be imported in addition to the predefined BibTeX fields. Create an entry for each non-standard BibTeX field name that your input data use in your <a class="link" href="re12.html#bib2ris-configuration" title="Configuration">bib2ris configuration</a> file. The data are handled differently based on the type of RIS field they are imported to. If the data are imported to the RIS fields AD, N1, or N2, which basically have an unlimited size, all occurrences of these fields will be concatenated into a single AD, N1, or N2 tag line, respectively. If the data are mapped to the RIS KW field, the string will be tokenized based on the list separator specified in the listsep configuration variable. Each token will be written as a separate KW tag line. A special case is the RIS pseudo-field "PY.day". Data imported to this tag are integrated as the day part in the publication date tag line "PY" (year and month, but not day, are standard BibTeX fields and are recognized by default). All other fields will be printed with their requested RIS tag. It is at the discretion of any RIS importing application to decide what to do with duplicate tag lines. Multiples are allowed for author tags (AU, A2, A3) and the keyword tag (KW). refdb will use the <span class="emphasis"><em>last</em></span> occurrence of a tag line that does not allow multiple occurrences.</p></li><li class="listitem"><p>Abbreviated journal names are detected only if they use periods. E.g. <span class="quote">“<span class="quote">J. Biol. Chem.</span>”</span> will be mapped to a "JO" RIS element whereas <span class="quote">“<span class="quote">J Biol Chem</span>”</span> will be (incorrectly) mapped to a "JF" element (<span class="quote">“<span class="quote">Journal of Biological Chemistry</span>”</span> would correctly end up here too). Spaces after periods are optional. To capture <span class="quote">“<span class="quote">J Biol Chem</span>”</span> in a "JO" element, use the <code class="option">-j</code> command line option or the "forcejabbrev" configuration file variable.</p></li><li class="listitem"><p>The mapping of BibTeX publication types (book, inproceedings...) to RIS types as specified in the configuration file is checked for valid RIS types. If an invalid RIS type is specified, an error is generated and the compile-time default is used instead.</p></li><li class="listitem"><p>By default the first names of authors and editors are not abbreviated. If you wish you can configure <span class="command"><strong>bib2ris</strong></span> to abbreviate first and middle names.</p></li></ul></div></div><div class="refsect1"><a id="bib2ris-files"></a><h2>Files</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">PREFIX/etc/refdb/bib2risrc</code></span></dt><dd><p>The global configuration file of bib2ris.</p></dd><dt><span class="term"><code class="filename">$HOME/.bib2risrc</code></span></dt><dd><p>The user configuration file of bib2ris.</p></dd></dl></div></div><div class="refsect1"><a id="bib2ris-see_also2"></a><h2>See also</h2><p><span class="emphasis"><em>RefDB</em></span> (7),
<span class="emphasis"><em><a class="link" href="re19.html" title="refdb_latex2utf8txt">refdb_latex2utf8txt</a></em></span> (1),
<span class="emphasis"><em><a class="link" href="re13.html" title="db2ris">db2ris</a></em></span> (1),
<span class="emphasis"><em><a class="link" href="re14.html" title="en2ris">en2ris</a></em></span> (1),
<span class="emphasis"><em><a class="link" href="re15.html" title="marc2ris">marc2ris</a></em></span> (1),
<span class="emphasis"><em><a class="link" href="re16.html" title="med2ris">med2ris</a></em></span> (1).</p><p><span class="emphasis"><em>RefDB manual (local copy) </em></span> PREFIX/share/doc/refdb-<version>/refdb-manual/index.html</p><p><span class="emphasis"><em>RefDB manual (web) </em></span> <<a class="ulink" href="http://refdb.sourceforge.net/manual/index.html" target="_top">http://refdb.sourceforge.net/manual/index.html</a>></p><p><span class="emphasis"><em>RefDB on the web </em></span> <<a class="ulink" href="http://refdb.sourceforge.net/" target="_top">http://refdb.sourceforge.net/</a>></p></div><div class="refsect1"><a id="bib2ris-author2"></a><h2>Author</h2><p>bib2ris was written by Markus Hoenicka <markus@mhoenicka.de>.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="re11.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch14.html#idp69978912">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="re13.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">refdbc </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> db2ris</td></tr></table></div></body></html>
|