Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
REFDBXP(1)			 RefDB Manual			    REFDBXP(1)

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:

       o  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 -->

       o  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>

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

       o  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) <[1]http://refdb.sourceforge.net/manual/index.html>

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

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

REFERENCES
       1. http://refdb.sourceforge.net/manual/index.html
	  http://refdb.sourceforge.net/manual/index.html

       2. http://refdb.sourceforge.net/
	  http://refdb.sourceforge.net/

2005-10-17			  2005-10-17			    REFDBXP(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLE | SEE ALSO | AUTHOR | REFERENCES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=refdbxp&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help