In DocBook documents (both SGML and XML), citations are encoded as citation elements. To distinguish these from citation elements that are not meant to be processed by RefDB, set the role attribute to REFDB in all caps. Each citation 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:

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

The list of references can either contain numerical ID values, as in the examples above, or alphanumeric citation keys like in the following example:

<citation role="REFDB">miller1999;jones2001</citation>
	  

The corresponding syntax for TEI XML documents is quite similar, except that we abuse the general-purpose seg element and tag it for use with RefDB by setting the type to REFDBCITATION in all caps:

<seg type="REFDBCITATION">2;5;9</seg>
	  

Again, you can use citation keys instead of the ID values shown in the example above.

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:

<para><citation role="REFDB">A:jones2001</citation> reported
recently <citation role="REFDB">Y:jones2001</citation> ...</para>
	  

You may have guessed that the prefix "A:" tags a citation as an author-only citation and that the prefix "Y:" means year-only.

This is about all you need to know about the short notation. The only thing you must not forget is that you must preprocess documents that contain citations in short notation with refdbxp before you transform the document to one of the output formats.

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 refdbxp. The output created by this utility is the full notation described in this section.

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.

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:

<citation role="REFDB">      
<xref linkend="ID1-X">        
</citation>
<citation role="REFDB">
<xref linkend="LITIBP-ID2-X"> 
</citation>
	  

	The citation element is a wrapper for one or more bibliographic references. The role attribute is set to REFDB to distinguish this citation from other citation elements that RefDB should leave alone. Each citation element can contain one or more xref elements.
	Each xref element specifies one bibliographic reference. The value of the linkend 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.
	This xref 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).

The corresponding syntax in a TEI XML document looks like this:

<seg type="REFDBCITATION">      
<ptr targOrder="U" target="ID1-X" TEIform="ptr"/>       
</seg>
<seg type="REFDBCITATION">
<ptr targOrder="U" target="LITIBP-ID2-X" TEIform="ptr"/>
</seg>
	  

	The general-purpose seg element with the type attribute set to REFDBCITATION is the citation wrapper for one or more bibliographic references.
	Each bibliographic reference is specified by a ptr element whose target 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.
	This is the corresponding bibliographic reference with the database specified.

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

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.

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.

<citation role="REFDB">
<xref endterm="IMTHEFIRST" linkend="ID1" role="MULTIXREF">
<xref linkend="ID1-X">                                   
<xref linkend="ID14-X">
<xref linkend="ID7-X">
</citation>
	  

This is the additional xref element which is mandatory in multiple citations. The linkend 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 role attribute with the value MULTIXREF. You also have to provide an unique value for the endterm 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.

This and the following xref elements define the actual references that comprise the multiple citation.

The corresponding TEI citation is a little bit simpler:

<seg type="REFDBCITATION">
<ptr type="MULTIXREF" targOrder="U" target="IMTHEFIRST" TEIform="ptr"/>
<ptr targOrder="U" target="ID1-X" TEIform="ptr"/>                     
<ptr targOrder="U" target="LITIBP-ID21-X" TEIform="ptr"/>
<ptr targOrder="U" target="ID5-X" TEIform="ptr"/>
</seg>
	  

This is the additional ptr element which is mandatory in multiple citations. The element must have a type attribute with the value MULTIXREF. You also have to provide an unique value for the target 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.

This and the following xref elements define the actual references that comprise the multiple citation.

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 citation 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 role attribute of the citation element to REFDB to include it in the list of citations that runbib extracts from your document, like this:

<citation role="REFDB"><xref linkend="Bellamy2002"/></citation>

Lets assume you have a DocBook SGML document mypaper.sgml 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 Manage bibliography styles to learn how it gets there). All your bibliography entries (at least those referenced without an explicit database name) are stored in the database mybib. Start the script from the directory that contains your document with the following command:

	    ~$ 
	    runbib -d mybib -S "J.Irrep.Res." -t db31 foo.sgml
	  

For a similar TEI XML document bar.xml you would run:

	    ~$ 
	    runbib -d mybib -S "J.Irrep.Res." -t teix bar.xml
	  

In both cases you will end up with a bibliography file (foo.bib.sgml and bar.bib.xml, respectively) as well as with a stylesheet (J.Irrep.Res.dsl) or a set of stylesheets (J.Irrep.Res.fo.xsl and J.Irrep.Res.html.xsl), respectively.

To tell runbib that you want to create a raw instead of a cooked bibliography, use the -r command line switch. As there is no style information involved, you don't need the -S option in this case:

	    ~$ 
	    runbib -d mybib -r -t db50x bar.xml
	  

This will create a raw bibliography from the DocBook 5.0 document bar.xml, using the reference entries in the database mybib.

The following steps do exactly what the runbib script does, just with more to type. 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.