Provided by: refdb-clients_1.0.2-1_amd64 bug

NAME

       refdbxp - converts short and full citation formats in SGML and XML documents containing
       RefDB citations.

SYNOPSIS

       refdbxp [-h] [-s] [-t input-format] refdbxp

DESCRIPTION

       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.

           Note
           You should be aware that refdbxp is not a SGML or XML-aware tool. It is a simple text
           replacement tool with some restrictions:

           •   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:

                   <!-- <citation role="REFDB">9;</citation> first occurrence -->
                   <!-- other stuff inbetween -->
                   <citation role="REFDB">9;</citation><!-- second occurrence -->

           •   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?):

                   <citation role="REFDB"><!-- </citation> -->2;5;9;</citation>

           •   refdbxp does not include external entities. The whole document refdbxp is supposed
               to convert needs to be in one chunk.

           •   refdbxp currently does not support multiple databases per document.

           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 sgmlnorm (shipped with the Jade/OpenJade packages) to
           preprocess the document. To work around the missing support of multiple databases,
           well... just wait.

OPTIONS

       -h
           Prints a command synopsis on the screen and exits.

       -s
           Create citations using the short notation. The default is to use the full notation.

       -t input-format
           Select the type of input. Currently supported values are db31 (DocBook SGML version
           3.1 or later), db31x (DocBook XML, all versions), and teix (TEI XML).

EXAMPLE

       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 foo.full.sgml. The input from foo.sgml is
       assumed to be DocBook SGML:

                ~$
                refdbxp -t db31 < foo.sgml > foo.full.sgml

       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:

                ~$
                refdbxp -t teix -s < bar.xml > bar.short.xml

       The last example shows how to treat documents that consist of several files. The DocBook
       SGML master file foo_master.sgml 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:

                ~$
                osgmlnorm -dn /usr/local/share/sgml/docbook/4.1/docbook.dcl foo_master.sgml | refdbxp -t db31 > foo.full.sgml

           Note
           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 foo.sgml wants to include the bibliography by using the entity
           declaration %bibliography; at the proper location. The entity is declared in the
           declaration subset at the top of your sourcefile as the external file foo.bib.sgml.
           Then you should create a file foo.bib.sgml with the following contents:

               <!--&bibliography;-->

           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:

                      ~$
                      osgmlnorm -dn /usr/local/share/sgml/docbook/4.1/docbook.dcl foo_master.sgml | refdbxp -t db31 | sed 's%<!--\&bibliography;-->%\&bibliography;%' > foo.full.sgml

           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.

SEE ALSO

       RefDB (7), refdbnd (1).

       RefDB manual (local copy) PREFIX/share/doc/refdb-<version>/refdb-manual/index.html

       RefDB manual (web) <http://refdb.sourceforge.net/manual/index.html>

       RefDB on the web <http://refdb.sourceforge.net/>

AUTHOR

       refdbxp was written by Markus Hoenicka <markus@mhoenicka.de>.