'\" t
.\" Title: refdbxp
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1
.\" Date: 2005-10-17
.\" Manual: RefDB Manual
.\" Source: RefDB Manual
.\" Language: English
.\"
.TH "REFDBXP" "1" "2005\-10\-17" "RefDB Manual" "RefDB Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
refdbxp \- converts short and full citation formats in SGML and XML documents containing RefDB citations\&.
.SH "SYNOPSIS"
.HP \w'\fBrefdbxp\fR\ 'u
\fBrefdbxp\fR [\fB\-h\fR] [\fB\-s\fR] [\fB\-t\fR\ \fIinput\-format\fR] \fIrefdbxp\fR
.SH "DESCRIPTION"
.PP
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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
You should be aware that refdbxp is not a SGML or XML\-aware tool\&. It is a simple text replacement tool with some restrictions:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\*(Aqt 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:
.sp
.if n \{\
.RS 4
.\}
.nf
9; first occurrence \-\->
9;
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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?):
.sp
.if n \{\
.RS 4
.\}
.nf
\-\->2;5;9;
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
refdbxp does not include external entities\&. The whole document refdbxp is supposed to convert needs to be in one chunk\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
refdbxp currently does not support multiple databases per document\&.
.RE
.PP
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
\fBsgmlnorm\fR
(shipped with the Jade/OpenJade packages) to preprocess the document\&. To work around the missing support of multiple databases, well\&.\&.\&. just wait\&.
.sp .5v
.RE
.SH "OPTIONS"
.PP
\fB\-h\fR
.RS 4
Prints a command synopsis on the screen and exits\&.
.RE
.PP
\fB\-s\fR
.RS 4
Create citations using the short notation\&. The default is to use the full notation\&.
.RE
.PP
\fB\-t\fR \fIinput\-format\fR
.RS 4
Select the type of input\&. Currently supported values are
\fIdb31\fR
(DocBook SGML version 3\&.1 or later),
\fIdb31x\fR
(DocBook XML, all versions), and
\fIteix\fR
(TEI XML)\&.
.RE
.SH "EXAMPLE"
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
~$
\fBrefdbxp \-t db31 < foo\&.sgml > foo\&.full\&.sgml\fR
.fi
.if n \{\
.RE
.\}
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
~$
\fBrefdbxp \-t teix \-s < bar\&.xml > bar\&.short\&.xml\fR
.fi
.if n \{\
.RE
.\}
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
~$
\fBosgmlnorm \-dn /usr/local/share/sgml/docbook/4\&.1/docbook\&.dcl foo_master\&.sgml | refdbxp \-t db31 > foo\&.full\&.sgml\fR
.fi
.if n \{\
.RE
.\}
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
You may have realized that there\*(Aqs two small problems with this procedure\&. First, using (o)sgmlnorm will also include the external entity that contains (or will contain once it\*(Aqs 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:
.sp
.if n \{\
.RS 4
.\}
.nf
.fi
.if n \{\
.RE
.\}
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
~$
\fBosgmlnorm \-dn /usr/local/share/sgml/docbook/4\&.1/docbook\&.dcl foo_master\&.sgml | refdbxp \-t db31 | sed \*(Aqs%%\e&bibliography;%\*(Aq > foo\&.full\&.sgml\fR
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.sp .5v
.RE
.SH "SEE ALSO"
.PP
\fBRefDB\fR
(7),
\fBrefdbnd\fR
(1)\&.
.PP
\fIRefDB manual (local copy) \fR
PREFIX/share/doc/refdb\-/refdb\-manual/index\&.html
.PP
\fIRefDB manual (web) \fR
<\m[blue]\fBhttp://refdb\&.sourceforge\&.net/manual/index\&.html\fR\m[]>
.PP
\fIRefDB on the web \fR
<\m[blue]\fBhttp://refdb\&.sourceforge\&.net/\fR\m[]>
.SH "AUTHOR"
.PP
refdbxp was written by Markus Hoenicka \&.