Customizing bibliography output

Customizing bibliography output
	Chapter 14. Bibliographies

If you want a two-column bibliography in print output, you need to create a custom page-master and use it for bibliography in place of the original back page-master, which is also used by appendix, glossary, and colophon elements. See the section “Custom page design” to learn how to do that.

To customize entries in the bibliography for print output, you can use the biblioentry.properties attribute-set. That attribute-set is applied to the overall fo:block containing each entry. You can set spacing, indents, and font properties for your entries. By default, it sets start-indent and end-indent properties and uses the normal.para.spacing attribute-set.

To customize entries in the bibliography for HTML output, use CSS. Each entry is contained in a div class="biblioentry" for which you can write a CSS selector such as div.biblioentry and apply properties.

The label in square brackets at the start of each entry can be customized using the biblioentry.label template. For example, you may have turned off numbering of entries, but some of your entries have an abbrev element that you do not want to show. You can turn them off with the following customization:

<xsl:template name="biblioentry.label">
 <!--do nothing --> 
</xsl:template>

This template normally generates the label with a number or abbreviation. This customization turns off all labels for entries in a bibliography by redefining the template to do nothing.

If you do not like the way a particular bibliographic element such as author is formatted, then you can customize its template. Elements in a biblioentry are processed with templates in mode="bibliography.mode" Elements in a bibliomixed are processed with templates in mode="bibliomixed.mode". Look for the appropriate template in biblio.xsl (either html or fo), and then copy it to your customization layer to change it. For example:

<xsl:template match="author" mode="bibliography.mode">
  <span class="{name(.)}">
    <xsl:call-template name="person.name"/>
    <xsl:value-of select="$biblioentry.item.separator"/>
  </span>
</xsl:template>

This template formats an author within a biblioentry for HTML output. It puts the output within an HTML span element so it can add a class="author" attribute, which makes it possible to apply styles with a CSS stylesheet. Then it calls the person.name template to output the author's name. Then it adds the $biblioentry.item.separator, which is just a period by default. The template for bibliomixed using mode="bibliomixed.mode" is similar except it omits the trailing period. It assumes you are adding any necessary punctuation literally.

If you want the order of elements in the output to differ from how they appear in biblioentry element, then you will have to do a larger customization. There is no easy way to do this now, but you can expect this feature to become available in a future version of the DocBook stylesheets. To do it now, you must copy the template from biblio.xsl with match="biblioentry" to your customization layer. Within that template, locate these lines (HTML version):

<div class="{name(.)}">
    <xsl:call-template name="anchor"/>
    <p>
      <xsl:call-template  name="biblioentry.label"/>
      <xsl:apply-templates  mode="bibliography.mode"/>
    </p>
 </div>

The line <xsl:apply-templates mode="bibliography.mode"/> acts on each child of the biblioentry in the order in which they appear in the document. You need to replace that line with a sequence of similar lines, each of which selects a particular element. The order is then determined by those lines. For example:

<xsl:apply-templates  select="author"  mode="bibliography.mode"/>
<xsl:apply-templates  select="title"  mode="bibliography.mode"/>
<xsl:apply-templates  select="publisher"  mode="bibliography.mode"/>

Now the output for each entry will have the order author, title, publisher, regardless of the order of those elements in the source document.

If you do not like the square brackets used in citation cross references, you can change them with a stylesheet customization. These two templates control the prefix and suffix characters:

<xsl:template match="biblioentry|bibliomixed" mode="xref-to-prefix">
  <xsl:text>[</xsl:text>
</xsl:template>

<xsl:template match="biblioentry|bibliomixed" mode="xref-to-suffix">
  <xsl:text>]</xsl:text>
</xsl:template>

Copy these templates to your customization layer and change the text that they generate.

ISO 690 bibliography standard

If you want or need to use an established international standard for bibliographic entries, then consider ISO 690. The standard itself says it best:

	This International Standard specifies the elements to be included in bibliographic references to published monographs and serials, to chapters, articles, etc. in such publications and to patent documents. It sets out a prescribed order for the elements of the reference and establishes conventions for the transcription and presentation of information derived from the source publication.
	--International Standard ISO 690:1987

The standard specifies for each type of document what information should be included in the bibliographic citation. It also specifies the order and the punctuation.

Starting with version 1.72, the DocBook XSL stylesheets provide support for ISO 690 style bibliographic output. In order to use this feature, you need to do two things:

Mark up your biblioentry elements using the recommended DocBook elements that the stylesheet recognizes for each type of referenced document.
Set the stylesheet parameter bibliography.style to iso690 when you process your bibliography.

The markup requirements for your entries are documented on the DocBook Wiki site http://wiki.docbook.org/topic/ISO690Bibliography. The documentation shows the DocBook XML elements and attributes to use for each type of referenced document, and provides examples of each. In general:

The list of referenced document types includes monographs (books), serials, articles, patent documents, electronic documents, and parts of each.
Each document type must be identified by a specific role attribute on its biblioentry element.
Each biblioentry has required and optional elements according to its document type.
The order of elements must be followed.

Any text (such as ISBN) and punctuation that is generated by the stylesheet comes from the standard DocBook gentext files, such as common/en.xml for English. See the section “Generated text” for more information on DocBook's gentext system. These gentext entries are contained in a context name="iso690" element. They may not be translated for all languages, but they can be customized using the method described in the section “Customizing generated text”.

There are two stylesheet parameters that control the formatting of ISO 690 entries.

The biblioentry.primary.count parameter identifies how many authors in an entry should be included in the output. If there are three or fewer authors, then they are all output. If there are more than three, then the output can include one, two, or three authors from the list. Set this parameter to a value of 1 to get one author, to 2 for two authors, or 3 for three authors. The default value is 1.
The biblioentry.alt.primary.seps parameter controls the use of alternative punctuation and connector text between authors in the output. When this parameter is set to zero (the default), then the separators come from gentext entries in the context name="authorgroup" element. When set to 1, then the separators come from gentext entries in the context name="iso690" element.

Bibliography title

The title Bibliography that appears at the beginning of a bibliography is generated by the stylesheet if you do not include a title element. If your document uses a lang other than English, then the generated title is in the appropriate language. If you need to change the title text, just add a title element to your document, as in the following example:

<bibliography>
  <title>Further Reading</title>
  ...

The formatting of the bibliography title is handled as part of the general titlepage mechanism in DocBook XSL. That means the specifications original in the title page spec file titlepage.templates.xml (that's .xml) in the html or fo stylesheet subdirectory.

For HTML output, it is easiest to format the title using a CSS stylesheet. You can create a CSS selector like the following:

div.bibliography div.titlepage h2.title {
   put your CSS styles here
}

For print output, the bibliography title, like other component elements, is processed using the component.title template. See the section “Other component titles” for a description of how to customize such titles.


Sorting a bibliography		RefDB bibliographic database