Contents | Start | End | Previous: Appendix C: The Jutoh Box Model | Next: Appendix E: Speech Markup Reference


Appendix D: The Bibliographic Formatting Language

This topic describes the XML-based language that Jutoh uses to format bibliographic items.

Introduction

There are many standards for formatting bibliography and reference sections, and organisations and publishers may dictate their own house style. In addition, bibliographic references have differing fields according to the type of reference, and formatting must also cope with missing field values and other quirks.

So, a built-in style or a simplistic template created by a point and click user interface cannot suffice. Instead, bibliography formatting in Jutoh is specified using an XML-based language called Xi (XML Interpreter). This simple language is totally dedicated to Jutoh bibliographic formatting and is supported by a test facility in the formatting template dialog. It’s easy to export and import these templates, so users who become queasy at the thought of editing XML can outsource the task (if needed at all).

The commands in a formatting template are executed for every item in the bibliography. It can access all the fields in the bibliography, as well as some other variables that may be needed such as the item number (Number) and whether the bibliography is being formatted as a list (FormatAsList). The template can also set variables, either to communicate with Jutoh or for its own convenience. The template writes out fields and other necessary text using the write command, conditional on whether fields are set, or on the values of variables.

An example template

Here’s an example of a formatting template, so you can get used to the overall feel:

<?xml version="1.0" encoding="UTF-8"?>

<xi version="1.0.0.0">

 

<!-- Use the new variable Id so we can change it easily -->

<set name="Id" value-of="Number"/>

<set name="PersonSeparator" value=" and "/>

 

<!-- A catch-all formatting clause -->

<write if-variable-neq="FormatAsList" value="1">

<variable name="Id"/>

<text value=". "/>

</write>

 

<write if-variable-set="Title" attributes="emphasis">

<variable name="Title"/>

</write>

 

<write if-variable-set="Book">

<text value=", "/>

<variable name="Book"/>

</write>

 

<write if-variable-set="Author">

<text value=", "/>

<variable name="Author.surnamesfirst" attributes="strong"/>

</write>

 

<write if-variable-set="Corporate author">

<text value=", "/>

<variable name="Corporate author" attributes="strong"/>

</write>

 

<write if-variable-set="Year">

<text value=", "/>

<variable name="Year"/>

</write>

 

<write if-variable-set="City">

<text value=", "/>

<variable name="City"/>

</write>

 

<write if-variable-set="URL">

<text value=", "/>

<variable name="URL" url-name="URL"/>

</write>

 

<write>

<text value="."/>

</write>

<finish/>

</xi>

If written in English, the first few commands of this would be: set a new Id variable with the value of the Number variable. Set the separator for writing names to “ and ”. If the bibliography is not being formatted as a list, write the value of Id followed by a period and a space. If the Title variable is set, write its value in an italic font. If the Book variable is set, write a comma and then the value. If the Author variable is set, write a comma and then the names as “Surname1, Forenames1 and Surname2, Forenames2”, in a bold font.

XML syntax is fairly simple: there are tags enclosed with angle brackets, such as write and set, which must be terminated with another tag containing the same name preceded by a slash, or by self-terminating the same tag with a slash. If you miss out a tag terminator, you will get an error message. Tags can be nested, where appropriate.

Tags can have attributes, in the form name="value", and you can add comments between <!-- ... --> tags. And that’s about it for the basic XML syntax. Jutoh’s formatting language is all couched in this syntax.

Constructs

These are the constructs you can use in Xi.

if

You can use if to test for a condition and then execute alternate commands. You can add two or three elements between the start and end if tags: cond (a condition), then (a sequence of commands), and optionally else for an alternative sequence of commands if the test fails.

For example:

<if>

<cond>

<and>

<variable-eq name="FormatAsList" value="1"/>

<variable-eq name="Type" value="Article"/>

</and>

</cond>

<then>

<write><text value="An article in a list"/></write>

</then>

<else>

<write><text value="Not an article or not a list"/></write>

</else>

</if>

The condition here contains an and which takes two boolean expressions; you can also use or, not, eq, neq, variable-eq, variable-neq, and variable. The latter takes a name attribute and returns a value that you can use in a condition.

There are attributes in the write command that are more succinct equivalents to using if, but sometimes if is needed when a whole block of commands is conditional.

finish

This command is used to terminate the template immediately and avoid further unnecessary tests. It is not essential to use this.

set

This command sets a variable to a text value or the value of a different variable, for example:

<set name="Id" value-of="Number"/>

<set name="PersonSeparator" value=" and "/>

The first set command sets a new variable Id to the value of the Number variable, which contains the position of the current item in the bibliography list.

The second set command sets the value a variable which is used to tell Jutoh how to separate a list of names, for example if there are multiple authors.

write

This command writes text or variable values to the bibliography. Two further tags can be nested within write: text and variable. The text tag takes a value attribute with the text to write, and variable takes a name attribute for the variable whose value should be written.

The write command can take the following attributes.

if-variable-set: if the value of the specified field is empty, the write command is not executed.

if-variable-eq: if the value of the specified field is the same as the value attribute, the write command is executed.

if-variable-neq: if the value of the specified field is not the same as the value attribute, the write command is executed.

attributes: a comma-separated list of attributes to give the content written by this command. The attributes can be a combination of strong, emphasis, underline, caps, smallcaps, superscript, and subscript. Jutoh will add a suitable style to the currently active style sheet.

style: the name of a character style to assign to the content written by this command. The style should exist already.

Note that you can also use attributes and style with individual text and variable tags that you place within the write command.

Using variables

The following variables are available:

You can also set arbitrary variables.

Fields that contain person names can be referenced in various ways by appending a dot and a keyword to the name:

The following fields are available in the standard Jutoh database template. Not all of them will be used for a given source type.

Abbreviated case number, Address, Album title, Annotation, Artist, Author, Book author, Book title, Broadcaster, Broadcast title, Case number, Chapter, City, Compiler, Composer, Conductor, Conference name, Corporate author, Counsel, Country/Region, Court, Custom citation, Day, Day accessed, Department, Director, DOI, Edition, Editor, Institution, Internet site title, Interviewee, Interviewer, Inventor, Issue, Journal, Medium, Month, Month accessed, Note, Number of volumes, Organisation, Pages, Patent number, Patent type, Performer, Producer, Production company, Publisher, Publication title, Publication type, Recording number, Reporter, Report type, Series, Short name, Short title, Standard number, State/Province, Station, Theater, Title, Translator, Type, University, URL, User defined 1, User defined 2, User defined 3, User defined 4, User defined 5, Version, Volume, Writer, Year, Year accessed.

These are the source types (set using the Type field).

Art, Article, Article in conference proceedings, Book, Book excerpt, Brochure, Case, Conference proceedings, Dissertation, Electronic source, Email, Film, In collection, Interview, Journal, Miscellaneous, Patent, Performance, Research report, Sound recording, Technical documentation, Thesis, Unpublished, Web site.

How to edit and use formatting templates

Each project can have one or more formatting templates; however only one can be active at a time. You can create, edit, delete, import and export formatting templates from the Formatting Templates tab under Project Properties/Indexes/Bibliography. It’s easy to test a template in the Formatting Template dialog – edit the test data and press Test to see the formatted item.

The bibliographic formatting template editor

Update the bibliography via Book | Update to reapply the template to the bibliography section.


Contents | Start | End | Previous: Appendix C: The Jutoh Box Model | Next: Appendix E: Speech Markup Reference