/usr/share/doc/refdb/refdb-manual/ch10s03.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 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | <?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>Create SGML and XML bibliographies</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="ch10.html" title="Chapter 10. Bibliographies" /><link rel="prev" href="ch10s02.html" title="Manage bibliography styles" /><link rel="next" href="ch10s04.html" title="Create LaTeX/BibTeX bibliographies" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Create SGML and XML bibliographies</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch10s02.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Bibliographies</th><td width="20%" align="right"> <a accesskey="n" href="ch10s04.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect-create-xml-bibliographies"></a>Create SGML and XML bibliographies</h2></div></div></div><p>Although SGML documents are usually processed with a DSSSL toolchain and XML documents with a XML toolchain, the procedures to generate documents with bibliographies are similar enough to treat them in a single section. If you use the high-level tools provided by RefDB, you won't even notice a difference.</p><p>RefDB can create two types of bibliographies, cooked and raw. Cooked bibliographies are already preformatted using the information of a particular bibliography and citation style. Documents using cooked bibliographies have to be processed using the appropriate stylesheet driver files provided by RefDB. Raw bibliographies (currently supported only for XML documents) contain no particular formatting and should therefore be processed using the regular DocBook or TEI stylesheets.</p><p>RefDB provides both high-level tools which attempt to hide the entire complexity of the bibliography business, and low-level tools which allow experienced users to integrate RefDB into their own toolchains. We'll first describe the high-level approach which should always be the first choice. The subsequent sections give all the details about the low-level tools which you normally don't even want to know about.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect-refdbnd-shortcut"></a>Keeping it simple with refdbnd</h3></div></div></div><p><a class="link" href="re21.html" title="refdbnd">refdbnd</a> provides the simplest approach to create, maintain, and transform documents with RefDB bibliographies. Once set up, all you'll have to do is to run something as simple as <span class="command"><strong>make pdf</strong></span>. The following subsections cover how to set up a refdbnd-managed project, how to cite, and how to process the document.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-setup-refdbnd-project"></a>Setting up a project</h4></div></div></div><p><a class="link" href="re21.html" title="refdbnd">refdbnd</a> is an interactive script which creates a skeleton document and a custom-tailored <code class="filename">Makefile</code>. Start the script in a clean subdirectory by typing <span class="command"><strong>refdbnd</strong></span>. You'll be asked a couple of questions, each of which supplies sufficient background information for novice users. The script will then create three files (we'll assume that the basename that you provided was "foo"):</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">foo.short.[sgml|xml]</span></dt><dd><p>The ".short" reminds you that you're supposed to use the <a class="link" href="ch10s03.html#sect-edit-refdbnd-project" title="Editing your document">short notation</a> for citations in this file. This is simpler, usually more convenient, and should always be your first choice.</p></dd><dt><span class="term">foo.[sgml|xml]</span></dt><dd><p>This file is just a dummy in a fresh project. If you edit the file <code class="filename">foo.short.xml</code>, the file <code class="filename">foo.xml</code> will automatically be updated and fed to the subsequent processing steps next time you run <span class="command"><strong>make</strong></span>. Unless you know what you do, you don't want to touch this file.</p></dd><dt><span class="term">Makefile</span></dt><dd><p>This is a customized Makefile that contains all the information that you provided to <a class="link" href="re21.html" title="refdbnd">refdbnd</a>. Simply run commands like <span class="command"><strong>make pdf</strong></span> or <span class="command"><strong>make html</strong></span> to create printable or HTML output with formatted citations and bibliographies from your document.</p></dd></dl></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-edit-refdbnd-project"></a>Editing your document</h4></div></div></div><p>The <code class="filename">foo.short[sgml|xml]</code> skeleton document contains the required markup to start a book or an article. You'll now want to open this file in your favourite text editor to write the contents and to add your citations. In DocBook SGML and XML documents, citations are encoded as <code class="sgmltag-element">citation</code> elements. To distinguish these from <code class="sgmltag-element">citation</code> elements that are not meant to be processed by RefDB, set the <code class="sgmltag-attribute">role</code> attribute to <code class="sgmltag-attvalue">REFDB</code> in all caps. Each <code class="sgmltag-element">citation</code> element contains one or more references, separated by semicolons. The trailing semicolon after the last reference is optional, so the following citations are absolutely equivalent:</p><pre class="programlisting"><citation role="REFDB">2;5;9</citation>
<citation role="REFDB">2;5;9;</citation>
</pre><p>The values identifiy the bibliographic entries in your database. Use either numerical IDs as in the examples above, or alphanumeric citation keys as shown in the following example:</p><pre class="programlisting"><citation role="REFDB">Miller1999;Jones2001</citation>
</pre><p>The corresponding syntax for TEI XML documents is quite similar, except that we abuse the general-purpose <code class="sgmltag-element">seg</code> element and tag it for use with RefDB by setting the <code class="sgmltag-attribute">type</code> to <code class="sgmltag-attvalue">REFDBCITATION</code> in all caps:</p><pre class="programlisting"><seg type="REFDBCITATION">2;5;9</seg>
</pre><p>Again, you can use citation keys instead of the numerical IDs shown in the example above.</p><p>The examples shown above will be rendered as "regular" citations. In addition to this you can request author-only or year-only citations. These come in handy if you want to write something like: Jones et al. reported recently (2001)... Both the authors (Jones et al.) and the year (2001) need to be encoded as individual citations as shown in the following example:</p><pre class="programlisting"><para><citation role="REFDB">A:Jones2001</citation> reported
recently <citation role="REFDB">Y:Jones2001</citation> ...</para>
</pre><p>You may have guessed that the prefix "A:" tags a citation as an author-only citation and that the prefix "Y:" means year-only.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>These prefixes tag the whole citation, not a particular reference in the citation. Therefore the prefix must be the first thing right after the start tag. Multiple citations using the author-only or year-only style would make no sense anyway.</p></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-transform-refdbnd-project"></a>Transforming your document</h4></div></div></div><p>The Makefiles created by refdbnd offer the following targets:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">pdf</span></dt><dd><p>This target generates a PDF file from your source document. PDF is a widely accepted document format with free viewers for essentially all current operating systems. Be aware that not all FO processors (used in transforming XML documents) offer PDF output.</p></dd><dt><span class="term">html</span></dt><dd><p>This runs all required commands to create HTML output, viewable with any web browser. Depending on your local setup, the output will be chunked into a collection of HTML files.</p></dd><dt><span class="term">rtf</span></dt><dd><p>This target generates a Rich Text Format (RTF) file. This plain text format is sort of a word processor interchange format understood by most current word processors, including MS Word, WordPerfect, and OpenOffice/StarOffice. Not all FO processors offer RTF output though.</p></dd><dt><span class="term">ps</span></dt><dd><p>This target is only available for SGML documents. It will create a Postscript document from your source. Postscript is the universal document format on Unix systems and can be printed directly on Postscript printers. Viewers are available for all current operating systems.</p></dd></dl></div><p>The Makefile also offers a few more targets. For each of the above targets there is a corresponding '<target>dist' target which creates a <code class="filename">.tar.gz</code> archive of the output document, along with its associated CSS stylesheet if applicable. The target 'all', which is also the default if you don't specify a target to <span class="command"><strong>make</strong></span>, builds all available output formats. Accordingly, the target 'dist' creates all archives. And finally, the target 'clean' removes all intermediate files and returns your directory to the original state.</p><p>The refdbnd-generated Makefiles should be sufficient for the average document. However, feel free to modify them in order to adapt them to specific needs. For example you can specify a different style in order to switch your output to a different citation and bibliography style. <span class="command"><strong>make</strong></span> also allows you to override variable settings on the command line. E.g. if you want to output your document using a different bibliography style without making it the permanent default, invoke <span class="command"><strong>make</strong></span> like this:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>make clean && make pdf stylename="Eur.J.Pharmacol."</code></strong>
</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><span class="command"><strong>make clean</strong></span> removes intermediate files to let the change of the bibliography style take effect.</p></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect-low-level-bibliographies"></a>Bibliographies, the hard way</h3></div></div></div><p>If the simple approach outlined above does not suit your needs, you can turn to the low-level bibliography tools provided by RefDB. Needless to say, you can always start with a refdbnd-created project and use the low-level tools whenever you run into any limitations. However, this section describes the manual creation and transformation of documents from the ground up.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-prepare-doc"></a>Prepare the document</h4></div></div></div><p>RefDB's bibliography output is a <code class="sgmltag-element">bibliography</code> element that contains all required references. You can redirect the output into a file and include this file at the spot where your bibliography should appear. To achieve this you need two modifications in your document:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>When using DTD-based documents (i.e. DocBook 4.x or TEI P4), extend the document type declaration at the beginning of your document to declare the external entity. The first example is from a DocBook SGML document:</p><pre class="programlisting"><!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY bibliography "foo.bib.sgml">
]>
...
</pre><p>The second example shows a TEI XML document:</p><pre class="programlisting"><?xml version="1.0"?>
<!DOCTYPE TEI.2 PUBLIC "-//TEI P4//DTD Main Document Type//EN" "http://www.tei-c.org/P4X/DTD/tei2.dtd" [
<!ENTITY % TEI.general 'INCLUDE'>
<!ENTITY % TEI.names.dates 'INCLUDE'>
<!ENTITY % TEI.linking 'INCLUDE'>
<!ENTITY % TEI.XML 'INCLUDE'>
<!ENTITY bibliography SYSTEM "refdbtest.bib.xml">
]>
...
</pre><p>The name of the entity is of course yours to choose, but using <span class="quote">“<span class="quote">bibliography</span>”</span> as in this example is pretty descriptive.</p><p>When using schema-based documents (i.e. DocBook 5.x or TEI P5), there is no need to declare the bibliography at the beginning of the document.</p></li><li class="listitem"><p>Include the bibliography at the desired spot as an external entity for DTD-based documents:</p><pre class="programlisting">...
&bibliography;
...
</pre><p>Alternatively, use xinclude to include the bibliography in schema-based documents:</p><pre class="programlisting">...
<xi:include href="refdbtest.bib.xml"
xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:fallback>refdbtest.bib.xml appears to be missing</xi:fallback>
</xi:include>
</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Some XSLT processors require a command-line switch or additional libraries to support xincludes. If your transformed document should lack the bibliographic listing, consult the documentation of your XSLT processor.</p></div><p>You need to make sure that the included chunk of text is valid at the point where you want to include it. DocBook SGML and XML bibliographies are generated as <code class="sgmltag-element">bibliography</code> elements, TEI XML bibliographies are wrapped in <code class="sgmltag-element">div</code> elements.</p></li></ol></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect3-create-citations"></a>Create citations</h4></div></div></div><p>Creating citations and bibliographies in SGML or XML documents with RefDB is very similar to what you would do if you had to manually code the bibliographies - but without the sweat. First you create the citations. Each citation consists of one or more bibliographic references in the text, each of which points to one particular entry in the bibliography. Then you create a bibliography for all cited publications (and possibly some more). For an increased benefit you would certainly also want to create functional links from the citations to the corresponding bibliography entries, which would act as hyperlinks in suitable output formats like HTML or PDF. In real life, you would probably jump back and forth, adding a bibliography entry whenever you add a new citation, and invent suitable ID values for your bibliographic link targets as needed.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The distinction made here between a citation and a bibliographical reference may sound like nitpicking, but it will be important when we deal with citations that contain more than one bibliographical reference.</p></div><p>RefDB requires a slightly more formalized approach. You have to stick to a particular syntax when you create the citations, but the good news is that RefDB does almost all of the rest. You will usually also create the citations first and let RefDB create the bibliography just before you are ready to transform the first draft.</p><p>RefDB uses three different notations for references:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Short notation</span></dt><dd><p>The short notation is, as the name implies, a lot faster to type and thus more convenient, but it requires an additional preprocessing step that adds some small restrictions to the way you write your documents (please see the section about <a class="link" href="re27.html" title="refdbxp">refdbxp</a> for details about these restrictions). The preprocessing of documents using the short notation also automates the issue of first and subsequent citations of a bibliographic entry and it automatically creates the ID values used in multiple citations. Using multiple databases per document is not supported by the short notation currently.</p><p>The short notation is fully valid SGML or XML code, without any extensions of the original DTDs. You can use all sorts of SGML or XML processing tools on such documents.</p></dd><dt><span class="term">Full notation</span></dt><dd><p>The full notation offers full control but requires a lot more typing and thinking. It does not require a preprocessing step before the transformation, though. You need to take care of the issue of first and subsequent citations of a reference, and you have to manually generate ID values for use in multiple citations. You can include references taken from several databases.</p><p>Just like the short notation, the full notation is also fully valid SGML or XML code, without any extensions of the original DTDs.</p></dd><dt><span class="term">ID notation for raw bibliographies</span></dt><dd><p>If you want to process your document with the default Docbook or TEI stylesheets using a raw bibliography, you just use the citation key as te value of the <code class="sgmltag-attribute">linkend</code> attribute of the <code class="sgmltag-element">xref</code> or <code class="sgmltag-element">biblioref</code> elements to refer to the appropriate reference entry in the bibliography. RefDB will generate the bibliography using the citation key as the <code class="sgmltag-attribute">id</code> or <code class="sgmltag-attribute">xml:id</code> (for DocBook 5.x and TEI P5) attribute.</p></dd></dl></div><p>First we'll have a look at the short notation, before we get into the gruesome details of the full notation. Keep in mind that the <a class="link" href="re27.html" title="refdbxp">refdbxp</a> application interconverts the short and the full notation. You can convert your document back and forth as often as you wish, so you're not limited to the notation that you initially choose. In fact, you can mix both notations in a single document. Finally, we'll also show examples of the ID notation for raw bibliographies.</p><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="sect-short-notation"></a>Short notation</h5></div></div></div><p>The short notation has been described <a class="link" href="ch10s03.html#sect-edit-refdbnd-project" title="Editing your document">above</a> as this is the notation which you use in refdbnd-maintained projects. The only thing you must not forget when not using refdbnd is that you <span class="emphasis"><em>must</em></span> preprocess documents that contain citations in short notation with <a class="link" href="re27.html" title="refdbxp">refdbxp</a> before you transform the document to one of the output formats.</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="sect-full-notation"></a>Full notation</h5></div></div></div><p>The full notation is a lot more complex than the simple notation described above. So unless you have specific reasons to write citations in full notation from scratch, it is more advisable to use the short notation and preprocess your documents with <a class="link" href="re27.html" title="refdbxp">refdbxp</a>. The output created by this utility is the full notation described in this section.</p><p>The particular syntax of citations and bibliographic references is necessary for two reasons: first we have to tell RefDB which bibliographic database entry (and probably, from which database) we want to reference. Second, we need to encode which type of citation or reference we want. The exact markup depends on the DTD that your document uses, but the basics are the same.</p><p>In both DocBook and TEI documents, these two bits of information are encoded in attributes of elements that create a link from the reference to the bibliographic entry. In order to handle multiple citations correctly, these link elements need to be inside a wrapper element. For a DocBook document, basic citations therefore look like this:</p><pre class="programlisting"><citation role="REFDB"> <a id="list1-citation"></a><span><img src="images/callouts/1.png" alt="1" border="0" /></span>
<xref linkend="ID1-X"> <a id="list1-xref"></a><span><img src="images/callouts/2.png" alt="2" border="0" /></span>
</citation>
<citation role="REFDB">
<xref linkend="LITIBP-ID2-X"> <a id="list1-xref2"></a><span><img src="images/callouts/3.png" alt="3" border="0" /></span>
</citation>
</pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#list1-citation"><span><img src="images/callouts/1.png" alt="1" border="0" /></span></a> </p></td><td valign="top" align="left"><p>The <code class="sgmltag-element">citation</code> element is a wrapper for one or more bibliographic references. The <code class="sgmltag-attribute">role</code> attribute is set to <code class="sgmltag-attvalue">REFDB</code> to distinguish this <code class="sgmltag-element">citation</code> from other <code class="sgmltag-element">citation</code> elements that RefDB should leave alone. Each <code class="sgmltag-element">citation</code> element can contain one or more <code class="sgmltag-element">xref</code> elements.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#list1-xref"><span><img src="images/callouts/2.png" alt="2" border="0" /></span></a> </p></td><td valign="top" align="left"><p>Each <code class="sgmltag-element">xref</code> element specifies one bibliographic reference. The value of the <code class="sgmltag-attribute">linkend</code> attribute encodes which bibliographic item is referenced (in this case, the database entry with the ID 1) and how the reference should be rendered (see below). It consists of the string "ID" followed by the numerical database entry ID, and a trailing one-letter type specifier ("X" in this case), separated from the rest by a dash. This simple form does not encode the database from which the reference is to be pulled. When generating the bibliography, you will specify a default database from which all references without an explicit database label will be taken from. This form is most convenient if all your bibliographic items are stored in one database.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#list1-xref2"><span><img src="images/callouts/3.png" alt="3" border="0" /></span></a> </p></td><td valign="top" align="left"><p>This <code class="sgmltag-element">xref</code> element shows the syntax when an explicit database (LITIBP in this case) is specified. The attribute value consists of the database name, a dash, the string "ID", the numerical database entry ID, and the trailing type specifier. This form is mandatory only if you reference bibliographic entries from different databases in the same document (again, one database can be set as the default database in subsequent processing steps, so you could use the simple form for all references to entries in that particular database).</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This and the following DocBook examples are given in SGML notation. Keep in mind two things when working with XML documents:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The empty <code class="sgmltag-element">xref</code> elements need a closing slash as in <xref linkend="ID2-X"/>.</p></li><li class="listitem"><p>All attribute values relevant to RefDB must be in uppercase. This restriction is imposed by the way citations are currently extracted from the document. It may be dropped in later versions though.</p></li></ul></div></div><p>The corresponding syntax in a TEI XML document looks like this:</p><pre class="programlisting"><seg type="REFDBCITATION"> <a id="list2-citation"></a><span><img src="images/callouts/1.png" alt="1" border="0" /></span>
<ptr targOrder="U" target="ID1-X" TEIform="ptr"/> <a id="list2-xref"></a><span><img src="images/callouts/2.png" alt="2" border="0" /></span>
</seg>
<seg type="REFDBCITATION">
<ptr targOrder="U" target="LITIBP-ID2-X" TEIform="ptr"/><a id="list2-xref2"></a><span><img src="images/callouts/3.png" alt="3" border="0" /></span>
</seg>
</pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#list2-citation"><span><img src="images/callouts/1.png" alt="1" border="0" /></span></a> </p></td><td valign="top" align="left"><p>The general-purpose <code class="sgmltag-element">seg</code> element with the <code class="sgmltag-attribute">type</code> attribute set to <code class="sgmltag-attvalue">REFDBCITATION</code> is the citation wrapper for one or more bibliographic references.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#list2-xref"><span><img src="images/callouts/2.png" alt="2" border="0" /></span></a> </p></td><td valign="top" align="left"><p>Each bibliographic reference is specified by a <code class="sgmltag-element">ptr</code> element whose <code class="sgmltag-attribute">target</code> attribute encodes the bibliographic entry that is referenced. As explained in the DocBook example, this is the simple form that does not specify the database.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#list2-xref2"><span><img src="images/callouts/3.png" alt="3" border="0" /></span></a> </p></td><td valign="top" align="left"><p>This is the corresponding bibliographic reference with the database specified.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You don't have to worry about the attributes in the example which are not mentioned in the explanations. These are TEI default attributes which do not have anything to do with RefDB (your XML editor will most likely create them automatically for you).</p></div><p>There are several ways to render citations and bibliographic references in the text. You select what you need by a trailing capital letter after the database ID (the "X" in the above examples). RefDB will create several preformatted strings in the bibliography file which can be linked to by selecting the proper postfix. These preformatted strings have several purposes, as shown in the following <a class="link" href="ch10s03.html#table-biblio-reference-types" title="Table 10.1. Bibliographic reference types">table</a>:</p><div class="table"><a id="table-biblio-reference-types"></a><p class="title"><strong>Table 10.1. Bibliographic reference types</strong></p><div class="table-contents"><table summary="Bibliographic reference types" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Postfix</th><th>Purpose</th></tr></thead><tbody><tr><td>X</td><td>The most common case. This is the first occurrence of a reference which is to be displayed outside the flow of the text. In numerical citation schemes this will be something like "(2)", in author-year citation schemes this may be rendered as "(Miller et al., 1992)".</td></tr><tr><td>S</td><td>This is the same as X, but for a subsequent occurrence of the same reference. This distinction is important for some author-year citation schemes that print the full (or at least a longer) author list at the first occurrence and an abbreviated one at all subsequent occurrences of the same reference.</td></tr><tr><td>A</td><td>This is the first occurrence of a reference that displays the authorlist inside the flow of the text, like in "Miller et al. reported recently (2001)...".</td></tr><tr><td>Q</td><td>This is the same as A, but for subsequent occurrences of the same reference.</td></tr><tr><td>Y</td><td>This type complements the author-only references mentioned above. In numerical citation schemes this is usually rendered like a normal reference, e.g. as "(2)", but in author-year citation schemes usually only the publication date is rendered, as in "(2001)".</td></tr></tbody></table></div></div><br class="table-break" /><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The exact formatting of these references, e.g. which citation style is used or which brackets surround the reference, is controlled by the style specification for a particular publication or publisher. This takes effect when you generate the bibliography and transform the final document.</p></div><p>An additional twist comes into play if you have multiple citations, i.e. a citation that contains more than one bibliographic reference. In most cases, all references are displayed inside of one pair of brackets. Some numerical citation styles require that bibliographic references with consecutive numbers be formatted as ranges within the same citation.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Formatting consecutive numbers as ranges kills the links from the reference to the bibliographic item for each reference that make up a range. Any generated hyperlinks will therefore point to one common target for all members of a multiple citation. If this is not desired (e.g. to keep the links alive in a HTML presenation of a scientific document), you may override this behaviour during the transformation of the final document.</p></div><p>In order to format these cases properly, you need to include a dummy element whose sole purpose is to provide a link to an element that contains the combined, preformatted citation string. This is shown for a DocBook document in the following example.</p><pre class="programlisting"><citation role="REFDB">
<xref endterm="IMTHEFIRST" linkend="ID1" role="MULTIXREF"><a id="list3-multixref"></a><span><img src="images/callouts/1.png" alt="1" border="0" /></span>
<xref linkend="ID1-X"> <a id="list3-xref"></a><span><img src="images/callouts/2.png" alt="2" border="0" /></span>
<xref linkend="ID14-X">
<xref linkend="ID7-X">
</citation>
</pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#list3-multixref"><span><img src="images/callouts/1.png" alt="1" border="0" /></span></a> </p></td><td valign="top" align="left"><p>This is the additional <code class="sgmltag-element">xref</code> element which is mandatory in multiple citations. The <code class="sgmltag-attribute">linkend</code> specifies the target of a link, which by convention could be the first of the following references. Note that the attribute value does not have a trailing type specifier. The element must have a <code class="sgmltag-attribute">role</code> attribute with the value <code class="sgmltag-attvalue">MULTIXREF</code>. You also have to provide an unique value for the <code class="sgmltag-attribute">endterm</code> attribute. This specifies the ID value that will be used in the corresponding element in the RefDB-generated bibliography that contains the preformatted string for the multiple citation. The ID value has to start with the letters "IM" as a sort of sanity check.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#list3-xref"><span><img src="images/callouts/2.png" alt="2" border="0" /></span></a> </p></td><td valign="top" align="left"><p>This and the following <code class="sgmltag-element">xref</code> elements define the actual references that comprise the multiple citation.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The sequence of the <code class="sgmltag-element">xref</code> elements that encode the actual references <span class="emphasis"><em>may</em></span> be important. Depending on the bibliography style used for the document transformation, the references may be displayed in the sequence as they were entered, or they may be rearranged according to the sequence of the bibliographic entries in the finished bibliography.</p><p>Keep also in mind that all attribute values must be in uppercase for the same reasons as stated above.</p></div><p>The corresponding TEI citation is a little bit simpler:</p><pre class="programlisting"><seg type="REFDBCITATION">
<ptr type="MULTIXREF" targOrder="U" target="IMTHEFIRST" TEIform="ptr"/><a id="list4-multixref"></a><span><img src="images/callouts/1.png" alt="1" border="0" /></span>
<ptr targOrder="U" target="ID1-X" TEIform="ptr"/> <a id="list4-xref"></a><span><img src="images/callouts/2.png" alt="2" border="0" /></span>
<ptr targOrder="U" target="LITIBP-ID21-X" TEIform="ptr"/>
<ptr targOrder="U" target="ID5-X" TEIform="ptr"/>
</seg>
</pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#list4-multixref"><span><img src="images/callouts/1.png" alt="1" border="0" /></span></a> </p></td><td valign="top" align="left"><p>This is the additional <code class="sgmltag-element">ptr</code> element which is mandatory in multiple citations. The element must have a <code class="sgmltag-attribute">type</code> attribute with the value <code class="sgmltag-attvalue">MULTIXREF</code>. You also have to provide an unique value for the <code class="sgmltag-attribute">target</code> attribute. This specifies the ID value that will be used in the corresponding element in the RefDB-generated bibliography. The ID string has to start with "IM". In contrast to DocBook elements, there is no way to specify where a link should point to. The RefDB XSL stylesheets will use the first bibliographic entry referenced in a multiple citation as the link target.</p></td></tr><tr><td width="5%" valign="top" align="left"><p><a href="#list4-xref"><span><img src="images/callouts/2.png" alt="2" border="0" /></span></a> </p></td><td valign="top" align="left"><p>This and the following <code class="sgmltag-element">xref</code> elements define the actual references that comprise the multiple citation.</p></td></tr></table></div></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="sect-raw-notation"></a>ID notation for raw bibliographies</h5></div></div></div><p>This notation is similar to what you'd do in a document which does not use RefDB bibliographies at all, except that you have to declare which <code class="sgmltag-element">citation</code> elements should be processed by RefDB (it may very well be that RefDB is supposed to process all of these elements, but in order to support cases where it shouldn't, there is a mechanism to allow just this). Just set the <code class="sgmltag-attribute">role</code> attribute of the <code class="sgmltag-element">citation</code> element to <code class="sgmltag-attvalue">REFDB</code> to include it in the list of citations that <a class="link" href="re22.html" title="runbib">runbib</a> extracts from your document, like this:</p><pre class="programlisting"><citation role="REFDB"><xref linkend="Bellamy2002"/></citation>
</pre></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-generate-xml-bibliography"></a>Generate the bibliography</h4></div></div></div><p>Unless you have good reasons not to do so, you should use the <a class="link" href="re22.html" title="runbib">runbib</a> shell script to generate the bibliography. This script greatly simplifies this task and offers a common interface for all supported document types. The following subsection will explain the use of this script. If you like to do it the hard way (or if you want to peek under the hood) you'll find a few explanations further down how to do this.</p><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="sect-xml-bibliography-with-runbib"></a>Use runbib</h5></div></div></div><p>Lets assume you have a DocBook SGML document <code class="filename">mypaper.sgml</code> and want to submit it to the "Journal of Irreproducible Results". We further assume that the bibliography style for this famous periodical is stored in your database under the name "J.Irrep.Res." (see <a class="link" href="ch10s02.html" title="Manage bibliography styles">Manage bibliography styles</a> to learn how it gets there). All your bibliography entries (at least those referenced without an explicit database name) are stored in the database <code class="filename">mybib</code>. Start the script from the directory that contains your document with the following command:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>runbib -d mybib -S "J.Irrep.Res." -t db31 foo.sgml</code></strong>
</pre><p>For a similar TEI XML document <code class="filename">bar.xml</code> you would run:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>runbib -d mybib -S "J.Irrep.Res." -t teix bar.xml</code></strong>
</pre><p>In both cases you will end up with a bibliography file (<code class="filename">foo.bib.sgml</code> and <code class="filename">bar.bib.xml</code>, respectively) as well as with a stylesheet (<code class="filename">J.Irrep.Res.dsl</code>) or a set of stylesheets (<code class="filename">J.Irrep.Res.fo.xsl</code> and <code class="filename">J.Irrep.Res.html.xsl</code>), respectively.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Don't worry if you are greeted by a list of (Open)Jade errors complaining about missing elements when you first run this script on a particular document. Your document contains a number of crosslinks that point to elements that do not exist yet - you use runbib precisely to create these elements (you thus face a classic bootstrapping problem). As soon as the bibliography is created, these error messages should go away. Later you will only get an error message for each bibliographic entry that was added since the last time you ran runbib.</p></div><p>To tell <a class="link" href="re22.html" title="runbib">runbib</a> that you want to create a raw instead of a cooked bibliography, use the <code class="option">-r</code> command line switch. As there is no style information involved, you don't need the <code class="option">-S</code> option in this case:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>runbib -d mybib -r -t db50x bar.xml</code></strong>
</pre><p>This will create a raw bibliography from the DocBook 5.0 document <code class="filename">bar.xml</code>, using the reference entries in the database <code class="filename">mybib</code>.</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a id="sect-xml-bibliography-without-runbib"></a>Do it the hardest possible way</h5></div></div></div><p>The following steps trace back exactly what the runbib script does. The only benefit of the hard way is that you have a chance to fiddle with the intermediate XML file which contains the list of bibliographic entries that should go into the bibliography. You can add further entries to extend the bibliography if you want to include uncited publications. The following procedure was written with a DocBook SGML document in mind, but transferring the commands to XML documents is straightforward. However, when working with XML documents there are additional steps required as outlined below.</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p class="title"><strong>Extract the list of bibliographic references</strong></p><p>Use Jade or OpenJade with the <code class="filename">citations.dsl</code> stylesheet to create a list of the reference IDs from SGML files (provide full paths as needed):</p><pre class="screen" width="60">
<code class="prompt">#~ </code>
<strong class="userinput"><code>openjade -t sgml -d citations.dsl /usr/lib/sgml/declaration/docbook-3.1.dcl foo.sgml > foo.id.xml</code></strong>
</pre><p>Be prepared for a long list of "missing ID" error messages. This is due to the fact that the elements with the IDs that the <code class="sgmltag-element">xref</code> elements in the citations point to do not yet exist, they will be generated in the RefDB bibliography output. If you process documents with more than 200 citations, you'll have to increase the maximum error limit of Jade in order to obtain all IDs the first time. After the first complete pass (including the steps outlined below), Jade will only complain about any additional citations that you have inserted since the last run.</p><p>XML files are processed using your favourite XSL processor. There are two different stylesheets available for raw and for cooked bibliographies. Both work all the same for DTD-based (DocBook 4.x, TEI P4) and schema-based (DocBook 5.x, TEI P5) documents:</p><pre class="screen" width="60">
<code class="prompt">#~ </code>
<strong class="userinput"><code>xsltproc --catalogs --xinclude /usr/local/share/refdb/xsl/citations.xsl foo.xml > foo.id.xml</code></strong>
<code class="prompt">#~ </code>
<strong class="userinput"><code>xsltproc --catalogs --xinclude /usr/local/share/refdb/xsl/citationsraw.xsl foo.xml > foo.id.xml</code></strong>
</pre><p>In all cases the output is a simple XML file that contains the information about all <code class="sgmltag-element">citation</code> and <code class="sgmltag-element">xref</code> elements with their relevant attributes. It is absolutely legal to extend this file with additional citation elements to specify references which are not cited but nonetheless should appear in the bibliography.</p><p>Unfortunately, both Jade and OpenJade don't get that Doctype line quite correct. Both forget to insert a space between the public and the system identifier, thus leaving you with a not well-formed document. Fire up your favourite editor and fix this line manually (insert a space between the two consecutive quotation marks on line 2).</p><p>If you edit this intermediate XML file (that is, if you do more than just fixing the Doctype line), you should make sure that the result is still valid according to the CitationList XML DTD. RefDB uses a non-validating parser to read this file so deviations from the DTD may slip through undetected and may have undesired consequences. The intermediate XML file carries the SYSTEM identifier of the CitationList XML DTD in the document type declaration. You may have to adapt the stylesheet <code class="filename">citations.dsl</code> to use the correct path for your local system.</p><p>The following command lines can be used to validate the document with <span class="application">(o)nsgmls</span> or <span class="application">xmllint</span> (change the paths as necessary):</p><pre class="screen" width="60">
<code class="prompt">~$ </code>
<strong class="userinput"><code>onsgmls -wxml -s /usr/lib/sgml/declaration/xml.dcl foo.id.xml</code></strong>
<code class="prompt">~$ </code>
<strong class="userinput"><code>xmllint --noout --nonet --dtdvalid file:///usr/local/share/refdb/dtd/citationlistx.dtd foo.id.xml</code></strong>
</pre></li><li class="step"><p class="title"><strong>Create the bibliography file</strong></p><pre class="screen" width="60">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbib -d mybib -S "J.Irrep.Res." -t db31 foo.id.xml > foo.bib.sgml</code></strong>
</pre><p>This assumes that your reference database is called "mybib" and that you try to publish your paper in a journal that accepts the style with the name "J.Irrep.Res.".</p><p>In addition to the bibliography file, refdbib will also create a DSSSL script containing the style specification. This file is a customized driver file for the RefDB-DocBook driver files and provides a couple of variable values specific for the given bibliography style.</p><p>If you want to generate a raw bibliography, use a command like this:</p><pre class="screen" width="60">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbib -d mybib -r -t db50x foo.id.xml > foo.bib.xml</code></strong>
</pre></li><li class="step"><p class="title"><strong>Post-processing</strong></p><p>This step is only required for XML documents. First we have to bring the stylesheets into shape, and if it is a TEI document, we'll also have to transform the bibliography file itself.</p><p>refdbib creates a general-purpose XSL stylesheet which we need to turn into one FO and one HTML stylesheet. Create two copies of the file. If the stylesheet was e.g. <code class="filename">J.Biol.Chem.xsl</code>, you need one copy named <code class="filename">J.Biol.Chem.fo.xsl</code> and one copy named <code class="filename">J.Biol.Chem.html.xsl</code>. Scan the files for an import statement whose <code class="sgmltag-attribute">href</code> attribute is surrounded with two "<!-- REFDBSTYLESHEET -->" comments. The value of this attribute must be set to the full path of the corresponding original stylesheet (DocBook FO or HTML, or TEI FO or HTML).</p><p>If you're working on a TEI P4 XML document, you'll have to transform the bibliography file itself. This is a DocBook SGML document and can be transformed easily with Jade/OpenJade and the <code class="filename">bibdb2tei.dsl</code> stylesheet. TEI P5 bibliographies are exported directly by <a class="link" href="re02.html" title="refdbd">refdbd</a> and do not require further processing.</p></li></ol></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="sect-transform-doc"></a>Transform the document</h4></div></div></div><p>Finally you can transform the document to create printable or HTML output. If you use cooked bibliographies you have to use the RefDB driver files for the DocBook or TEI stylesheets.</p><p>In addition to the general modifications of these driver files we'll have to apply modifications specific for the particular reference style. Therefore you have to specify the DSSSL or XSL style specification file that was created in the previous step. For your convenience it is recommended to use the supplied <a class="link" href="re24.html" title="refdbjade">refdbjade</a> and <a class="link" href="re25.html" title="refdbxml">refdbxml</a> scripts for DSSSL and XSL transformations, respectively, which were designed for this task:</p><pre class="screen" width="60">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbjade -t html -s J.Irrep.Res.dsl foo.sgml</code></strong>
</pre><pre class="screen" width="60">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbxml -t pdf -s J.Irrep.Res.fo.xsl bar.xml</code></strong>
</pre><p>If you want to change the bibliography style of your document, all you need to do is to rerun <span class="command"><strong>runbib</strong></span> and <span class="command"><strong>refdbjade</strong></span> or <span class="command"><strong>refdbxml</strong></span> with the new parameters. No changes to your DocBook source are necessary.</p><p>Processing your document with a raw bibliography does not differ from processing any other DocBook or TEI document. However, you can still use the <a class="link" href="re25.html" title="refdbxml">refdbxml</a> script to avoid having to type the full command line of your XSL processor. Use something like this to process a Docbook 5.0 document with a raw bibliography:</p><pre class="screen" width="60">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbxml -t pdf -s db5 bar.xml</code></strong>
</pre><p>The <code class="option">-s</code> option tells the script to use the stock DocBook stylesheets for version 5. Other values are "db", "tei", and "tei5" for the DocBook stylesheet for version 4.x, the TEI P4 stylesheets, and the TEI P5 stylesheets, respectively</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you want to create a bibliography for each part of a book or for each chapter, the procedure is not much different. The simplest approach is to keep the parts or chapters in individual files and process these individually as described above for the whole document. You'll get several bibliography files that you can include into the corresponding document source files.</p></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect3-customize-bib"></a>How to use custom stylesheets</h3></div></div></div><p>We have assumed in the previous instructions that the stock DocBook or TEI stylesheets suit your needs when processing your documents. However, if you need a particular formatting of the parts of your document which are not under the control of RefDB (things like fonts, colours, font sizes and so on), you'll have to create a driver file with your personal modifications, and somehow make sure this driver file is used whenever your document is processed. This section discusses the available mechanisms to use particular XSL driver files as a per-user or a per-document option. Currently no such mechanism is available for the DSSSL stylesheets.</p><p>A driver file is essentially a stylesheet which imports the stock stylesheets and adds a few modifications. XSL is designed such that any definition of a template in the driver file overrides the definition in the imported file. RefDB uses this mechanism extensively to provide the formatting of citations and bibliographic listings. Whenever you run <a class="link" href="re20.html" title="refdbib">refdbib</a> (or <a class="link" href="re22.html" title="runbib">runbib</a> which calls the former), a driver file is created which imports a general RefDB driver file. This general driver file in turn includes the stock stylesheets (imports can be nested). If the stock stylesheets don't suit your needs, you'll have to provide two driver files:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>a driver file for the stock stylesheets which contains your modifications of those parts which are not under RefDB's control. Obviously, this driver file must import the stock stylesheets. You can put this driver file into any convenient subdirectory in your home directory. For further information about how to set up a driver file, please see Bob Stayton's <a class="ulink" href="http://www.sagehill.net/docbookxsl/index.html" target="_top">DocBook XSL Guide</a> (the general approach is applicable to TEI and any other XSL stylesheets just as well)</p></li><li class="listitem"><p>a modified general RefDB driver file which imports your driver file instead of the stock stylesheets. To this end, copy the relevant general RefDB driver file (there are driver files for fo, html, and xhtml output, and they are available both for DocBook and for TEI) to a convenient subdirectory in your home directory and modify the import statements to suit your needs.</p></li></ul></div><p>There are two options to have the modified general RefDB driver file used instead of the default ones:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>if you want to apply your modifications as a default to all documents which you process, consider adding the paths to your personal copy of the <code class="filename">runbibrc</code> configuration file.</p></li><li class="listitem"><p>if you want to apply the modifications to a particular <a class="link" href="re21.html" title="refdbnd">refdbnd</a>-created project, just specify the paths of the modified general RefDB driver files when setting up the project. This way, each project can use a different set of modifications.</p></li></ul></div><p><a class="xref" href="ch10s03.html#fig-stylesheets" title="Figure 10.2. Stylesheets involved in processing RefDB documents">Figure 10.2, “Stylesheets involved in processing RefDB documents”</a> visualizes how a document containing a RefDB bibliography is processed with a focus on the stylesheets involved. The example shows the transformation of a DocBook XML document to fo (which might then be processed to e.g. PDF). However, the same principles are applicable to other output formats and other document types. The left hand side shows the default processing using the stylesheets installed by RefDB. <a class="link" href="re20.html" title="refdbib">refdbib</a> (which may be invoked by runbib, or by running a <a class="link" href="re21.html" title="refdbnd">refdbnd</a>-created <code class="filename">Makefile</code>) creates an intermediate stylesheet containing the style-specific information. This stylesheet is converted to output-type-specific driver files for fo, html, and sometimes xhtml output. The figure shows only the fo driver file to keep it simple. This driver file imports the general RefDB fo driver file, which in turn imports the appropriate official DocBook fo stylesheet. The right hand side shows how to process the same document with a DocBook driver file which may alter the general formatting of the document (page size, borders, fonts and the like). As you can see, you have to provide both the DocBook driver file and an equivalent of the general RefDB fo driver file, which has to import your driver file instead of the stock DocBook stylesheet.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You can of course add all your general modifications to <code class="filename">myrefdbdriver.xsl</code> and have that import the stock DocBook stylesheet. However, doing it in two steps as shown will allow you to use <code class="filename">mydocbookdriver.xsl</code> for non-RefDB projects as well.</p></div><div class="figure"><a id="fig-stylesheets"></a><p class="title"><strong>Figure 10.2. Stylesheets involved in processing RefDB documents</strong></p><div class="figure-contents"><div class="mediaobject"><img src="refdbmanualfig6.png" alt="Stylesheets involved in processing RefDB documents" /></div></div></div><br class="figure-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch10s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch10.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch10s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Manage bibliography styles </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Create LaTeX/BibTeX bibliographies</td></tr></table></div></body></html>
|