/usr/share/doc/refdb/refdb-manual/ch08.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 12 13 14 15 16 17 18 | <?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>Chapter 8. Reference management</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="pt03.html" title="Part III. User manual" /><link rel="prev" href="ch07s06.html" title="Input data mangling" /><link rel="next" href="ch08s02.html" title="Find and view references" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Reference management</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch07s06.html">Prev</a> </td><th width="60%" align="center">Part III. User manual</th><td width="20%" align="right"> <a accesskey="n" href="ch08s02.html">Next</a></td></tr></table><hr /></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a id="chapter-managing-references"></a>Chapter 8. Reference management</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="sect1"><a href="ch08.html#sect1-add-references">Add references</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch08.html#sect-add-ris-datasets">RIS datasets</a></span></dt><dt><span class="sect2"><a href="ch08.html#sect-add-risx-datasets">risx datasets</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch08s02.html">Find and view references</a></span></dt><dt><span class="sect1"><a href="ch08s03.html">Delete references</a></span></dt><dt><span class="sect1"><a href="ch08s04.html">Edit references</a></span></dt><dt><span class="sect1"><a href="ch08s05.html">Print references</a></span></dt><dt><span class="sect1"><a href="ch08s06.html">Managing personal reference lists</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch08s06.html#idp68122240">Creating and deleting personal reference lists</a></span></dt><dt><span class="sect2"><a href="ch08s06.html#idp68138704">Accessing references in personal reference lists</a></span></dt><dt><span class="sect2"><a href="ch08s06.html#idp68142192">Advanced use of personal reference lists</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch08s07.html">Global edit references</a></span></dt><dt><span class="sect1"><a href="ch08s08.html">Create periodical synonyms</a></span></dt><dt><span class="sect1"><a href="ch08s09.html">Character encoding issues</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch08s09.html#idp68168928">Character encodings of databases</a></span></dt><dt><span class="sect2"><a href="ch08s09.html#idp68180960">Character encodings of imported data</a></span></dt><dt><span class="sect2"><a href="ch08s09.html#idp68192272">Character encodings of exported data</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch08s10.html">Use pdfroot</a></span></dt><dt><span class="sect1"><a href="ch08s11.html">Interaction with external applications</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch08s11.html#idp68218768">Editor</a></span></dt><dt><span class="sect2"><a href="ch08s11.html#idp68230176">Viewer</a></span></dt></dl></dd></dl></div><p>You can manage your references with the refdbc command line client. We will demonstrate the interactive use of refdbc, but feel free to use the non-interactive batch mode instead if you prefer. We'll also use a conservative, least error-prone approach whenever there are several ways to achieve the same goal. E.g. we'll use intermediate files instead of piping so we can verify what we got at every stage. Once you're sure about what you're doing, you can still speed up things.</p><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect1-add-references"></a>Add references</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect-add-ris-datasets"></a>RIS datasets</h3></div></div></div><p>Adding references boils down to running <a class="link" href="re11.html#app-c-command-addref" title="addref"><span class="command"><strong>addref</strong></span></a> with proper input files. The input files have to be valid <a class="link" href="ch07.html#sect1-ris-format" title="Writing RIS datasets">RIS</a> files. They may contain one or more RIS datasets.</p><p>You can set some fields to default values with the <code class="option">-g <em class="replaceable"><code>defaultfile</code></em></code> option of the <span class="command"><strong>addref</strong></span>. This will add the tags given in the <em class="replaceable"><code>defaultfile</code></em> to the end of every dataset before they are added to the database. This means that these values override any values given in the datasets. This option may be convenient e.g. to set the reprint status of all datasets that you add in one fell swoop instead of editing them individually.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please be aware that any numerical values of the ID tag are ignored when you add references with the <a class="link" href="re11.html#app-c-command-addref" title="addref"><span class="command"><strong>addref</strong></span></a> command. RefDB assigns an automatically generated ID to every new reference, so you can't enforce arbitrary IDs. You can however use the ID tag to provide an alphanumeric citation key, such as "Miller1999". The citation key should consist only of letters and numbers within the 7-bit ASCII range and has to be unique in the database. Remember that the citation key has to be all uppercase if you want to create bibliographies for SGML documents. If you do not specify a citation key, RefDB will generate a unique citation key based on the last name of the first author and the publication year.</p><p>If you want to overwrite an existing reference with a given numerical ID or a given citation key, use the <a class="link" href="re11.html#app-c-command-updateref" title="updateref"><span class="command"><strong>updateref</strong></span></a> command instead.</p></div><div class="simplesect"><div class="titlepage"><div><div><h4 class="title"><a id="idp67108640"></a>Example 1</h4></div></div></div><p>Let's assume we just downloaded a bunch of references from <a class="ulink" href="http://www.ncbi.nlm.nih.gov" target="_top">PubMed</a> (the largest database for biomedical publications). We saved them in the "Medline" format, ending up with several small files containing one or more references each. How do we get them into the database?</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>First we convert all references in the files (we prudently named them <code class="filename">pm001.txt</code>, <code class="filename">pm002.txt</code> and so on) to the RIS format and write the result into an intermediate file, using the <a class="link" href="re16.html" title="med2ris">med2ris.pl</a> input filter:</p><pre class="screen">
<code class="prompt">~# </code>
<strong class="userinput"><code>med2ris.pl -o foo.ris pm*</code></strong>
</pre><p>We could now open <code class="filename">foo.ris</code> in our favourite text editor and make a few changes. We could enter additional keywords, provide personal notes (e.g. why we currently find the article worth the paper it is printed on, something that may not be apparent a few months later), or specify the reprint status and availability.</p></li><li class="listitem"><p>Then we switch to (or start) the refdbc command line client and type the following command at the prompt to add the references to the database <code class="filename">bar</code> (use the full path to <code class="filename">foo.ris</code> if necessary):</p><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>addref -d bar foo.ris</code></strong>
</pre></li></ul></div></div><div class="simplesect"><div class="titlepage"><div><div><h4 class="title"><a id="idp66830864"></a>Example 2</h4></div></div></div><p>You feel the urge to import MODS data, an XML data format developed by the <a class="ulink" href="http://www.loc.gov" target="_top">Library of Congress</a>. RefDB does not support this format natively or via converters at this time, so you'll have to resort to an external tool. Chris Putnam's <a class="ulink" href="http://www.scripps.edu/~cdputnam/software/bibutils/bibutils.html" target="_top">bibutils</a> package comes to the rescue, as it provides a set of command-line tools to interconvert a number of bibliography data formats. Both RIS and MODS are supported, so we have all it takes. The following command imports the MODS data into your default database in a single step, although you may first want to check the output of the converter before going ahead:</p><pre class="screen">
<code class="prompt"># </code><strong class="userinput"><code>xml2ris modsdata.xml|refdbc -C addref</code></strong>
</pre></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect-add-risx-datasets"></a>risx datasets</h3></div></div></div><p>If you prefer the XML data format instead, use the <a class="link" href="re11.html#app-c-command-addref" title="addref"><span class="command"><strong>addref</strong></span></a> with the <code class="option">-A risx</code> switch. As the data are imported using a non-validating XML parser you should make sure the documents are valid, either by using some nifty feature of your XML editor or by running the document through a suitable tool like <span class="command"><strong>xmllint</strong></span>.</p><p>Each entry in a risx document can specify a numerical ID value and an alphanumeric citation key. The ID is ignored by the import routines. If you want to update or replace an entry by ID, you have to use the <a class="link" href="re11.html#app-c-command-updateref" title="updateref"><span class="command"><strong>updateref</strong></span></a> command instead. The citation key should only use letters and numbers within the 7-bit ASCII range. Remember that the citation key has to be all uppercase if you want to create bibliographies for SGML documents. If you do not specify a citation key, RefDB will automatically assign a citation key based on the first author and the publication year.</p><div class="simplesect"><div class="titlepage"><div><div><h4 class="title"><a id="idp66842336"></a>Example</h4></div></div></div><p>You've written a risx dataset from scratch and want to import it into your RefDB database. This is what you need to do:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>First you need to make sure that your document is valid against the risx DTD. Unless your XML editor validates your document anyway, you'll have to use an external validator like <span class="command"><strong>onsgmls</strong></span>, which is a part of the OpenSP suite of SGML tools, or <span class="command"><strong>xmllint</strong></span>, which is shipped with libxml2.</p><pre class="screen">
<code class="prompt">~# </code>
<strong class="userinput"><code>onsgmls -s /usr/local/share/refdb/declarations/xml.dcl foo.xml</code></strong>
<code class="prompt">~# </code>
<strong class="userinput"><code>xmllint --noout --dtdvalid "http://refdb.sourceforge.net/risx/index.html" foo.xml</code></strong>
</pre><p>No news is good news in both cases: If your document is valid, the validator will not output anything. If you do get some error messages, go back to your editor and fix the problems.</p></li><li class="listitem"><p>Now switch to refdbc and run the following command to add the references in <code class="filename">foo.xml</code> to the reference database <code class="filename">bar</code>:</p><pre class="screen">
<code class="prompt">refdbc: </code>
<strong class="userinput"><code>addref -A risx -d bar foo.xml</code></strong>
</pre></li></ul></div></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch07s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt03.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch08s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Input data mangling </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Find and view references</td></tr></table></div></body></html>
|