Contents | Start | End | Previous: Appendix C: The Jutoh Box Model | Next: Appendix E: Speech Markup Reference
This topic describes the XML-based language that Jutoh uses to format bibliographic items.
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.
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.
In the above example, we output the URL field as a link, courtesy of the url-name attribute which names the field that contains the link. We could also have used url-name with any other field, such as the book title, to make the book title clickable if the URL field is present and contains a value. If you might have multiple links per entry, you could have several link fields in your database, such as Publisher-URL and Book-URL, and you can then use the url-name attribute where appropriate with different values.
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.
The following variables are available:
All fields in the current bibliography item, with a first upper case letter and remaining lower case letters.
Number: the position of the item in the bibliography.
FormatAsList: "1" if the project is formatting the items as a true list, and "0" otherwise.
PersonSeparator: the text to insert between person names. By default this is a semicolon, but you can set it in the template.
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:
Field name.surname: the surname of the first person.
Field name.surnames: the surnames of all people, separated by the value of PersonSeparator.
Field name.forenames: the forenames of the first person.
Field name.surnamefirst: the full name of the first person, surname first.
Field name.surnamelast: the full name of the first person, surname last.
Field name.surnamesfirst: the full names of all people, surname first.
Field name.surnameslast: the full names of all people, surname last.
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.
Each project can have one or more formatting templates; normally, only one can be active at a time, but you can specify the name of the template to be used using the configuration option Bibliography formatting template. 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, using the current configuration’s Bibliography formatting template if specified, or the default template.
Contents | Start | End | Previous: Appendix C: The Jutoh Box Model | Next: Appendix E: Speech Markup Reference