Thread: [Refdb-cvs] CVS: refdb/doc refdba.1.xml,NONE,1.1.2.1 bib2ris.1.xml,NONE,1.1.2.1
Status: Beta
Brought to you by:
mhoenicka
Menu
▾
▴
refdb-cvs
|
From: Markus H. <mho...@us...> - 2006-01-08 22:32:49
|
Update of /cvsroot/refdb/refdb/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv12604 Added Files: Tag: Release_0_9_5_stable refdba.1.xml bib2ris.1.xml Log Message: moved refdb-manual to xml --- NEW FILE --- <?xml version="1.0" encoding="UTF-8"?> <refentry id='refentry-refdba'> <refentryinfo><date>2005-10-15</date></refentryinfo> <refmeta> <refentrytitle>REFDBA</refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo class='date'>2005-10-15</refmiscinfo> <refmiscinfo class='manual'>refdba Manual</refmiscinfo> </refmeta> <refnamediv id='refdba-name'> <refname>refdba</refname> <refpurpose>the administration client of RefDB</refpurpose> </refnamediv> <!-- body begins here --> <refsynopsisdiv id='refdba-synopsis'> <para>Interactive mode:</para> <cmdsynopsis> <command>refdba</command> <arg choice='opt'><option>-c</option> <replaceable>pager-command</replaceable></arg> <arg choice='opt'><option>-e</option> <replaceable>log-destination</replaceable></arg> [...1314 lines suppressed...] <refsect1 id='refdba-see_also'> <title>SEE ALSO</title> <para><emphasis remap='B'>RefDB</emphasis> (7), <emphasis remap='B'><link linkend="refentry-refdbd">refdbd</link></emphasis> (1), <emphasis remap='B'><link linkend="refentry-refdbc">refdbc</link></emphasis> (1).</para> <para><emphasis remap='I'>RefDB manual (local copy) </emphasis> /usr/local/share/doc/refdb-0.9.7-pre1/index.html</para> <para><emphasis remap='I'>RefDB manual (web) </emphasis> <<ulink url='http://refdb.sourceforge.net/manual/index.html'>http://refdb.sourceforge.net/manual/index.html</ulink>></para> <para><emphasis remap='I'>RefDB on the web </emphasis> <<ulink url='http://refdb.sourceforge.net/'>http://refdb.sourceforge.net/</ulink>></para> </refsect1> <refsect1 id='refdba-author'> <title>AUTHOR</title> <para>refdba was written by Markus Hoenicka <ma...@mh...>.</para> </refsect1> </refentry> --- NEW FILE --- <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <!-- lifted from troff+man by doclifter --> <refentry id="refentry-bib2ris"> <refentryinfo><date>2005-10-16</date></refentryinfo> <refmeta> <refentrytitle>BIB2RIS</refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo class='date'>2005-10-16</refmiscinfo> <refmiscinfo class='manual'>bib2ris Manual</refmiscinfo> </refmeta> <refnamediv id='bib2ris-name2'> <refname>bib2ris</refname> <refpurpose>converts bibtex bibliographic data to the RIS format</refpurpose> </refnamediv> <!-- body begins here --> <refsynopsisdiv id='bib2ris-synopsis'> <cmdsynopsis> <command>bib2ris</command> <arg choice='opt'>-e <replaceable>log-destination</replaceable></arg> <arg choice='opt'>-h </arg> <arg choice='opt'>-j </arg> <arg choice='opt'>-l <replaceable>log-level</replaceable></arg> <arg choice='opt'>-L <replaceable>log-file</replaceable></arg> <arg choice='opt'>-q </arg> <arg choice='opt'>-s <replaceable>separator</replaceable></arg> <arg choice='opt'>-v </arg> <arg choice='opt'>-y <replaceable>confdir</replaceable></arg> <arg choice='plain'><replaceable>file</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> <refsect1 id='bib2ris-description2'><title>DESCRIPTION</title> <para>bib2ris converts BibTeX bibliography files into RIS files.</para> <para>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.</para> <para>There are basically two ways how to handle BibTeX data with refdb:</para> <orderedlist inheritnum="ignore" continuation="restarts"> <listitem> <para>Convert all entries to plain text. This will allow you to work with your data just as with "native" RIS data, i.e. all field values in the output of the refdb backends will be plain text as well.</para> </listitem> <listitem> <para>Keep the TeX formatting in the entries. This will allow you to make use of TeX commands and formatting stuff in the BibTeX bibliography output, but it'll be a bit strange to work with these data in the rest of refdb. When formulating queries you will have to take account of the TeX magic, and this stuff will also show up in all other output (screen, HTML, DocBook etc).</para> </listitem> </orderedlist> <para>There may be better support for this situation in future releases of refdb. Currently the rule of thumb is: If you're interested only in BibTeX bibliographies, keep the formatting. If you're interested in generating both BibTeX and DocBook bibliographies or if you're mainly interested to maintain an easily accessible reference database, strip off the TeX formatting. This is best done with the supplied <link linkend="bib2ris-postprocessing"><command moreinfo="none">tex2mail</command></link> script which will be discussed shortly.</para> </refsect1> <refsect1 id='bib2ris-options'><title>OPTIONS</title> <variablelist remap='TP'> <varlistentry> <term><option>-e</option> <replaceable>log-destination</replaceable></term> <listitem> <para>log-destination can have the values 0, 1, or 2, or the equivalent strings <emphasis remap='I'>stderr</emphasis>, <emphasis remap='I'>syslog</emphasis>, or <emphasis remap='I'>file</emphasis>, respectively. This value specifies where the log information goes to. <literal>0</literal> (zero) means the messages are sent to stderr. They are immediately available on the screen but they may interfere with command output. <literal>1</literal> 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 <filename>/var/log/user.log</filename>. <literal>2</literal> will send the messages to a custom log file which can be specified with the <option>-L</option> option.</para> </listitem> </varlistentry> <varlistentry> <term><option>-h</option></term> <listitem> <para>Displays help and usage screen, then exits.</para> </listitem> </varlistentry> <varlistentry> <term><option>-j</option></term> <listitem> <para>Force bib2ris to use <emphasis remap='B'>JO</emphasis> 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, <emphasis remap='B'>JO</emphasis> will be used, otherwise <emphasis remap='B'>JF</emphasis> will be used.</para> </listitem> </varlistentry> <varlistentry> <term><option>-l</option> <replaceable>log-level</replaceable></term> <listitem> <para>Specify the priority up to which events are logged. This is either a number between <literal>0</literal> and <literal>7</literal> or one of the strings <emphasis remap='I'>emerg</emphasis>, <emphasis remap='I'>alert</emphasis>, <emphasis remap='I'>crit</emphasis>, <emphasis remap='I'>err</emphasis>, <emphasis remap='I'>warning</emphasis>, <emphasis remap='I'>notice</emphasis>, <emphasis remap='I'>info</emphasis>, <emphasis remap='I'>debug</emphasis>, respectively (see also Log level definitions). <option>-1</option> disables logging completely. A low log level like <literal>0</literal> means that only the most critical messages are logged. A higher log level means that less critical events are logged as well. <literal>7</literal> 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.</para> </listitem> </varlistentry> <varlistentry> <term><option>-L</option> <replaceable>log-file</replaceable></term> <listitem> <para>Specify the full path to a log file that will receive the log messages. Typically this would be <filename>/var/log/refdba</filename>.</para> </listitem> </varlistentry> <varlistentry> <term><option>-q</option></term> <listitem> <para>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.</para> </listitem> </varlistentry> <varlistentry> <term><option>-s</option> <replaceable>separator</replaceable></term> <listitem> <para>Specify the delimiter which separates individual keywords in a non-standard keyword field. Use the string <emphasis remap='B'>spc</emphasis> for whitespace-separated lists (spaces and tabs).</para> </listitem> </varlistentry> <varlistentry> <term><option>-v</option></term> <listitem> <para>Prints version and copyright information, then exits.</para> </listitem> </varlistentry> <varlistentry> <term><option>-y</option> <replaceable>confdir</replaceable></term> <listitem> <para>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 <option>-y</option> option unless you use precompiled binaries in unusual locations, e.g. by relocating a rpm package.</para> </listitem> </varlistentry> <varlistentry> <term><emphasis remap='I'>file</emphasis></term> <listitem> <para>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.</para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>DIAGNOSTICS</title> <para>The exit code of <command moreinfo="none">bib2ris</command> 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:</para> <variablelist> <varlistentry> <term><emphasis remap='I'>1</emphasis></term> <listitem> <para>general error; includes out of memory situations and invalid command-line options</para> </listitem> </varlistentry> <varlistentry> <term><emphasis remap='I'>2</emphasis></term> <listitem> <para>incomplete entry (at least one essential field in an entry was missing)</para> </listitem> </varlistentry> <varlistentry> <term><emphasis remap='I'>4</emphasis></term> <listitem> <para>unknown field name</para> </listitem> </varlistentry> <varlistentry> <term><emphasis remap='I'>8</emphasis></term> <listitem> <para>unknown publication type</para> </listitem> </varlistentry> <varlistentry> <term><emphasis remap='I'>16</emphasis></term> <listitem> <para>invalid BibTeX->RIS type mapping</para> </listitem> </varlistentry> <varlistentry> <term><emphasis remap='I'>32</emphasis></term> <listitem> <para>parse error; includes file access errors</para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1 id="bib2ris-configuration"> <title>CONFIGURATION</title> <para><command moreinfo="none">bib2ris</command> evaluates the file <filename moreinfo="none">bib2risrc</filename> to initialize itself.</para> <table> <title>bib2risrc</title> <tgroup cols="3"> <thead> <row> <entry>Variable</entry> <entry>Default</entry> <entry>Comment</entry> </row> </thead> <tbody> <row> <entry>logfile</entry> <entry>/var/log/bib2ris.log</entry> <entry>The full path of a custom log file. This is used only if logdest is set appropriately.</entry> </row> <row> <entry>logdest</entry> <entry>1</entry> <entry>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.</entry> </row> <row> <entry>loglevel</entry> <entry>6</entry> <entry>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.</entry> </row> <row> <entry>abbrevfirst</entry> <entry>t</entry> <entry>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.</entry> </row> <row> <entry>listsep</entry> <entry>;</entry> <entry>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).</entry> </row> <row> <entry>forcejabbrev</entry> <entry>f</entry> <entry>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".</entry> </row> <row> <entry>maparticle</entry> <entry>JOUR</entry> <entry>map the BibTeX article publication type to a RIS type</entry> </row> <row> <entry>mapbook</entry> <entry>BOOK</entry> <entry>map the BibTeX book publication type to a RIS type</entry> </row> <row> <entry>mapbooklet</entry> <entry>PAMP</entry> <entry>map the BibTeX booklet publication type to a RIS type</entry> </row> <row> <entry>mapconference</entry> <entry>CHAP</entry> <entry>map the BibTeX conference publication type to a RIS type</entry> </row> <row> <entry>mapinbook</entry> <entry>CHAP</entry> <entry>map the BibTeX inbook publication type to a RIS type</entry> </row> <row> <entry>mapincollection</entry> <entry>CHAP</entry> <entry>map the BibTeX incollection publication type to a RIS type</entry> </row> <row> <entry>mapinproceedings</entry> <entry>CHAP</entry> <entry>map the BibTeX inproceedings publication type to a RIS type</entry> </row> <row> <entry>mapmanual</entry> <entry>BOOK</entry> <entry>map the BibTeX manual publication type to a RIS type</entry> </row> <row> <entry>mapmastersthesis</entry> <entry>THES</entry> <entry>map the BibTeX mastersthesis publication type to a RIS type</entry> </row> <row> <entry>mapmisc</entry> <entry>GEN</entry> <entry>map the BibTeX misc publication type to a RIS type</entry> </row> <row> <entry>mapphdthesis</entry> <entry>THES</entry> <entry>map the BibTeX phdthesis publication type to a RIS type</entry> </row> <row> <entry>mapproceedings</entry> <entry>CONF</entry> <entry>map the BibTeX proceedings publication type to a RIS type</entry> </row> <row> <entry>maptechreport</entry> <entry>RPRT</entry> <entry>map the BibTeX techreport publication type to a RIS type</entry> </row> <row> <entry>mapunpublished</entry> <entry>UNPB</entry> <entry>map the BibTeX unpublished publication type to a RIS type</entry> </row> <row> <entry>nsf_xyz</entry> <entry>(none)</entry> <entry>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".</entry> </row> </tbody> </tgroup> </table> </refsect1> <refsect1 id="bib2ris-data-processing"> <title>DATA PROCESSING</title> <para>This section provides a few hints about the data conversion itself and the BibTeX format requirements.</para> <itemizedlist> <listitem> <para>The parsing of the input data is done by the <filename moreinfo="none">btparse</filename> library. All limitations of that library apply to bib2ris as well. This applies very specifically to two hardcoded settings in <filename moreinfo="none">btparse</filename> 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 <varname>NUM_MACROS</varname> and <varname>STRING_SIZE</varname> in the source file <filename moreinfo="none">macros.c</filename> and recompile the <filename moreinfo="none">btparse</filename> library.</para> </listitem> <listitem> <para>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".</para> </listitem> <listitem> <para>The entries are checked for completeness. An error is generated if an entry lacks fields which are considered essential for the particular publication type.</para> </listitem> <listitem> <para>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 <link linkend="bib2ris-configuration">bib2ris configuration</link> 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 <emphasis>last</emphasis> occurrence of a tag line that does not allow multiple occurrences.</para> </listitem> <listitem> <para>Abbreviated journal names are detected only if they use periods. E.g. <quote>J. Biol. Chem.</quote> will be mapped to a "JO" RIS element whereas <quote>J Biol Chem</quote> will be (incorrectly) mapped to a "JF" element (<quote>Journal of Biological Chemistry</quote> would correctly end up here too). Spaces after periods are optional. To capture <quote>J Biol Chem</quote> in a "JO" element, use the <option>-j</option> command line option or the "forcejabbrev" configuration file variable.</para> </listitem> <listitem> <para>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.</para> </listitem> <listitem> <para>By default the first names of authors and editors are not abbreviated. If you wish you can configure <command moreinfo="none">bib2ris</command> to abbreviate first and middle names.</para> </listitem> </itemizedlist> </refsect1> <refsect1 id="bib2ris-postprocessing"> <title>Post-processing with tex2mail</title> <para>refdb ships with a slightly modified version of the <command moreinfo="none">tex2mail</command> Perl script. The original purpose of this script is to convert (La)TeX input into a human-readable plain text file, taking care of various mathematical commands which can be rendered in multi-line output. In lieu of a better way to provide someting useful in no time I hacked this script to generate suitable RIS output when used with the proper command line switches. Without the <option>-ris</option> switch the script behaves just like the original tex2mail script. The purpose of this script in the context of refdb is to strip TeX commands and constructs from the RIS output that bib2ris generates.</para> <warning> <itemizedlist> <listitem> <para>This script is really a quick hack. It will be replaced by something more dedicated to its purpose (at least I'll maintain this illusion for the time being).</para> </listitem> <listitem> <para>If you have LaTeX math formulas somewhere in the field values, strange and wondrous things are likely to happen. You will have to manually fix the output.</para> </listitem> </itemizedlist> </warning> <para>Run the script with the following command, assuming that <filename moreinfo="none">foo.ris</filename> is the output that you generated from your BibTeX bibliography file with the help of bib2ris:</para> <screen format="linespecific"><prompt moreinfo="none">~# </prompt>tex2mail -noindent -ragged -linelength 65535 -ris < foo.ris > foo-notex.ris</screen> <para>The argument of the <option>-linelength</option> option should be large enough to display each field in a single line, otherwise tex2mail tries to generate some simple layout which will screw up the RIS file.</para> </refsect1> <refsect1 id='bib2ris-files'><title>FILES</title> <variablelist remap='TP'> <varlistentry> <term><filename>/usr/local/etc/refdb/bib2risrc</filename></term> <listitem> <para>The global configuration file of bib2ris.</para> </listitem> </varlistentry> <varlistentry> <term><emphasis remap='I'>$HOME/.bib2risrc</emphasis></term> <listitem> <para>The user configuration file of bib2ris.</para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1 id='bib2ris-see_also2'><title>SEE ALSO</title> <para><emphasis remap='B'>RefDB</emphasis> (7), <emphasis remap='B'><link linkend="refentry-db2ris">db2ris</link></emphasis> (1). <emphasis remap='B'><link linkend="refentry-en2ris">en2ris</link></emphasis> (1). <emphasis remap='B'><link linkend="refentry-marc2ris">marc2ris</link></emphasis> (1). <emphasis remap='B'><link linkend="refentry-med2ris">med2ris</link></emphasis> (1).</para> <para><emphasis remap='I'>RefDB manual (local copy) </emphasis> /usr/local/share/doc/refdb-0.9.7-pre1/index.html</para> <para><emphasis remap='I'>RefDB manual (web) </emphasis> <<ulink url='http://refdb.sourceforge.net/manual/index.html'>http://refdb.sourceforge.net/manual/index.html</ulink>></para> <para><emphasis remap='I'>RefDB on the web </emphasis> <<ulink url='http://refdb.sourceforge.net/'>http://refdb.sourceforge.net/</ulink>></para> </refsect1> <refsect1 id='author2'><title>AUTHOR</title> <para>bib2ris was written by Markus Hoenicka <ma...@mh...>.</para> </refsect1> </refentry> |
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X