/usr/share/doc/refdb/refdb-manual/re27.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>refdbxp</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="ch15.html" title="Chapter 15. Tools for bibliographies" /><link rel="prev" href="re26.html" title="refdbrtf" /><link rel="next" href="re28.html" title="refdb-ms" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">refdbxp</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="re26.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Tools for bibliographies</th><td width="20%" align="right"> <a accesskey="n" href="re28.html">Next</a></td></tr></table><hr /></div><div class="refentry"><a id="refentry-refdbxp"></a><div class="titlepage"></div><div class="refnamediv"><a id="refdbxp-name"></a><h2>Name</h2><p>refdbxp — converts short and full citation formats in SGML and XML documents containing RefDB citations.</p></div><div class="refsynopsisdiv"><a id="refdbxp-synopsis"></a><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">refdbxp</code> [<code class="option">-h</code> ] [<code class="option">-s</code> ] [<code class="option">-t</code> <em class="replaceable"><code>input-format</code></em>] <em class="replaceable"><code>refdbxp</code></em> </p></div></div><div class="refsect1"><a id="refdbxp-description"></a><h2>Description</h2><p>refdbxp allows the interconversion of the short and full notation of citations in the supported SGML and XML documents of RefDB(7). See the RefDB manual (see below) for information about the two notations. The conversion is round-trip safe, and it supports mixing short and full notation in the same source document. Full-notation citations will use the correct encoding for first and subsequent citations of the same reference.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You should be aware that refdbxp is not a SGML or XML-aware tool. It is a simple text replacement tool with some restrictions:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If you comment out citation elements, they still count as if they were present when the first/subsequent citation issue is resolved (refdbxp simply doesn't know about the concept of a comment). In the following example, the citation in the last line will be the only one transformed, but it will be formatted as a subsequent citation of reference 9, not as the first citation:</p><pre class="programlisting"><!-- <citation role="REFDB">9;</citation> first occurrence -->
<!-- other stuff inbetween -->
<citation role="REFDB">9;</citation><!-- second occurrence -->
</pre></li><li class="listitem"><p>If you use SGML/XML tags within a comment and nest this comment ingeniously between the start tag and the end tag of an element relevant for refdbxp, you shoot yourself in the foot. You do not want to use code like this (why would you, anyways?):</p><pre class="programlisting"><citation role="REFDB"><!-- </citation> -->2;5;9;</citation></pre></li><li class="listitem"><p>refdbxp does not include external entities. The whole document refdbxp is supposed to convert needs to be in one chunk.</p></li><li class="listitem"><p>refdbxp currently does not support multiple databases per document.</p></li></ul></div><p>One way to work around the problem with comments is to create a copy of your master source and use a small script to remove comments just before you process and transform your text. To work around the fact that refdbxp does not treat external entities correctly, use a tool like <span class="command"><strong>sgmlnorm</strong></span> (shipped with the Jade/OpenJade packages) to preprocess the document. To work around the missing support of multiple databases, well... just wait.</p></div></div><div class="refsect1"><a id="refdbxp-options"></a><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h</code></span></dt><dd><p>Prints a command synopsis on the screen and exits.</p></dd><dt><span class="term"><code class="option">-s</code></span></dt><dd><p>Create citations using the short notation. The default is to use the full notation.</p></dd><dt><span class="term"><code class="option">-t</code> <em class="replaceable"><code>input-format</code></em></span></dt><dd><p>Select the type of input. Currently supported values are <span class="emphasis"><em>db31</em></span> (DocBook SGML version 3.1 or later), <span class="emphasis"><em>db31x</em></span> (DocBook XML, all versions), and <span class="emphasis"><em>teix</em></span> (TEI XML).</p></dd></dl></div></div><div class="refsect1"><a id="refdbxp-example"></a><h2>Example</h2><p>Lets first try the most common usage of refdbxp. The following command expands all citations, regardless of whether they are written in short or full notation, to the full notation and writes the result to a new file <code class="filename">foo.full.sgml</code>. The input from <code class="filename">foo.sgml</code> is assumed to be DocBook SGML:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbxp -t db31 < foo.sgml > foo.full.sgml</code></strong>
</pre><p>The following command goes the other way. This time we convert all citations of a TEI XML document, regardless of whether they are written in short or full notation, to the short notation and write the result to a new file:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>refdbxp -t teix -s < bar.xml > bar.short.xml</code></strong>
</pre><p>The last example shows how to treat documents that consist of several files. The DocBook SGML master file <code class="filename">foo_master.sgml</code> includes several other subdocuments as external entities. Treating those files individually with refdbxp would screw up things as the first/subsequent citation issue would not be treated correctly and collisions of automatically created element IDs would result. The following command comes to the rescue and expands all citations in the document correctly:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>osgmlnorm -dn /usr/local/share/sgml/docbook/4.1/docbook.dcl foo_master.sgml | refdbxp -t db31 > foo.full.sgml</code></strong>
</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>You may have realized that there's two small problems with this procedure. First, using (o)sgmlnorm will also include the external entity that contains (or will contain once it's created) the bibliography element created by refdb. One way around this is to use a mock file that just contains the entity reference in a comment. Lets assume your document <code class="filename">foo.sgml</code> wants to include the bibliography by using the entity declaration <code class="sgmltag-paramentity">%bibliography;</code> at the proper location. The entity is declared in the declaration subset at the top of your sourcefile as the external file <code class="filename">foo.bib.sgml</code>. Then you should create a file <code class="filename">foo.bib.sgml</code> with the following contents:</p><pre class="programlisting"><!--&bibliography;--></pre><p>We have to outcomment the entity reference as these may be nested, i.e. the parser would try to replace this entity again and fail because the entity is already opened. After the conversion you just need to uncomment the parameter entity. If you like long commands, you could do this on the fly like this:</p><pre class="screen">
<code class="prompt">~$ </code>
<strong class="userinput"><code>osgmlnorm -dn /usr/local/share/sgml/docbook/4.1/docbook.dcl foo_master.sgml | refdbxp -t db31 | sed 's%<!--\&bibliography;-->%\&bibliography;%' > foo.full.sgml</code></strong>
</pre><p>Second, (o)nsgmlnorm will not output the internal declaration subset that we need at least to declare the parameter entity for the bibliography. You could fix this with a sed command along the lines of the command shown above or add it back manually.</p></div></div><div class="refsect1"><a id="refdbxp-see_also"></a><h2>See also</h2><p><span class="emphasis"><em>RefDB</em></span> (7),
<span class="emphasis"><em><a class="link" href="re21.html" title="refdbnd">refdbnd</a></em></span> (1).</p><p><span class="emphasis"><em>RefDB manual (local copy) </em></span> PREFIX/share/doc/refdb-<version>/refdb-manual/index.html</p><p><span class="emphasis"><em>RefDB manual (web) </em></span> <<a class="ulink" href="http://refdb.sourceforge.net/manual/index.html" target="_top">http://refdb.sourceforge.net/manual/index.html</a>></p><p><span class="emphasis"><em>RefDB on the web </em></span> <<a class="ulink" href="http://refdb.sourceforge.net/" target="_top">http://refdb.sourceforge.net/</a>></p></div><div class="refsect1"><a id="refdbxp-author"></a><h2>Author</h2><p>refdbxp was written by Markus Hoenicka <markus@mhoenicka.de>.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="re26.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch15.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="re28.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">refdbrtf </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> refdb-ms</td></tr></table></div></body></html>
|