Creating References and Bibliography in ESP Pages

This page explains how to make a list of reference works (books, articles, etc.) and when and how to use it.

Further reading functionality

ESP has functionality for referencing articles, journals, books, websites etc. within the site's pages.

There are two methods to create a list of materials suggested for further reading:

using links to a bookmarked bibliography; or
using the list of references in the referents.xml file.

Method I is recommended for sites where you require links to a bibliography page, which may contain links to downloadable resources, such as PDF files. This method was used on the Knowledge & Power [http://oracc.museum.upenn.edu/saao/knpp] website.

Method II is recommended for sites such as the Whipple Museum's Explore [http://www.hps.cam.ac.uk/whipple/explore] website that have a limited bibliography and no requirement for a separate bibliography page.

Method I

First, create a bibliography page that contains all of the reference material for your site. Here you can create links to downloadable material, such as PDF files and multimedia content.

Use the <esp:bookmark> element to create a bookmark for each entry in your bibliography to which you would like to refer. On the page where you wish to place the further reading list, create a set of links to the relevant bookmarks in your bibliography.

See the section on bookmarks for details of how to do this.

You can place the links anywhere on the page, though it may be helpful to put them together at the end.

Method II

The list of references created in the referents.xml file (see the section on References) can be used to add a list of materials for further reading to the bottom of a page.

At the bottom of your page, insert the <esp:reading> element with the id of each item you would like to include in a 'further reading' list. Technically, the element can be placed anywhere on the page, though it may be helpful to put them together at the end.

The specification of <esp:reading> is given below:

<esp:reading
	referent="example"
	page="123"
/>

referent: Mandatory. The id of a <esp:referent> element in the file referents.xml in the site-content folder.
page: Optional. The page number or page range to be added to the further reading entry. For example, page="123" or page="123, 125" or page="123-150" (the text p. or pp. is added automatically when the site is rebuilt).

NB. The element is always empty.

References

The `referents.xml` file

References are stored in the file referents.xml in the folder site-content. The list of referents is created using a number of <ref:referent> elements inside the root element <ref:referents>.

Adding reference functionality is carried out in two stages:

adding the details of an article/book etc., to the reference list using <ref:referent>:
creating a link to the reference in the text using <esp:ref>.

Adding to the reference list

To add the details of a book, article, etc., to the reference list, create a new <ref:referent> tag within the reference list <ref:referents>.

The specification of <ref:referent> is given below:

<ref:referent id="example">
	Arbitrary inline content
</ref:referent>

id: A unique identifier for this referent. Becomes part of the URL for that referent, so as well as being unique, each id should be reasonably short, contain no spaces and no accented characters.

Place the details of the article, book, etc., within the element in whatever reference format you prefer. The text should not end with a full stop, as this is added by the system.

Here is an example referents.xml file containing two references:

<?xml version="1.0" encoding="utf-8"?>
<esp:referents 
	xmlns:ref="http://oracc.org/ns/esp-refer/1.0"
	xmlns:esp="http://oracc.org/ns/esp/1.0"
	xmlns="http://www.w3.org/1999/xhtml">
>

<esp:referent id="mercer1993">MERCER, P.A. and SMITH, G., 1993. <i>Private 
viewdata in the UK.</i> 2nd ed. London: Longman>/esp:referent>

<esp:referent id="bantz1995">BANTZ, C.R., 1995. Social dimensions of software 
development. In: J.A. ANDERSON, ed. <i>Annual review of software management 
and development.>/i> Newbury Park, CA: Sage</esp:referent>

</esp:referents>

Referring to the reference list

To place a reference in the text to an item in the reference list, use the <esp:ref> element. ESP will place a bracketed reference number in the text at the point where <esp:ref> is inserted and will place the full details of the reference at the bottom of the page. (The number acts as a link to the full reference.) Remember to use the id of the referent as defined in the reference list.

The specification of the <esp:ref> element is given below:

<esp:ref
	referent="example"
	page="123"
/>

referent: Mandatory. The id of a <esp:referent> element listed in the file referents.xml in the site-content folder.
page: Optional. The page number or page range to be added to the reference. For example, page="123" or page="123, 125" or page="123-150" (the text p. or pp. is added automatically when the site is rebuilt).

NB. This element is always empty.

Examples of reference functionality

See the Whipple Museum's Explore [http://www.hps.cam.ac.uk/whipple/explore] website for examples of reference functionality in use. It was not utilised in the Knowledge & Power [http://oracc.museum.upenn.edu/saao/knpp] website.