Thread: [Refdb-cvs] CVS: tutorial refdbtutorial.sgml,1.1.1.1,1.2
Status: Beta
Brought to you by:
mhoenicka
Menu
▾
▴
refdb-cvs
|
From: Markus H. <mho...@us...> - 2004-02-10 23:55:12
|
Update of /cvsroot/refdb/tutorial In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv29637 Modified Files: refdbtutorial.sgml Log Message: updated for 0.9.4 Index: refdbtutorial.sgml =================================================================== RCS file: /cvsroot/refdb/tutorial/refdbtutorial.sgml,v retrieving revision 1.1.1.1 retrieving revision 1.2 diff -u -U2 -r1.1.1.1 -r1.2 --- refdbtutorial.sgml 9 Feb 2004 20:52:24 -0000 1.1.1.1 +++ refdbtutorial.sgml 10 Feb 2004 23:51:31 -0000 1.2 @@ -16,4 +16,8 @@ <revhistory> <revision> + <revnumber>1.1</revnumber> + <date>2004-02-08</date> + </revision> + <revision> <revnumber>1.0</revnumber> <date>2002-11-22</date> @@ -49,12 +53,14 @@ defaultdb refs pager less +toencoding ISO-8859-1 +fromencoding ISO-8859-1 </programlisting> <para>The line starting with the hash sign (#) is a <emphasis>comment</emphasis>. You can add more comment lines if you want to, or leave out the comment line in the example if you remember what that file is good for anyway.</para> <para>If you (or your administrator) don't feel comfortable with storing your password in a plain-text file, you can use an asterisk "*" instead. This will cause the &appname; clients to ask for the password interactively at startup.</para> - <para>Now what does the configuration file <filename moreinfo="none">.&appname;ibrc</filename> look like? Incidentally it is the same, because we don't use any advanced features of these programs yet. You can simply create a copy and name it <filename moreinfo="none">.&appname;ibrc</filename>.</para> + <para>Now what does the configuration file <filename moreinfo="none">.&appname;ibrc</filename> look like? It is the same with the exception of the last line. You can simply create a copy and name it <filename moreinfo="none">.&appname;ibrc</filename>, remove the last line, and you're done.</para> </sect1> </chapter> <chapter> - <title>Managing references</title> + <title>Managing references and notes</title> <para>Now everything is ready to do some real work. We'll go ahead and learn how to use the reference management client.</para> <sect1> @@ -142,11 +148,11 @@ <sect1 id="sect-adding-refs"> <title>Adding references</title> - <para>If you're new to &appname; and don't have a database yet, you'll want to start by adding a couple of references. This chapter first teaches you how to add references in the main input format RIS. The following sections cover the import of data from various data sources like PubMed, BibTeX, or Z39.50 servers.</para> + <para>If you're new to &appname; and don't have a database yet, you'll want to start by adding a couple of references. This chapter first teaches you how to add references in the main input formats RIS and risx. The subsequent sections cover the import of data from various data sources like PubMed, BibTeX, or Z39.50 servers.</para> <tip> <para>If you're really new to &appname; but have access to an existing database, e.g. the one your department built, you might want to get acquainted with &appname; by <link linkend="sect-finding-refs">retrieving existing references</link>. Retrieving references does not alter the database, so this is safe to play around. Once you feel comfortable, return to this section.</para> </tip> <sect2> - <title>Adding RIS datasets</title> - <para>The RIS format is a plain-text tagged file format used by most Windows- and Mac-based reference management tools. This is currently the only reference data format that &appname; understands natively. All other data formats supported by &appname; must be converted to RIS using the conversion tools described in the following sections.</para> + <title>How to create RIS datasets</title> + <para>The RIS format is a plain-text tagged file format used by most Windows- and Mac-based reference management tools. A variety of other data formats supported by &appname; can be converted to RIS using the conversion tools described in the following sections.</para> <sect3> <title>What a RIS dataset looks like</title> @@ -586,138 +592,88 @@ </variablelist> </sect3> - <sect3 id="sect-global-personal-fields"> - <title>Global and personal fields</title> - <para>&appname; differs from other reference management tools because a main goal of its design is to encourage people to share their references. However, you may have figured from the tag list above that some of these entries only make sense if they can be maintained by each user individually. This is precisely the approach used by &appname;: The "hard" bibliographic data are global and identical for each user. The "soft" personal data, which are the only ones likely to change after the reference was added anyway, are maintained for each user individually. These personal fields are:</para> - <itemizedlist> - <listitem> - <para>The reprint status (RP)</para> - </listitem> - <listitem> - <para>The availability field (AV)</para> - </listitem> - <listitem> - <para>The notes field (N1)</para> - </listitem> - </itemizedlist> - <para>Even if you use one of the import filters described below or if you use RIS files exported from other bibliographic software, you should take the time to fill these fields with useful values. If you don't specify values, the AV and N1 field will be blank (this is ok), and the RP field will have the default value "NOT IN FILE".</para> - </sect3> <sect3> - <title>Adding vs. updating references</title> - <para>In most cases you have a new set of references and want to add them to your database. This is no big deal if the data comply with the RIS specification outlined above. Assuming your references are stored in a file <filename moreinfo="none">newrefs.ris</filename> in the present working directory, all you need to do is:</para> - <screen format="linespecific"><prompt moreinfo="none">&appname;c: </prompt><userinput>addref newrefs.ris</userinput></screen> - <para>To simply add the references in the example RIS file, use this command:</para> - <screen format="linespecific"><prompt moreinfo="none">&appname;c: </prompt><userinput>addref /usr/local/share/&appname;/examples/testrefs.ris</userinput></screen> - <para>&appname;c will try to add the references stored in that file to your default database. The diagnostic messages will be displayed in your pager, so if you send a dozen or so references it might take a few seconds until the results are displayed. You'll see a message for each reference found in the input file: Which ID was assigned, which citation key was used (or generated if you didn't specify one), and whether the operation was successful. Adding references usually fails only for two reasons:</para> - <itemizedlist> - <listitem> - <para>The input data didn't contain useful RIS datasets.</para> - </listitem> - <listitem> - <para>A citation key was specified in the reference but the same citation key already exists in the database. &appname; will refuse to accept the reference because citation keys <emphasis>must</emphasis> be unique. You can fix this by changing or deleting the offending citation key in the input file.</para> - </listitem> - </itemizedlist> - <para>Once a reference is added to the database, you might still feel the urge to change it. Be it that you would like to add further keywords or that your personal information, like the reprint status, have changed since. The most straightforward way to change a reference is to retrieve it in RIS format, save it to a file, edit it, and send the updated copy back to where it came from. The following sequence of commands achieves this:</para> - <note> - <para>In this example we'll assume that you already know the ID of the reference that you want to change. You'll learn <link linkend="sect-finding-refs">later</link> how to find a reference by all sorts of criteria like authors, keywords and the like. This section also has additional information on the <command moreinfo="none">getref</command> command used here.</para> - </note> - <screen format="linespecific"> -<prompt moreinfo="none">&appname;c: </prompt><userinput moreinfo="none">getref -t ris -o editme.ris :ID:=7</userinput> -2595 byte written to /usr/home/markus/refdb/editme.ris -<prompt moreinfo="none">&appname;c: </prompt> -</screen> - <para>Now you can use your favourite text editor to change the file <filename moreinfo="none">editme.ris</filename> as you see fit. For this exercise we'll just change the reprint status (the RP field) from "NOT IN FILE" to "IN FILE". When you're done, save the file and go back to &appname;c:</para> - <screen format="linespecific"> -<prompt moreinfo="none">&appname;c: </prompt><userinput moreinfo="none">updateref -P editme.ris</userinput> -Updating set 0 successful -1 dataset(s) updated, 0 added, 0 failed -1 dataset(s) sent. -</screen> - <para>Now what was that <option>-P</option> switch good for? This switch tells &appname; that it should only update your personal information of this reference, i.e. the RP, AV, and N1 fields. This is a lot faster than updating the whole reference. It is also more secure as you might have changed the file somewhere else accidentally without noticing. On the other hand, if you e.g. correct a typo you noticed in the title (TI) field, you <emphasis>must not</emphasis> use the <option>-P</option> switch.</para> - </sect3> - </sect2> - <sect2> - <title>Creating a RIS dataset from scratch</title> - <para>As noted previously, you can use any text editor that creates Unix-style line endings (linefeed) to create and edit RIS files. &appname; ships a ris-mode for Emacs which makes the task a little more pleasant. Ask your administrator whether this mode is available on your system.</para> - <para>Creating a dataset is basically monkey business. The only intelligence required is to use the correct tags for your chunks of bibliographic information. Use the example RIS file as guidelines for the most common reference types journal article, book chapter, and book. We'll look at a few issues related to these references first.</para> - <para>The first issue is certainly the type of the reference. There are pretty clear cases if you look at the list, but there's some bordercases too which are not covered by the predefined types. You should keep in mind that &appname; does not restrict the fields available for a particular reference type. You can fill any available field for any reference type. The only restriction is that the bibliography styles for most reference types use only a subset of the available fields. E.g. a bibliography entry of a journal article will not show a series editor even if you filled in the A3 field, whereas the bibliography entry of a book chapter might show the series editor if the book the chapter is published in is a part of a series.</para> - <para>The general rule is to use the closest matching type, to be consistent in this decision (all similar bordercases should use the same type), and to use the GEN type if nothing else helps. Most bibliography styles display all available fields for the GEN type.</para> - <para>To people new to bibliographic software, the various levels of titles and authors is often confusing. RIS offers three levels of authors:</para> - <variablelist> - <varlistentry> - <term>AU (synonym: A1)</term> - <listitem> - <para>The author of a publication. This is the person (or the persons) responsible for the smallest unit of the publication you're looking at.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>ED (synonym: A2)</term> - <listitem> - <para>The editor of a collection of publications.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>A3</term> - <listitem> - <para>The editor of a series of collections of publications.</para> - </listitem> - </varlistentry> - </variablelist> - <para>Lets consider a few examples. If your reference contains a journal article, published in some scientific journal, the AU fields contain the names of those who wrote the article. The same holds true for the authors of a chapter published in a book like "Methods in Enzymology". The chapter authors would be in the AU fields, the volume editors in the ED field. The editors of the whole "Methods in Enzymology" series of books would be entered in A3 fields. However, if your reference points to one particular volume of "Methods in Enzymology" as a whole, you'd rather put the volume editors in the AU fields. The same logic holds true for the title fields:</para> - <variablelist> - <varlistentry> - <term>TI (synonym: T1)</term> - <listitem> - <para>The title of the smallest unit of publication you're looking at.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>A2</term> - <listitem> - <para>The title of the collection of publications</para> - </listitem> - </varlistentry> + <title>Creating a RIS dataset from scratch</title> + <para>As noted previously, you can use any text editor that creates Unix-style line endings (linefeed) to create and edit RIS files. &appname; ships a ris-mode for Emacs which makes the task a little more pleasant. Ask your administrator whether this mode is available on your system.</para> + <para>Creating a dataset is basically monkey business. The only intelligence required is to use the correct tags for your chunks of bibliographic information. Use the example RIS file as guidelines for the most common reference types journal article, book chapter, and book. We'll look at a few issues related to these references first.</para> + <para>The first issue is certainly the type of the reference. There are pretty clear cases if you look at the list, but there's some bordercases too which are not covered by the predefined types. You should keep in mind that &appname; does not restrict the fields available for a particular reference type. You can fill any available field for any reference type. The only restriction is that the bibliography styles for most reference types use only a subset of the available fields. E.g. a bibliography entry of a journal article will not show a series editor even if you filled in the A3 field, whereas the bibliography entry of a book chapter might show the series editor if the book the chapter is published in is a part of a series.</para> + <para>The general rule is to use the closest matching type, to be consistent in this decision (all similar bordercases should use the same type), and to use the GEN type if nothing else helps. Most bibliography styles display all available fields for the GEN type.</para> + <para>To people new to bibliographic software, the various levels of titles and authors is often confusing. RIS offers three levels of authors:</para> + <variablelist> + <varlistentry> + <term>AU (synonym: A1)</term> + <listitem> + <para>The author of a publication. This is the person (or the persons) responsible for the smallest unit of the publication you're looking at.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ED (synonym: A2)</term> + <listitem> + <para>The editor of a collection of publications.</para> + </listitem> + </varlistentry> <varlistentry> - <term>A3</term> - <listitem> - <para>The title of the series of collections of publications</para> - </listitem> - </varlistentry> - </variablelist> - <para>Using our previous example, an article published in "Methods in Enzymology" might have a TI field "An apparatus to turn urine into gold". The T2 field would be the title of the volume, e.g. "Alchemy and related techniques", whereas the T3 field would contain "Methods in Enzymology". However, if your reference points to the "Alchemy and related techniques" volume as a whole, this title would go into the T1 field.</para> - </sect2> - <sect2 id="sect-retrieve-pubmed"> - <title>Retrieving datasets from PubMed</title> - <para>The primary source of reference data in the biomedical field is the PubMed database maintained by the <ulink url="http://www.ncbi.nlm.nih.gov">National Center for Biotechnology Information</ulink>. This section shows the simplest and most common way to retrieve bibliographic information about interesting articles from this database using a web browser (other methods use web service clients or email subscription services, but this is beyond the scope of this tutorial).</para> - <para>After visiting the site with your favourite web browser, select "PubMed" from the drop-down box called "Search" and type a query in the provided field. Something like "Doe J 2002" to find articles published by J. Doe in 2002. After hitting "Enter" you'll receive a list of publications matching your query. Select the ones you're interested in by clicking the check box right next to the publication (convenience beating logic, you can also check <emphasis>none</emphasis> of the boxes in order to retrieve <emphasis>all</emphasis> publications). Select "XML" from the drop-down box next to the <guibutton moreinfo="none">Display</guibutton> button and hit the latter. You'll receive the list of the publications in the Pubmed XML format. Now click the <guibutton moreinfo="none">Save</guibutton> button on that page and save the information to a plain-text file, e.g. <filename moreinfo="none">pm001.xml</filename>. You could then return to the search, run a few more queries, and save your results in additional files according to this pattern.</para> - <para>We'll use the Perl script <command moreinfo="none">med2ris.pl</command> to turn our XML data into RIS data. This tool either reads Pubmed data from standard input or from files specified as arguments. The result will be sent to standard output, so you can either view it with a pager or write it to a file.</para> - <screen format="linespecific"><prompt moreinfo="none">~$ </prompt><userinput moreinfo="none">med2ris.pl < pm001.xml | less</userinput></screen> - <para>This command converts the data in the file <filename moreinfo="none">pm001.xml</filename> and displays the result in a pager.</para> - <screen format="linespecific"><prompt moreinfo="none">~$ </prompt><userinput moreinfo="none">med2ris.pl pm*.xml > pm.ris</userinput></screen> - <para>This command converts all files that match the pattern <filename moreinfo="none">pm*.xml</filename>, like <filename moreinfo="none">pm001.xml</filename> or <filename moreinfo="none">pmnew.xml</filename>, and writes the resulting RIS datasets to <filename moreinfo="none">pm.ris</filename>.</para> - <para>Now you should add your personal information to each dataset, as outlined <link linkend="sect-global-personal-fields">above</link>. Then you could go ahead and add the references to your default database with &appname;c:</para> - <screen format="linespecific"><prompt moreinfo="none">&appname;c: </prompt>addref pm.ris</screen> - </sect2> - <sect2> - <title>Importing BibTeX datasets</title> - <para>If you have a BibTeX database that you want to import into &appname;, you'll have to convert these data to RIS first. This is again best done by using one of the converters shipped with &appname;. The tool <command moreinfo="none">bib2ris</command> will by default convert all standard BibTeX fields to the RIS equivalents. If you used non-standard fields in your BibTeX database, <command moreinfo="none">bib2ris</command> can be configured to import these too, but this requires additional entries in the <filename moreinfo="none">~/.bib2risrc</filename> configuration file. The manual has all the details, but for the purposes of this tutorial we'll assume that you only use an "ABSTRACT" field as the only additional non-standard field.</para> - <para>Just like &appname;c, bib2ris reads configuration files at startup which you can modify to permanently set some defaults. The syntax of the configuration file is the same as outlined <link linkend="sect-config-files">above</link>, but the only line we have to enter at this time is the following:</para> - <programlisting format="linespecific"> + <term>A3</term> + <listitem> + <para>The editor of a series of collections of publications.</para> + </listitem> + </varlistentry> + </variablelist> + <para>Lets consider a few examples. If your reference contains a journal article, published in some scientific journal, the AU fields contain the names of those who wrote the article. The same holds true for the authors of a chapter published in a book like "Methods in Enzymology". The chapter authors would be in the AU fields, the volume editors in the ED field. The editors of the whole "Methods in Enzymology" series of books would be entered in A3 fields. However, if your reference points to one particular volume of "Methods in Enzymology" as a whole, you'd rather put the volume editors in the AU fields. The same logic holds true for the title fields:</para> + <variablelist> + <varlistentry> + <term>TI (synonym: T1)</term> + <listitem> + <para>The title of the smallest unit of publication you're looking at.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>A2</term> + <listitem> + <para>The title of the collection of publications</para> + </listitem> + </varlistentry> + <varlistentry> + <term>A3</term> + <listitem> + <para>The title of the series of collections of publications</para> + </listitem> + </varlistentry> + </variablelist> + <para>Using our previous example, an article published in "Methods in Enzymology" might have a TI field "An apparatus to turn urine into gold". The T2 field would be the title of the volume, e.g. "Alchemy and related techniques", whereas the T3 field would contain "Methods in Enzymology". However, if your reference points to the "Alchemy and related techniques" volume as a whole, this title would go into the T1 field.</para> + </sect3> + <sect3 id="sect-retrieve-pubmed"> + <title>Retrieving datasets from PubMed</title> + <para>The primary source of reference data in the biomedical field is the PubMed database maintained by the <ulink url="http://www.ncbi.nlm.nih.gov">National Center for Biotechnology Information</ulink>. This section shows the simplest and most common way to retrieve bibliographic information about interesting articles from this database using a web browser (other methods use web service clients or email subscription services, but this is beyond the scope of this tutorial).</para> + <para>After visiting the site with your favourite web browser, select "PubMed" from the drop-down box called "Search" and type a query in the provided field. Something like "Doe J 2002" to find articles published by J. Doe in 2002. After hitting "Enter" you'll receive a list of publications matching your query. Select the ones you're interested in by clicking the check box right next to the publication (convenience beating logic, you can also check <emphasis>none</emphasis> of the boxes in order to retrieve <emphasis>all</emphasis> publications). Select "XML" from the drop-down box next to the <guibutton moreinfo="none">Display</guibutton> button and hit the latter. You'll receive the list of the publications in the Pubmed XML format. Now click the <guibutton moreinfo="none">Save</guibutton> button on that page and save the information to a plain-text file, e.g. <filename moreinfo="none">pm001.xml</filename>. You could then return to the search, run a few more queries, and save your results in additional files according to this pattern.</para> + <para>We'll use the Perl script <command moreinfo="none">med2ris.pl</command> to turn our XML data into RIS data. This tool either reads Pubmed data from standard input or from files specified as arguments. The result will be sent to standard output, so you can either view it with a pager or write it to a file.</para> + <screen format="linespecific"><prompt moreinfo="none">~$ </prompt><userinput moreinfo="none">med2ris.pl < pm001.xml | less</userinput></screen> + <para>This command converts the data in the file <filename moreinfo="none">pm001.xml</filename> and displays the result in a pager.</para> + <screen format="linespecific"><prompt moreinfo="none">~$ </prompt><userinput moreinfo="none">med2ris.pl pm*.xml > pm.ris</userinput></screen> + <para>This command converts all files that match the pattern <filename moreinfo="none">pm*.xml</filename>, like <filename moreinfo="none">pm001.xml</filename> or <filename moreinfo="none">pmnew.xml</filename>, and writes the resulting RIS datasets to <filename moreinfo="none">pm.ris</filename>.</para> + <para>Now you should add your personal information to each dataset, as outlined <link linkend="sect-global-personal-fields">above</link>. Then you could go ahead and add the references to your default database with &appname;c:</para> + <screen format="linespecific"><prompt moreinfo="none">&appname;c: </prompt>addref pm.ris</screen> + </sect3> + <sect3> + <title>Importing BibTeX datasets</title> + <para>If you have a BibTeX database that you want to import into &appname;, you'll have to convert these data to RIS first. This is again best done by using one of the converters shipped with &appname;. The tool <command moreinfo="none">bib2ris</command> will by default convert all standard BibTeX fields to the RIS equivalents. If you used non-standard fields in your BibTeX database, <command moreinfo="none">bib2ris</command> can be configured to import these too, but this requires additional entries in the <filename moreinfo="none">~/.bib2risrc</filename> configuration file. The manual has all the details, but for the purposes of this tutorial we'll assume that you only use an "ABSTRACT" field as the only additional non-standard field.</para> + <para>Just like &appname;c, bib2ris reads configuration files at startup which you can modify to permanently set some defaults. The syntax of the configuration file is the same as outlined <link linkend="sect-config-files">above</link>, but the only line we have to enter at this time is the following:</para> + <programlisting format="linespecific"> nsf_abstract N2 -</programlisting> - <para>This will tell bib2ris to import your non-standard abstract field (this is case-insensitive, so your BibTeX file might use ABSTRACT or Abstract as well) into the N2 RIS field. Use the following command to see the results:</para> - <screen><prompt>~$ </prompt>bib2ris < myrefs.bib | less</screen> - <para>This command will convert the contents of <filename>myrefs.bib</filename> in the current directory and display the result in a pager.</para> - <screen><prompt>~$ </prompt>bib2ris *.bib > myrefs.ris</screen> - <para>This command reads the data from all <filename>*.bib</filename> files in the current directory and redirects the output into the file <filename>myrefs.ris</filename>.</para> - <para>Now there is a little issue with the data generated by bib2ris: they still contain all TeX markup that you may have used in your input data. If you want to use &appname; only to maintain references for LaTeX files, this is probably ok, but if you want to use the data for SGML and XML documents too, it is necessary to strip the TeX markup before adding the references to the database. To this end, run the RIS file through the Perl script <command moreinfo="none">tex2mail</command> shipped with &appname;.</para> - <screen><prompt>~$ </prompt>tex2mail -noindent -ragged -linelength 65535 -ris < myrefs.ris > myrefs-notex.ris</screen> - <para>As described in the <link linkend="sect-retrieve-pubmed">previous section</link>, you should now add your personal information and then use &appname;c to add the datasets to your database.</para> - </sect2> - <sect2> - <title>Retrieving datasets from a Z39.50 server</title> - <para>Many libraries allow remote access to their electronic catalogs via the Z39.50 protocol. With a suitable client you can search the catalogs and retrieve the bibliographic information of interesting references to your local computer. For this tutorial we'll use the free client provided in the <ulink url="http://www.indexdata.dk/yaz/">YAZ toolkit</ulink>, although you could use any other client as well. One of the largest libraries accessible via the Z39.50 protocol is the <ulink url="http://www.loc.gov">Library of Congress</ulink>. We'll try to find computer books written by some Mr. Knuth in this library.</para> - <para>The following command connects to the library using the host name "z3950.loc.gov", the port 7090, and the database name "Voyager". All this information is usually provided either online or in a printed pamphlet about electronic catalog access published by libraries offering Z39.50 services:</para> - <screen format="linespecific"> -<prompt>~$ </prompt><userinput>yaz-client z3950.loc.gov:7090/Voyager</userinput> + </programlisting> + <para>This will tell bib2ris to import your non-standard abstract field (this is case-insensitive, so your BibTeX file might use ABSTRACT or Abstract as well) into the N2 RIS field. Use the following command to see the results:</para> + <screen><prompt>~$ </prompt>bib2ris < myrefs.bib | less</screen> + <para>This command will convert the contents of <filename>myrefs.bib</filename> in the current directory and display the result in a pager.</para> + <screen><prompt>~$ </prompt>bib2ris *.bib > myrefs.ris</screen> + <para>This command reads the data from all <filename>*.bib</filename> files in the current directory and redirects the output into the file <filename>myrefs.ris</filename>.</para> + <para>Now there is a little issue with the data generated by bib2ris: they still contain all TeX markup that you may have used in your input data. If you want to use &appname; only to maintain references for LaTeX files, this is probably ok, but if you want to use the data for SGML and XML documents too, it is necessary to strip the TeX markup before adding the references to the database. To thi... [truncated message content] |
Thanks for helping keep SourceForge clean.
X