Thread: [Refdb-cvs] CVS: refdb/doc RefDB.7.xml,1.1.2.1,1.1.2.2 bib2ris.1.xml,1.1.2.1,1.1.2.2 db2ris.1.xml,1.
Status: Beta
Brought to you by:
mhoenicka
Menu
▾
▴
refdb-cvs
Update of /cvsroot/refdb/refdb/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18137/doc Modified Files: Tag: Release_0_9_5_stable RefDB.7.xml bib2ris.1.xml db2ris.1.xml eenc.1.xml en2ris.1.xml marc2ris.1.xml med2ris.1.xml refdb-backup.1.xml refdb-dos2unix.1.xml refdb-ms.1.xml refdb-restore.1.xml refdb.8.xml refdba.1.xml refdbc.1.xml refdbctl.1.xml refdbd.1.xml refdbib.1.xml refdbjade.1.xml refdbnd.1.xml refdbxml.1.xml runbib.1.xml Log Message: lower/mixed-cased section titles - should have known the manpage stylesheets handle this themselves Index: RefDB.7.xml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/Attic/RefDB.7.xml,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -U2 -r1.1.2.1 -r1.1.2.2 --- RefDB.7.xml 8 Jan 2006 22:03:15 -0000 1.1.2.1 +++ RefDB.7.xml 11 Jan 2006 00:12:29 -0000 1.1.2.2 @@ -1,299 +1,174 @@ <?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 --> +"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <refentry id='refdb7'> -<!-- Hey, EMACS: \-*\- nroff \-*\- --> -<!-- --> -<!-- Filename: <FILENAME> --> -<!-- Author: David Nebauer --> -<!-- History: <DATE> \- created --> -<!-- --> -<!-- For header (.TH), first parameter, NAME, should be all caps --> -<!-- Second parameter, SECTION, should be 1\-8, maybe w/ subsection --> -<!-- Other parameters are allowed: see man(7), man(1) --> -<!-- Please adjust the date whenever revising the manpage. --> -<!-- --> -<!-- Some roff macros, for reference: --> -<!-- .nh disable hyphenation --> -<!-- .hy enable hyphenation --> -<!-- .ad l left justify --> -<!-- .ad b justify to both left and right margins --> -<!-- .nf disable filling --> -<!-- .fi enable filling --> -<!-- .br insert line break --> -<!-- .sp <n> insert n+1 empty lines --> -<!-- for manpage\-specific macros, see man(7) --> -<!-- --> -<!-- Formatting [see groff_char (7) for details]: --> -<!-- ' : escape sequence for (') --> -<!-- `` : left/open double quote --> -<!-- '' : right/close double quote --> -<!-- ` : left/open single quote --> -<!-- ' : right/close single quote --> -<!-- — : escape sequence for em dash --> -<!-- – : escape sequence for en dash --> -<!-- \. : escape sequence for period/dot --> -<!-- \fX : escape sequence that changes font, where 'X' can be 'R|I|B|BI' --> -<!-- (R = roman/normal | I = italic | B = bold | BI = bold\-italic) --> -<!-- \fP : switch to previous font --> -<!-- in this case '\fR' could also have been used --> -<!-- --> -<!-- Bulleted list: --> -<!-- A bulleted list: --> -<!-- .IP • 2 --> -<!-- lawyers --> -<!-- .IP • --> -<!-- guns --> -<!-- .IP • --> -<!-- money --> -<!-- Numbered list: --> -<!-- .nr step 1 1 --> -<!-- A numbered list: --> -<!-- .IP \n[step] 3 --> -<!-- lawyers --> -<!-- .IP \n+[step] --> -<!-- guns --> -<!-- .IP \n+[step] --> -<!-- money --> -<refentryinfo><date>2005/10/16</date></refentryinfo> -<refmeta> -<refentrytitle>REFDB</refentrytitle> -<manvolnum>7</manvolnum> -<refmiscinfo class='date'>2005/10/16</refmiscinfo> -<refmiscinfo class='manual'>RefDB Manual</refmiscinfo> -</refmeta> -<refnamediv id='name'> -<refname>RefDB</refname> -<refpurpose>a set of tools to manage bibliographic references, notes, and bibliographies for markup languages</refpurpose> -</refnamediv> -<!-- body begins here --> - -<refsect1 id='description'><title>DESCRIPTION</title> - -<refsect2 id='general_features'><title>GENERAL FEATURES</title> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>RefDB is a reference/notes database and bibliography tool for SGML, XML, and LaTeX documents.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>RefDB is mainly implemented in C, with a few Perl scripts inbetween, as well as shell scripts as "glue". It can be compiled on all platforms with a decent C compiler (a small amount of porting may be required). It builds and runs out of the box on Linux, FreeBSD, NetBSD, Solaris, OSX, Darwin, and Windows/Cygwin.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>RefDB is modular and accessible. You can plug in a variety of database engines to store your data, and you can choose between a variety of interfaces for interactive work. You can use RefDB in your projects through shell scripts or from Perl programs.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>The RefDB handbook (more than 300 printed pages) helps you to get RefDB up and running quickly and explains how to use the software for both administrators and users in great detail. In addition there is a tutorial targeted at plain users.</para> - </listitem> - </varlistentry> -</variablelist> -</refsect2> - -<refsect2 id='application_design'><title>APPLICATION DESIGN</title> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>RefDB uses a SQL database engine to store the references, notes, and the bibliography styles. Choose either an external database server for optimum performance and flexibility, or an embedded database engine for convenience (see below for supported database engines).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>Both reference and bibliography style databases use the relational features of SQL databases extensively to consolidate information and to save storage space.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>RefDB employs a three-tier architecture with lots of flexibility: clients, an application server that can run as a daemon, and the database server. If you prefer the embedded SQL engine, there'll be a two-tier setup. In both cases, all tiers may run on a single workstation for individual use.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>The application server can generate log messages to monitor its operation.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>RefDB contains two standard interfaces: a command line interface for terminal addicts and for use in scripts, and a PHP-based web interface for a more visual approach. In addition, both Emacs and Vim users can access RefDB from the editing environment they're used to. Finally, there is also a Perl client module to integrate RefDB functionality into your own Perl programs.</para> - </listitem> - </varlistentry> -</variablelist> -</refsect2> - -<refsect2 id='reference_and_notes_management'><title>REFERENCE AND NOTES MANAGEMENT</title> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>The main input format for bibliographic data is RIS which can be generated and imported by all major reference databases on Windows (Reference Manager, EndNote and the like). An XML representation of RIS using the risx DTD is also supported as a native format. The latter is well suited as a means to import SGML or XML bibliographic data.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>Import filters are provided for Medline (tagged and XML), BibTeX, MARC, and DocBook.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>The data can be retrieved as simple text, formatted as HTML, formatted as a DocBook bibliography element (SGML or XML), formatted as a TEI listBibl element (XML), formatted as BibTeX reference list, or formatted as RIS or risx files.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>All character encodings supported by your platform can be used both for data input and for data export. This includes European character sets like Latin-1 and of course Unicode.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>Extended notes can be linked to one or more references, authors, periodicals, or keywords to create topics or material collections. These are more powerful and flexible than folder systems and the like.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>The query language is fairly simple yet powerful. You can use booleans to combine queries on any combination of fields. You can use brackets to group queries. You can use Unix-style regular expressions to formulate advanced queries.</para> - </listitem> - </varlistentry> -</variablelist> -</refsect2> - -<refsect2 id='bibliographies'><title>BIBLIOGRAPHIES</title> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>Formatted bibliographies can be created automatically from DocBook SGML/XML and TEI XML documents. This does not require any changes or extensions to the DTDs. RefDB can also be integrated as a data source into the LaTeX/BibTeX workflow.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>RefDB is extensible in terms of the supported document types: support for new document types can be added without hacking the tool itself (you only need to hack stylesheets)</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>Citation and reference styles can be defined in XML to match the weirdest requirements of journals and publishers.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>Sophisticated shell scripts and makefiles take care of the document transformations. The whole process is transparent to the user as all he needs to do is e.g. type make pdf to turn his document into a PDF file with formatted citations and bibliographies.</para> - </listitem> - </varlistentry> -</variablelist> -</refsect2> - -<refsect2 id='networking_capabilities'><title>NETWORKING CAPABILITIES</title> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>Due to the client/server design, RefDB is very well suited as a shared reference database for a workgroup or a department. However, it runs just fine on a single standalone workstation.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>Users can share databases and still have their personal reference lists. They can share their notes or keep them private on a per-note base.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>Concurrent read and write access of several users is supported. There is no need to restrict access of other users to read-only. However, if your database engine supports access control (MySQL and PostgreSQL), you can restrict access of some users to read-only.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>A simple method to access electronic offprints (e.g. in PDF or PostScript format) is provided in the HTML output and in the web interface. This also works across networks using mounted shares.</para> - </listitem> - </varlistentry> -</variablelist> -</refsect2> - -<refsect2 id='supported_database_servers'><title>SUPPORTED DATABASE SERVERS</title> -<para>RefDB versions 0.9 and later employ the libdbi database abstraction library to provide support for different SQL database engines. -Currently the following external SQL database servers are supported:</para> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>MySQL</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>PostgreSQL</para> - </listitem> - </varlistentry> -</variablelist> - -<para>The following embedded database engines are supported:</para> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>SQLite (versions 2.x and 3.x)</para> - </listitem> - </varlistentry> -</variablelist> -</refsect2> -</refsect1> - -<refsect1 id='see_also'><title>SEE ALSO</title> -<para><emphasis remap='B'>refdbd</emphasis> (1), -<emphasis remap='B'>refdba</emphasis> (1), -<emphasis remap='B'>refdbc</emphasis> (1), -<emphasis remap='B'>refdbbib</emphasis> (1), -<emphasis remap='B'>bib2ris</emphasis> (1), -<emphasis remap='B'>db2ris</emphasis> (1), -<emphasis remap='B'>en2ris</emphasis> (1), -<emphasis remap='B'>marc2ris</emphasis> (1), -<emphasis remap='B'>med2ris</emphasis> (1), -<emphasis remap='B'>eenc</emphasis> (1), -<emphasis remap='B'>refdb-backup</emphasis> (1), -<emphasis remap='B'>refdb-ms</emphasis> (1), -<emphasis remap='B'>refdb-restore</emphasis> (1), -<emphasis remap='B'>refdbjade</emphasis> (1), -<emphasis remap='B'>refdbnd</emphasis> (1), -<emphasis remap='B'>refdbxml</emphasis> (1), -<emphasis remap='B'>refdbctl</emphasis> (1), -<emphasis remap='B'>refdb</emphasis> (8).</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> + <refentryinfo><date>2005/10/16</date></refentryinfo> + <refmeta> + <refentrytitle>RefDB</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo class='date'>2005/10/16</refmiscinfo> + <refmiscinfo class='manual'>RefDB Manual</refmiscinfo> + </refmeta> + <refnamediv id='name'> + <refname>RefDB</refname> + <refpurpose>a set of tools to manage bibliographic references, notes, and bibliographies for markup languages</refpurpose> + </refnamediv> + <!-- body begins here --> + + <refsect1 id='description'> + <title>Description</title> + + <refsect2 id='general_features'> + <title>General Features</title> + <itemizedlist remap='IP'> + <listitem> + <para>RefDB is a reference/notes database and bibliography tool for SGML, XML, and LaTeX documents.</para> + </listitem> + <listitem> + <para>RefDB is mainly implemented in C, with a few Perl scripts inbetween, as well as shell scripts as "glue". It can be compiled on all platforms with a decent C compiler (a small amount of porting may be required). It builds and runs out of the box on Linux, FreeBSD, NetBSD, Solaris, OSX, Darwin, and Windows/Cygwin.</para> + </listitem> + <listitem> + <para>RefDB is modular and accessible. You can plug in a variety of database engines to store your data, and you can choose between a variety of interfaces for interactive work. You can use RefDB in your projects through shell scripts or from Perl programs.</para> + </listitem> + <listitem> + <para>The RefDB handbook (more than 300 printed pages) helps you to get RefDB up and running quickly and explains how to use the software for both administrators and users in great detail. In addition there is a tutorial targeted at plain users.</para> + </listitem> + </itemizedlist> + </refsect2> + + <refsect2 id='application_design'> + <title>Application Design</title> + <itemizedlist remap='IP'> + <listitem> + <para>RefDB uses a SQL database engine to store the references, notes, and the bibliography styles. Choose either an external database server for optimum performance and flexibility, or an embedded database engine for convenience (see below for supported database engines).</para> + </listitem> + <listitem> + <para>Both reference and bibliography style databases use the relational features of SQL databases extensively to consolidate information and to save storage space.</para> + </listitem> + <listitem> + <para>RefDB employs a three-tier architecture with lots of flexibility: clients, an application server that can run as a daemon, and the database server. If you prefer the embedded SQL engine, there'll be a two-tier setup. In both cases, all tiers may run on a single workstation for individual use.</para> + </listitem> + <listitem> + <para>The application server can generate log messages to monitor its operation.</para> + </listitem> + <listitem> + <para>RefDB contains two standard interfaces: a command line interface for terminal addicts and for use in scripts, and a PHP-based web interface for a more visual approach. In addition, both Emacs and Vim users can access RefDB from the editing environment they're used to. Finally, there is also a Perl client module to integrate RefDB functionality into your own Perl programs.</para> + </listitem> + </itemizedlist> + </refsect2> + + <refsect2 id='reference_and_notes_management'> + <title>Reference and Notes Management</title> + <itemizedlist remap='IP'> + <listitem> + <para>The main input format for bibliographic data is RIS which can be generated and imported by all major reference databases on Windows (Reference Manager, EndNote and the like). An XML representation of RIS using the risx DTD is also supported as a native format. The latter is well suited as a means to import SGML or XML bibliographic data.</para> + </listitem> + <listitem> + <para>Import filters are provided for Medline (tagged and XML), BibTeX, MARC, and DocBook.</para> + </listitem> + <listitem> + <para>The data can be retrieved as simple text, formatted as HTML, formatted as a DocBook bibliography element (SGML or XML), formatted as a TEI listBibl element (XML), formatted as BibTeX reference list, or formatted as RIS or risx files.</para> + </listitem> + <listitem> + <para>All character encodings supported by your platform can be used both for data input and for data export. This includes European character sets like Latin-1 and of course Unicode.</para> + </listitem> + <listitem> + <para>Extended notes can be linked to one or more references, authors, periodicals, or keywords to create topics or material collections. These are more powerful and flexible than folder systems and the like.</para> + </listitem> + <listitem> + <para>The query language is fairly simple yet powerful. You can use booleans to combine queries on any combination of fields. You can use brackets to group queries. You can use Unix-style regular expressions to formulate advanced queries.</para> + </listitem> + </itemizedlist> + </refsect2> + + <refsect2 id='bibliographies'> + <title>Bibliographies</title> + <itemizedlist remap='IP'> + <listitem> + <para>Formatted bibliographies can be created automatically from DocBook SGML/XML and TEI XML documents. This does not require any changes or extensions to the DTDs. RefDB can also be integrated as a data source into the LaTeX/BibTeX workflow.</para> + </listitem> + <listitem> + <para>RefDB is extensible in terms of the supported document types: support for new document types can be added without hacking the tool itself (you only need to hack stylesheets)</para> + </listitem> + <listitem> + <para>Citation and reference styles can be defined in XML to match the weirdest requirements of journals and publishers.</para> + </listitem> + <listitem> + <para>Sophisticated shell scripts and makefiles take care of the document transformations. The whole process is transparent to the user as all he needs to do is e.g. type <command>make pdf</command> to turn his document into a PDF file with formatted citations and bibliographies.</para> + </listitem> + </itemizedlist> + </refsect2> + + <refsect2 id='networking_capabilities'> + <title>Networking Capabilities</title> + <itemizedlist remap='IP'> + <listitem> + <para>Due to the client/server design, RefDB is very well suited as a shared reference database for a workgroup or a department. However, it runs just fine on a single standalone workstation.</para> + </listitem> + <listitem> + <para>Users can share databases and still have their personal reference lists. They can share their notes or keep them private on a per-note base.</para> + </listitem> + <listitem> + <para>Concurrent read and write access of several users is supported. There is no need to restrict access of other users to read-only. However, if your database engine supports access control (MySQL and PostgreSQL), you can restrict access of some users to read-only.</para> + </listitem> + <listitem> + <para>A simple method to access electronic offprints (e.g. in PDF or PostScript format) is provided in the HTML output and in the web interface. This also works across networks using mounted shares.</para> + </listitem> + </itemizedlist> + </refsect2> + + <refsect2 id='supported_database_servers'> + <title>Supported Database Servers</title> + <para>RefDB versions 0.9 and later employ the libdbi database abstraction library to provide support for different SQL database engines. + Currently the following external SQL database servers are supported:</para> + <itemizedlist remap='IP'> + <listitem> + <para>MySQL</para> + </listitem> + <listitem> + <para>PostgreSQL</para> + </listitem> + </itemizedlist> + + <para>The following embedded database engines are supported:</para> + <itemizedlist remap='IP'> + <listitem> + <para>SQLite (versions 2.x and 3.x)</para> + </listitem> + </itemizedlist> + </refsect2> + </refsect1> + + <refsect1 id='see_also'><title>See also</title> + <para><emphasis remap='B'>refdbd</emphasis> (1), + <emphasis remap='B'>refdba</emphasis> (1), + <emphasis remap='B'>refdbc</emphasis> (1), + <emphasis remap='B'>refdbbib</emphasis> (1), + <emphasis remap='B'>bib2ris</emphasis> (1), + <emphasis remap='B'>db2ris</emphasis> (1), + <emphasis remap='B'>en2ris</emphasis> (1), + <emphasis remap='B'>marc2ris</emphasis> (1), + <emphasis remap='B'>med2ris</emphasis> (1), + <emphasis remap='B'>eenc</emphasis> (1), + <emphasis remap='B'>refdb-backup</emphasis> (1), + <emphasis remap='B'>refdb-ms</emphasis> (1), + <emphasis remap='B'>refdb-restore</emphasis> (1), + <emphasis remap='B'>refdbjade</emphasis> (1), + <emphasis remap='B'>refdbnd</emphasis> (1), + <emphasis remap='B'>refdbxml</emphasis> (1), + <emphasis remap='B'>refdbctl</emphasis> (1), + <emphasis remap='B'>refdb</emphasis> (8).</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> + <para><emphasis remap='I'>RefDB on the web </emphasis> <<ulink url='http://refdb.sourceforge.net/'>http://refdb.sourceforge.net/</ulink>></para> + </refsect1> -<refsect1 id='author'><title>AUTHOR</title> -<para>RefDB was originally written by Markus Hoenicka <ma...@mh...>. For a list of current authors, see the file <filename>AUTHORS</filename>.</para> + <refsect1 id='author'><title>Author</title> + <para>RefDB was originally written by Markus Hoenicka <ma...@mh...>. For a list of current authors, see the file <filename>AUTHORS</filename>.</para> -</refsect1> + </refsect1> </refentry> Index: bib2ris.1.xml =================================================================== RCS file: /cvsroot/refdb/refdb/doc/Attic/bib2ris.1.xml,v retrieving revision 1.1.2.1 retrieving revision 1.1.2.2 diff -u -U2 -r1.1.2.1 -r1.1.2.2 --- bib2ris.1.xml 8 Jan 2006 22:32:40 -0000 1.1.2.1 +++ bib2ris.1.xml 11 Jan 2006 00:12:29 -0000 1.1.2.2 @@ -6,5 +6,5 @@ <refentryinfo><date>2005-10-16</date></refentryinfo> <refmeta> - <refentrytitle>BIB2RIS</refentrytitle> + <refentrytitle>bib2ris</refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo class='date'>2005-10-16</refmiscinfo> @@ -32,8 +32,9 @@ - <refsect1 id='bib2ris-description2'><title>DESCRIPTION</title> - <para>bib2ris converts BibTeX bibliography files into RIS files.</para> + <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>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"> @@ -48,318 +49,319 @@ </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> + <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>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> + <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> - </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> + <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> - </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> + <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> - </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> + <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> - </varlistentry> - <varlistentry> - <term><option>-v</option></term> <listitem> - <para>Prints version and copyright information, then exits.</para> + <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> - </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> + <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> - </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> + <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> - </varlistentry> - </variablelist> -</refsect1> + </itemizedlist> + </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> + <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><emphasis remap='I'>16</emphasis></term> + <term><filename>/usr/local/etc/refdb/bib2risrc</filename></term> <listitem> - <para>invalid BibTeX->RIS type mapping</para> + <para>The global configuration file of bib2ris.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='I'>32</emphasis></term> + <term><filename>$HOME/.bib2risrc</filename></term> <listitem> - <para>parse error; includes file access errors</para> + <para>The user configuration file of bib2ris.</para> </listitem> </varlistentry> </variablelist> -</refsect1> + </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). -<emph... [truncated message content] |
×
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