4. Coding your document

Like HTML, XML relies on elements to code up the document. If you are familiar with coding HTML files the transition to XML should be fairly painless. OUCS XML has many elements available for use, although in any one document only a subset of these will ever be applied. In this section we discuss the elements making up the body of a text.

4.1. Sectioning your text

Your text may be just a series of paragraphs, or these paragraphs may be grouped together into chapters, sections, subsections, etc. In the former case, each paragraph is embedded inside a the <p> element. In the latter case, the <body> may be divided into a series of <div> elements, which may be further subdivided. An example of div structure is shown below:

<div>  <head>This is my heading</head>  <p> This is a paragraph</p>  <div>   <head>This is my inner section heading</head>   <p> This is a paragraph in the inner section</p></div> <!--This div closes the inner section--></div> <!--This div formally closes entire section-->

Sectioning your document has important effects on the OUCS web site. Each div used is processed when the document is converted into html. Major divisions are treated as separate web pages and help to form the basis of the internal page navigation system. Each division is also sequentially numbered: 1, 2, 3 ... Where a div section is within another div, it is treated as a subsection and numbered accordingly e.g. 2.1, 2.2, 2.3....

Sectioning documents also influences the HTML output to browsers. The title of a document is always given the <h1> tag, major divisions are thus given the <h2> tag and minor section divisions are given <h3>, <h4>, <h5> etc. depending on how deep they are nested within the document.

Correct structural markup for documentation is important for accessibility. When documents are marked up in a structured way, they allow users of alternative technologies to discover the main sections and subsections more quickly and more easily. The structure allows users to jump from one section to another, without the need to read all of the information on the page. Documents that do not use structured markup pose a problem (to screen reader users in particular), as it is very difficult to find out what is on a page without reading all of the text. Where structural markup has not been used, the author has often employed styles (bold, italic, etc.) to indicate different sections and headings. While obvious to sighted readers, the structure is lost to screen reader users who must read the page to find out if it is of interest to them.

It is a requirement for authors to structure their documents in an accessible manner: relying on style alone is to be avoided as this results in inaccessible documents.

The following elements can be used to divide up your text:

<p>
marks paragraphs in prose.
<div>
contains a subdivision of the front, body, or back of a text.

When structural divisions smaller than a <div> are necessary, inner <div> elements may be used, without limit to the depth of nesting (see example above).

A div element can have the following three attributes:
type
This indicates the conventional name for this category of text division. Its value might be something like ‘Preface’.
id
This specifies a unique identifier for the division, which may be used for cross references or other links to it, such as a commentary. It is often useful to provide an id attribute for every major structural unit in a text, and to derive the id values in some systematic way, for example by appending a section number to a short code for the title of the work in question.
n
The n attribute specifies a mnemonic short name or number for the division, which can be used to identify it in preference to the id. If a conventional form of reference or abbreviation for the parts of a work already exists (such as the book/chapter/verse pattern of Biblical citations), the n attribute is the place to record it.
The attributes id and n, indeed, are so widely useful that they are allowed on any element in any TEI schema: they are global attributes.

The value of every id attribute must be unique within a document. They may be used to derive the names of HTML pages, so giving sensible mnemonic names is a good idea.

4.2. Headings and Closings

Every <div> may have a title or heading, and (less commonly) a closing such as ‘End of Chapter 1’. The following elements may be used to mark them up:
<head>
contains any heading, for example, the title of a section, or the heading of a list or glossary.
<trailer>
contains a closing title or footer appearing at the end of a division of a text.

Here is an example of their use:

<div>  <head>This is my heading</head>  <p>This is the body of the text</p>  <trailer>   <p>This is the trailer to my text</p></trailer></div>

N.B. At present it is not possible to use the <head> tag without using the <div> tag first.

4.3. Marking Highlighted Phrases

4.3.1. Changes of Typeface, etc.

Highlighted words or phrases are those made visibly different from the rest of the text, typically by a change of type font, handwriting style, or ink color, intended to draw the reader's attention to them.

<hi>
marks a word or phrase as graphically distinct from the surrounding text, for reasons concerning which no claim is made.
Code view:
<hi>example</hi>
Rendered view:
example
Alternatively, where the cause for the highlighting can be identified with confidence, a number of other, more specific, elements are available. All but the first two are OUCS extensions to the standard TEI markup.
<emph>
marks words or phrases which are stressed or emphasized for linguistic or rhetorical effect
Code view:
<emph>example</emph>
Rendered view:
example
<term>
contains a single-word, multi-word or symbolic designation which is regarded as a technical term
Code view:
<term>example</term>
Rendered view:
example
<gi>
An SGML, XML or HTML element name
Code view:
<gi>h1</gi>
Rendered view:
<h1>
<Button>
A button which a user can see
Code view:
<Button>Logout</Button>
Rendered view:
Logout
<Code>
Some sort of computer language code
Code view:
<Code>\textbf{a}$^34$</Code>
Rendered view:
\textbf{a}$^34$
<Command>
The name of a command
Code view:
<Command>tcsh</Command>
Rendered view:
tcsh
<Field>
A labelled input field
Code view:
<Field>Subject</Field>
Rendered view:
Subject
<Filespec>
A file or directory specification of any kind
Code view:
<Filespec>C:\Windows\My Documents</Filespec>
Rendered view:
C:\Windows\My Documents
<Icon>
an icon in a GUI
Code view:
<Icon>Notepad</Icon>
Rendered view:
Notepad
<Input>
Text for a user to type
Code view:
<Input>quota</Input>
Rendered view:
quota
<Key>
A key to press
Code view:
<Key>R</Key>
Rendered view:
<R>
<Keyword>
A keyword in some technical code the user is being asked to write
Code view:
<Keyword>font-family</Keyword>
Rendered view:
font-family
<Label>
The label for a button, radio box, etc.
Code view:
<Label>select to activate account</Label>
Rendered view:
select to activate account
<Link>
The text of a link which is being described
Code view:
<Link>IT Information</Link>
Rendered view:
IT Information
<Menu>
A menu item
Code view:
<Menu>Save as</Menu>
Rendered view:
[Save as]
<Output>
What comes back when you give a command
Code view:
<Output>job completed</Output>
Rendered view:
job completed
<Program>
A simple program listing
Code view:
<Program>i:=0;
j:=-1;</Program>
Rendered view:
i:=0; j:=-1;
<Prompt>
A prompt from the computer
Code view:
<Prompt>password:</Prompt>
Rendered view:
password:
<Screen>
A prettified display of text screenshot
Code view:
<Screen>Thanks!
Your work is complete.</Screen>
Rendered view:
Thanks! Your work is complete.
<Software>
The name of a program
Code view:
<Software>Microsoft Word</Software>
Rendered view:
Microsoft Word
<Value>
A possible value for some option
Code view:
<Value>Times-Roman 10pt</Value>
Rendered view:
Times-Roman 10pt
If you ever really need it, the <lb/> element marks the start of a new (typographic) line.

4.4. Cross References and Links

Explicit cross references or links from one point to another in a text in the same XML document may be encoded using the elements described in section 4.4.1. Simple Cross References. References or links to elements of some other XML document, or to parts of non-XML documents, may be encoded using the TEI extended pointers described in section 4.4.2. Extended Pointers.

Accessibility of your links is important. The text you use can either enhance a user's understanding of where the link will lead, or leave them clueless. The worst phrase you can use for a link is Click Here or simply Here: in both instances the user is left with no clear idea of where the link could lead. This problem is compounded for a screen reader user: they can get lists of all links from any given page, but if the author of the page has just said Click Here or Here, they will get a list consisting of just that. The user will be left stranded on the page with no clear way to move forwards in their search for information.

An accessible link is one that conveys both where the link will go and the information the user is likely to find. By default our system will add a title attribute to any link you make on your page when it is transformed into HTML. However, while this is good practice and a nice failsafe measure, it will only add the same text as the link text. This might be adequate in some circumstances, but to make your links more accessible you should add your own additional text using the n attribute. People browsing with modern visual browsers will see your additional link information when they mouse over your link, and screen reader users will have more information about where the link will take them as the title attribute is read out to them.

4.4.1. Simple Cross References

A cross reference from one point to another within a single document can be encoded using either of the following elements:
<ref>
a reference to another location in the current document usually modified by additional text.
<ptr>
a pointer to another location in the current document.
These elements share the following attribute:
target
specifies the destination of the pointer.

The difference between these two elements is that <ptr> is an empty element, simply marking a point from which a link is to be made, whereas <ref> may contain some text as well --- typically the text of the cross-reference itself. The <ptr> element would be used for a cross reference which is indicated by a symbol or icon, or in an electronic text by a button.

The following two forms, for example, are equivalent:

See especially <ref target="SEC12">section 12 on page 34</ref>.
See especially <ptr target="SEC12"/>.
The value of the target attribute must be present in the current XML document. This implies that the passage or phrase being pointed at must bear an identifier, and must therefore be tagged as an element of some kind. In the following example, the cross reference is to a <div> element:
...see especially <ptr target="SEC12"/>.... ... <div id="SEC12">  <head>Concerning Identifiers... </head></div>
The id attribute is global (i.e. can be used on any element), which means all elements in a document can be pointed to in this way. In the following example, a paragraph has been given an identifier so that it may be pointed at:
...this is discussed in <ref target="pspec">the paragraph on links</ref> ...<p id="pspec">Links may be made to any kind of element ...</p>

Sometimes the target of a cross reference does not correspond with any particular feature of a text, and so may not be tagged as an element of some kind. If the desired target is simply a point in the current document, the easiest way to mark it is by introducing an <anchor> element at the appropriate spot.

<ptr target="1234"/>.... ....<anchor id="1234"/>

4.4.2. Extended Pointers

The elements <ptr> and <ref> can only be used for cross-references whose targets occur within the same XML document as their source. They can also refer only to XML elements. The elements discussed in this section are not restricted in these ways.
<xptr>
defines a pointer to another location in the current document or an external document.
<xref>
defines a pointer to another location in the current document or an external document, usually modified by additional text or comment.

In addition to the attributes already discussed in section 4.4.1. Simple Cross References above, these elements share the following additional attribute, which is used to specify the target of the cross reference or link:

url
A Web URL specifying the destination

The following example shows how to link to another page and web site

See local information about <xref url="/email/clients/">email clients</xref> or go to <xptr   url="http://www.google.co.uk"   n="go to Google's web site"/>

The above example renders as follows:

See local information about email clients or go to http://www.google.co.uk

To link to a specific section on another page you should use the following syntax:

<xref url="/matlab/#fault_special">faults, problems, or special requests</xref>

4.5. Addresses

The <address> element is used to mark a postal address of any kind. It contains one or more <addrLine> elements, one for each line of the address.
address
contains a postal or other address, for example of a publisher, an organization, or an individual.
addrLine
contains one line of a postal or other address.
Here is a simple example:
<address>  <addrLine>Oxford University Computing Services</addrLine>  <addrLine>13 Banbury Rd</addrLine>  <addrLine>Oxford</addrLine>  <addrLine>OX2 6NN</addrLine></address>

4.6. Lists

4.6.1. The various kinds of lists

The element <list> is used to mark any kind of list. A list is a sequence of text items, which may be ordered, unordered, or a glossary list. Each item may be preceded by an item label (in a glossary list, this label is the term being defined):
<list>
contains any sequence of items organized as a list. Attributes include:
type
describes the form of the list. This attribute can have the following values:
  • unordered (for lists with bullet-marked items)
  • ordered (for lists with numbered or lettered items)
  • gloss (for lists consisting of a set of technical terms, each marked with a <label> element and accompanied by a gloss or definition marked as an <item>)
If the attribute is omitted, the default is for the list to be an unordered list.
rend
describes how the labels should appear. The rend attribute can have the following values:
  • no-bullets (for producing unordered lists with no bullet points)
  • lower-alpha (for producing ordered lists with labels a, b, c, ...)
  • upper-alpha (for producing ordered lists with labels A, B, C, ...)
  • lower-roman (for producing ordered lists with labels i, ii, iii, ...)
  • upper-roman (for producing ordered lists with labels I, II, III, ...)
If the attribute is omitted, the default is to produce the labels 1, 2, 3, ... (for ordered lists) or plain bullet points (for unordered lists).
<item>
contains one component of a list.
<label>
contains the label associated with an item in a list; in glossaries, marks the term being defined.

Individual list items are tagged with <item>. The first <item> may optionally be preceded by a <head>, which gives a heading for the list. The numbering of a list may be omitted (if reconstructible), indicated using the n attribute on each item, or (rarely) tagged as content using the <label> element. In order to achieve the same result with different browsers, the value of n should be greater than 0.

4.6.2. Examples of lists

Example 1

<list>  <head>An unordered list</head>  <item>First item in list</item>  <item>Second item in list</item>  <item>Third item in list</item></list>

An unordered list

  • First item in list
  • Second item in list
  • Third item in list

Example 2

<list type="ordered">  <head>An ordered list</head>  <item>First item in list</item>  <item>Second item in list</item>  <item>Third item in list</item></list>

An ordered list

  1. First item in list
  2. Second item in list
  3. Third item in list

Example 3

<list type="ordered">  <head>An ordered list with controlled numbering </head>  <item n="3">First item in list</item>  <item>Second item in list</item>  <item>Third item in list</item></list>

An ordered list with controlled numbering

  1. First item in list
  2. Second item in list
  3. Third item in list

Example 4

<list type="orderedrend="lower-alpha">  <head>An ordered list with letters for labels</head>  <item>First item in list</item>  <item>Second item in list</item>  <item>Third item in list</item></list>

An ordered list with letters for labels

  1. First item in list
  2. Second item in list
  3. Third item in list

Example 5

<list type="orderedrend="lower-alpha">  <head>An ordered list with controlled lettering </head>  <item n="9">First item in list</item>  <item>Second item in list</item>  <item>Third item in list</item></list>

An ordered list with controlled lettering

  1. First item in list
  2. Second item in list
  3. Third item in list

Example 6

<list type="gloss">  <head>A glossary list</head>  <label>One</label>  <item>First item in list</item>  <label>Two</label>  <item>Second item in list</item>  <label>Three</label>  <item>Third item in list</item></list>

A glossary list

One
First item in list
Two
Second item in list
Three
Third item in list

The styles should not be mixed in the same list.

Example 7

A simple two-column table may be treated as a glossary list, tagged <list type=gloss>. Here, each item comprises a term and a gloss, marked with <label> and <item> respectively.

<list type="gloss">  <head>Vocabulary</head>  <label>nu</label>  <item>now</item>  <label>lhude</label>  <item>loudly</item>  <label>bloweth</label>  <item>blooms</item>  <label>med</label>  <item>meadow</item>  <label>wude</label>  <item>wood</item>  <label>awe</label>  <item>ewe</item>  <label>lhouth</label>  <item>lows</item>  <label>sterteth</label>  <item>bounds, frisks</item>  <label>verteth</label>  <item lang="lat">pedit</item>  <label>murie</label>  <item>merrily</item>  <label>swik</label>  <item>cease</item>  <label>naver</label>  <item>never</item></list>

The above is rendered as follows:

Vocabulary

nu
now
lhude
loudly
bloweth
blooms
med
meadow
wude
wood
awe
ewe
lhouth
lows
sterteth
bounds, frisks
verteth
pedit
murie
merrily
swik
cease
naver
never

4.6.3. Nested lists

Lists of whatever kind can, of course, nest within list items to any depth required. Here, for example, a glossary list contains two items, each of which is itself a simple list:

<list type="gloss">  <label>EVIL</label>  <item>   <list type="simple">    <item>I am cast upon a horrible desolate island, void of all hope of        recovery.</item>    <item>I am singled out and separated as it were from all the world to be        miserable.</item>    <item>I am divided from mankind &amp;#8212; a solitaire; one banished from        human society.</item></list> <!-- end of first nested list --></item>  <label>GOOD</label>  <item>   <list type="simple">    <item>But I am alive; and not drowned, as all my ship's company were.</item>    <item>But I am singled out, too, from all the ship's crew, to be spared from        death...</item>    <item>But I am not starved, and perishing on a barren place, affording no        sustenances....</item></list> <!-- end of second nested list --></item></list> <!-- end of glossary list -->

The above is rendered as follows:

EVIL
  • I am cast upon a horrible desolate island, void of all hope of recovery.
  • I am singled out and separated as it were from all the world to be miserable.
  • I am divided from mankind - a solitaire; one banished from human society.
GOOD
  • But I am alive; and not drowned, as all my ship's company were.
  • But I am singled out, too, from all the ship's crew, to be spared from death...
  • But I am not starved, and perishing on a barren place, affording no sustenances....

4.7. Tables

The following elements are provided for describing tables:
<table>
contains text displayed in tabular form, in rows and columns.
<row>
contains one row of a table. Attributes include:
role
indicates the kind of information held in the cells of this row. This attribute should have the value label for labels or descriptive information, and data for actual data values. If omitted, it defaults to data.
<cell>
contains one cell of a table. Attributes include:
role
indicates the kind of information held in the cell. This attribute should have the value label for labels or descriptive information, and data for actual data values. If omitted, it defaults to data.
cols
indicates the number of columns occupied by this cell. If omitted, it defaults to 1.
rows
indicates the number of rows occupied by this cell. If omitted, it defaults to 1.

The <table> element can also take the align, summary, width, border, frame, rules, cellspacing and cellpadding attributes defined in HTML, and the conversion to HTML will pass them straight through.

4.7.1. Making your table accessible

Caution is advised when using tables as it is very easy to make them inaccessible to users of alternative technologies e.g. screen readers. It is your responsibility to make sure that any table used is comprehensible when it is linearised and that it contains suitable accessibility attributes.

Screen readers linearise tables when they are reading the content out to the user. This means that if you have failed to take this into account when designing your table, the screen reader user will not understand the content of your table. To check to see how your table will be read out, go to http://wave.webaim.org/. Run your page containing the table through this online checker. It will show you how the table will be read to a screen reader user.

All tables should be given the summary attribute regardless of whether they are for data or page layout. For data tables a short summary of the table content must be added for accessibility. Where a table is used for layout, the summary attribute is included, but left empty.

Here is an example:

<table>  <head>table shows the rise and fall of mortality figures during the plague</head>  <row role="label">   <cell/>   <cell cols="3">years</cell></row>  <row role="label">   <cell/>   <cell>1</cell>   <cell>2</cell>   <cell>3</cell></row>  <row>   <cell role="label">St. Leonard's, Shoreditch</cell>   <cell>64</cell>   <cell>84</cell>   <cell>119</cell></row>  <row>   <cell role="label">St. Botolph's, Bishopsgate</cell>   <cell>65</cell>   <cell>105</cell>   <cell>116</cell></row>  <row>   <cell role="label">St. Giles's, Cripplegate</cell>   <cell>213</cell>   <cell>421</cell>   <cell>554</cell></row></table>

The above is rendered as:

Table 1. table shows the rise and fall of mortality figures during the plague
years
123
St. Leonard's, Shoreditch 64 84 119
St. Botolph's, Bishopsgate 65 105 116
St. Giles's, Cripplegate 213 421 554

4.7.2. Making your table sortable

4.7.2.1. Normal use

If a <table> element has a rend attribute with the value tablesorter, the table will be rendered with the cells of the first column sorted and with buttons on each column that enable the person viewing the page to sort the table on another column.

<table rend="tablesorter"> ... </table>

Here is an example of what can be done:

Table 2. table shows a use of the tablesorter rend (derived from an example at http://tablesorter.com/docs/)
First Name   Last Name   Age   Total   Discount   Difference   Date and timeISOUK 1UK 2
Peter Parker 28 £9.99 20.9% +12.1 Sep 9, 2002 8:14 AM 2002-09-09 09-09-2002 09/09/2002
John Good 33 £19.99 125% +12 Jan 12, 2003 5:14 AM 2003-01-12 12-01-2003 12/01/2003
Clark Kent 18 £15.89 44% -26 Jan 18, 2001 11:14 AM 2001-01-18 18-01-2001 18/01/2001
Bruce Almighty 45 £153.19 44.7% +77 Sep 10, 2002 9:12 AM 2002-09-10 10-09-2002 10/09/2002
Bruce Evans 22 £13.19 11% -100.9 Sep 1, 2002 9:12 AM 2002-09-01 01-09-2002 01/09/2002

The above can be achieved using the following TEI:

<table rend="tablesorter">  <head>table shows a user of the tablesorter rend (derived from an example at http://tablesorter.com/docs/)</head>  <row role="label">   <cell>First Name&amp;#160;&amp;#160;&amp;#160;</cell>   <cell>Last Name&amp;#160;&amp;#160;&amp;#160;</cell>   <cell>Age&amp;#160;&amp;#160;&amp;#160;</cell>   <cell>Total&amp;#160;&amp;#160;&amp;#160;</cell>   <cell>Discount&amp;#160;&amp;#160;&amp;#160;</cell>   <cell>Difference&amp;#160;&amp;#160;&amp;#160;</cell>   <cell>Date and time</cell>   <cell>ISO</cell>   <cell>UK 1</cell>   <cell>UK 2</cell></row>  <row>   <cell>Peter</cell>   <cell>Parker</cell>   <cell>28</cell>   <cell>£9.99</cell>   <cell>20.9%</cell>   <cell>+12.1</cell>   <cell>Sep 9, 2002 8:14 AM</cell>   <cell>2002-09-09</cell>   <cell>09-09-2002</cell>   <cell>09/09/2002</cell></row>  <row>   <cell>John</cell>   <cell>Good</cell>   <cell>33</cell>   <cell>£19.99</cell>   <cell>125%</cell>   <cell>+12</cell>   <cell>Jan 12, 2003 5:14 AM</cell>   <cell>2003-01-12</cell>   <cell>12-01-2003</cell>   <cell>12/01/2003</cell></row>  <row>   <cell>Clark</cell>   <cell>Kent</cell>   <cell>18</cell>   <cell>£15.89</cell>   <cell>44%</cell>   <cell>-26</cell>   <cell>Jan 18, 2001 11:14 AM</cell>   <cell>2001-01-18</cell>   <cell>18-01-2001</cell>   <cell>18/01/2001</cell></row>  <row>   <cell>Bruce</cell>   <cell>Almighty</cell>   <cell>45</cell>   <cell>£153.19</cell>   <cell>44.7%</cell>   <cell>+77</cell>   <cell>Sep 10, 2002 9:12 AM</cell>   <cell>2002-09-10</cell>   <cell>10-09-2002</cell>   <cell>10/09/2002</cell></row>  <row>   <cell>Bruce</cell>   <cell>Evans</cell>   <cell>22</cell>   <cell>£13.19</cell>   <cell>11%</cell>   <cell>-100.9</cell>   <cell>Sep 1, 2002 9:12 AM</cell>   <cell>2002-09-01</cell>   <cell>01-09-2002</cell>   <cell>01/09/2002</cell></row></table>
4.7.2.2. Customising tablesorter

There are two ways in which the use of tablesorter can be customised. You will also find the documentation for tablesorter useful.

4.7.2.2.1. Customising tablesorter: for specific tables

This is appropriate if you want to do your own customisation of tablesorter for specific tables that occur in a TEI file.

In the teiHeader of the TEI file, you provide JavaScript like the following:

<html:script type="text/javascript"> var someOtherTextExtraction = function(node) { var anchortext = node.innerHTML.indexOf("--anchor--"); if ( anchortext == -1 ) { return node.innerHTML; } else { return node.innerHTML.substring(anchortext + 15); } } $(document).ready(function() { $table = $(".tablesorternoinitcode").tablesorter( {dateFormat: 'uk', sortList: [[0,0]], textExtraction: someOtherTextExtraction} ); } ); </html:script>

And you alter the table to have the following rends:

<table rend="tablesorter tablesorternoinitcode"> ... </table>

Gotcha: if you do provide a <html:script> element, remember to define the html namespace. For more details, see the section of this document labelled Using HTML elements in a TEI file.

The above assumes you want to do the same initialisation code for each table. If you want different initialisation code for some of the tables, add another value to the rend attribute of each table:

<table   rend="tablesorter tablesorternoinitcode tableone"> ... </table>

and refer to this value (rather than tablesorternoinitcode) in the initialisation code:

$table = $(".tableone").tablesorter(

The tablesorternoinitcode must still be present in the rend. It is being used to indicate that you do not want the XSL to generate the default initialisation code.

4.7.2.2.2. Customising tablesorter: for all tables of a site

This is appropriate if you want a micro site to have full control of the customisation of tablesorter.

The file oucsstandard.xsl has the following definition for the template outputTableSorterInitCode. In the XSL for the micro site, you define a template that overrides this.

<xsl:template name="outputTableSorterInitCode"> <script type="text/javascript"> var GTSTextExtraction = function(node) { var anchortext = node.innerHTML.indexOf("--anchor--"); if ( anchortext == -1 ) { return node.innerHTML; } else { return node.innerHTML.substring(anchortext + 15); } } $(document).ready(function() { $table = $(".tablesorter:not(.tablesorternoinitcode)").tablesorter( {dateFormat: 'uk', sortList: [[0,0]], textExtraction: GTSTextExtraction} ); } ); </script> <xsl:call-template name="outputLinebreak"/> </xsl:template>

4.8. Figures and Graphics

Not all the components of a document are necessarily textual. The most straight forward text will often contain diagrams or illustrations, to say nothing of documents in which image and text are inextricably intertwined, or electronic resources in which the two are complementary. This poses accessibility issues for users who cannot see the images. What are they? Are they important to the text, or just page decoration? Is the image a graph or simple picture? Has the author provided extra information about the graphic for those that cannot see it? If you do not provide alternative text for graphics or other accessibiity features in the page coding, the page will be inaccessible to some visitors.

The following tags and attributes are used to add images to web pages:

<figure>
marks the spot at which a graphic is to be inserted in a document. Attributes include:
url
The location and file name of a graphic.
width
The width to which the graphic should be scaled. If omitted, it defaults to the width of the graphic.
height
The height to which the graphic should be scaled. If omitted, it defaults to the height of the graphic.
scale
The extent which the graphic should be scaled (eg 0.5). If omitted, it defaults to 1.
<figDesc>
contains a textual description of the appearance or content of a graphic, essential for accessible graphics.

A picture is inserted into a document using the url attribute of the <figure> element:

<figure url="fezziPic.png">  <head>Mr Fezziwig's Ball</head>  <figDesc>A Cruikshank engraving showing Mr Fezziwig leading a group of    revellers.</figDesc></figure>

Usually, a graphic will have at the least an identifying title, which should be encoded using the <head> element. Images which are given a head tag have this text automatically converted to a figure caption and are numbered sequentially throughout the document. It is also essential to include a brief description of the image using <figDesc>. If the image is difficult to describe in just a few words, you should provide an alternative page where a full account of the image can be given to the user: this extra information should be provided via a [d] link. These are normal url links to normal web pages. By convention the [d] link should be provided next to the image in question; users needing greater detail about a given image will click on the [d] link for more information.

If the image is for decoration only (very rare on OUCS pages), it is still necessary to include the <figDesc> element in your document, but in this case it should be left blank. By convention the image is then considered just page decoration and unimportant to the reader.

If you want to control the way text flows around an image, use a rend value, as described in the Rends section.

4.9. Getting a TEI file to display a newsfeed

A newsfeed can be displayed by putting a <xptr> element with a rend of rss and a type of transclude inside a <p> element. The url attribute has the URL of the newsfeed. Our XSL can cope with newsfeeds written in RSS 2.0, RSS 1.0 and Atom 1.0.

<p> <xptr rend="rss" type="transclude" url="http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml" /> </p>

This will produce output like the following:

Commonwealth Games begin in GlasgowThe 2014 Commonwealth Games opening ceremony is under way at Celtic Park in Glasgow.
PM to check arms export licencesDavid Cameron vows to examine outstanding licences for the sale of arms to Russia after claims by MPs that they could breach the terms of an embargo.
Solemn ceremony for MH17 victimsThe Netherlands receives the first victims' bodies from crashed Malaysia Airlines flight MH17 in a solemn ceremony at Eindhoven air base.
Hamas ties ceasefire to blockadeHamas leader Khaled Meshaal says there can be no ceasefire in Gaza without an end to Israel's economic blockade, as fighting continues in Gaza.
Police 'spied on dead man's family'A woman calling for an inquiry into her son's death in 1997 says she has been told she was spied on by undercover police officers.
Character actress Dora Bryan diesDora Bryan, the actress whose career encompassed theatre, film and TV's Last of the Summer Wine, has died near Brighton at the age of 91.
Dozens killed in Taiwan plane crashMore than 40 people were killed when a TransAsia Airways passenger plane crashed after making a failed emergency landing in Taiwan, local officials say.
Geldof died of heroin overdoseTV presenter Peaches Geldof died of a heroin overdose after relapsing from a period of abstinence, a coroner rules.
Baby P boss awarded £680,000 payoutThe former head of Haringey children's services Sharon Shoesmith is awarded almost £680,000 following her unfair dismissal claim.
Man arrested in missing Claudia caseA man is arrested as part of the investigation into the murder of missing chef Claudia Lawrence, while forensic teams search a pub in York.

By default, 10 items of the feed will get output together with an RSS icon that allows people to subscribe to the newsfeed.

Gotcha: the web page will not change when new items get added to the feed unless you arrange for your page not to be cached by AxKit. Please contact webmaster@oucs.ox.ac.uk to get this done.

4.9.1. rsssummary gives a different style of output

Other components can be added to the rend to control what gets output and how it gets output.

A different style of output is delivered if you add rsssummary to the rend:

<p> <xptr rend="rss rsssummary" type="transclude" url="http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml" /> </p>

This will produce output like the following:

Commonwealth Games begin in GlasgowThe 2014 Commonwealth Games opening ceremony is under way at Celtic Park in Glasgow.
PM to check arms export licencesDavid Cameron vows to examine outstanding licences for the sale of arms to Russia after claims by MPs that they could breach the terms of an embargo.
Solemn ceremony for MH17 victimsThe Netherlands receives the first victims' bodies from crashed Malaysia Airlines flight MH17 in a solemn ceremony at Eindhoven air base.
Hamas ties ceasefire to blockadeHamas leader Khaled Meshaal says there can be no ceasefire in Gaza without an end to Israel's economic blockade, as fighting continues in Gaza.
Police 'spied on dead man's family'A woman calling for an inquiry into her son's death in 1997 says she has been told she was spied on by undercover police officers.
Character actress Dora Bryan diesDora Bryan, the actress whose career encompassed theatre, film and TV's Last of the Summer Wine, has died near Brighton at the age of 91.
Dozens killed in Taiwan plane crashMore than 40 people were killed when a TransAsia Airways passenger plane crashed after making a failed emergency landing in Taiwan, local officials say.
Geldof died of heroin overdoseTV presenter Peaches Geldof died of a heroin overdose after relapsing from a period of abstinence, a coroner rules.
Baby P boss awarded £680,000 payoutThe former head of Haringey children's services Sharon Shoesmith is awarded almost £680,000 following her unfair dismissal claim.
Man arrested in missing Claudia caseA man is arrested as part of the investigation into the murder of missing chef Claudia Lawrence, while forensic teams search a pub in York.

4.9.2. rsslimit-all outputs all items and rssnoimage omits the RSS icon

Suppose you want all the items of the feed to be output but you do not want the RSS icon:

<p> <xptr rend="rss rssnoimage rsslimit-all" type="transclude" url="http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml" /> </p>

This will produce output like the following:

Commonwealth Games begin in GlasgowThe 2014 Commonwealth Games opening ceremony is under way at Celtic Park in Glasgow.
PM to check arms export licencesDavid Cameron vows to examine outstanding licences for the sale of arms to Russia after claims by MPs that they could breach the terms of an embargo.
Solemn ceremony for MH17 victimsThe Netherlands receives the first victims' bodies from crashed Malaysia Airlines flight MH17 in a solemn ceremony at Eindhoven air base.
Hamas ties ceasefire to blockadeHamas leader Khaled Meshaal says there can be no ceasefire in Gaza without an end to Israel's economic blockade, as fighting continues in Gaza.
Police 'spied on dead man's family'A woman calling for an inquiry into her son's death in 1997 says she has been told she was spied on by undercover police officers.
Character actress Dora Bryan diesDora Bryan, the actress whose career encompassed theatre, film and TV's Last of the Summer Wine, has died near Brighton at the age of 91.
Dozens killed in Taiwan plane crashMore than 40 people were killed when a TransAsia Airways passenger plane crashed after making a failed emergency landing in Taiwan, local officials say.
Geldof died of heroin overdoseTV presenter Peaches Geldof died of a heroin overdose after relapsing from a period of abstinence, a coroner rules.
Baby P boss awarded £680,000 payoutThe former head of Haringey children's services Sharon Shoesmith is awarded almost £680,000 following her unfair dismissal claim.
Man arrested in missing Claudia caseA man is arrested as part of the investigation into the murder of missing chef Claudia Lawrence, while forensic teams search a pub in York.
Arrests made after eBay Stubhub theftsArrests are made in the UK, US, Canada and Spain after a scam involving e-tickets for Elton John concerts and other shows sold via Stubhub.
Suspected Auschwitz guard dies in USJohann Breyer, 89, has died awaiting extradition to Germany amid allegations he committed Nazi war crimes during World War Two.
VIDEO: Pupils confuse Merkel with the QueenIndian and Kenyan school pupils explain what they understand about the Commonwealth Games and tried to identify the Royal family.
VIDEO: Mayfly swarm fools radarMillions of mayflies took to the air in Wisconsin, tricking radar into thinking it was raining
VIDEO: Amur leopards born at zooA pair of Amur leopards, which are said to be the rarest big cats in the world, have been born in Leicestershire.
VIDEO: Is this the most ridiculous kit ever?Spanish second tier side Cultural Leonesa have revealed their new kit for the forthcoming season - a black and white shirt designed to look like a tuxedo.
VIDEO: Would you eat a 'waste' food curry?Adam Smith set up the UK's first cafe which serves only waste, or "intercepted", food.
VIDEO: Giant puppet creator on Liverpool showGiant puppets are set to roam the streets of Liverpool as part of the World War One centenary. Writer and director Jean-Luc Courcoult explains how his characters come to life.
VIDEO: Mystery over Brooklyn Bridge flagsAuthorities in New York are investigating who raised two large white flags on the towers of the Brooklyn Bridge early on Tuesday.
VIDEO: Student texts make fly on wall TV showBBC Click's Spencer Kelly goes behind the scenes of the TV programme The Secret Lives of Students.
Indian boy has 232 teeth removedDoctors in India extract 232 teeth from the mouth of a 17-year-old boy in a seven-hour operation.
Commonwealth edged out of BookerCommonwealth writers are sidelined from the Man Booker Prize longlist with US authors, including Joshua Ferris and Richard Powers, included for the first time.
Five names to inspire at Glasgow 2014From a cyclist who lost 60 of his family in the Rwandan genocide to a Pakistani squash player who pretended she was a boy.
Mexico back on Formula 1 calendarMexico returns to the Formula 1 calendar after a 23-year absence in 2015 at the Autodromo Hermanos Rodriguez in Mexico City.
Davies completes Tottenham switchSwansea full-back Ben Davies and goalkeeper Michel Vorm join Tottenham as Gylfi Sigurdsson makes Liberty Stadium switch.
Sri Lanka cyclists spotted on motorwayFour members of Sri Lanka's Commonwealth Games team are stopped by police for cycling down a Glasgow motorway.
Man City racism claim 'baseless'Manchester City's claim a player was racially abused in an Under-21 game is "baseless", say the Croatian club City walked off against.
Ban on flights to Tel Aviv renewedThe suspension of US and European airline flights to Israel's Ben Gurion airport after a nearby rocket attack has been extended for a second day.
VIDEO: Apple profits up on iPhone salesApple reports quarterly profits of $7.75bn up 12%, helped by strong sales of its iPhone.
PM won't pay back tennis donationDavid Cameron rejects calls to pay back a donation to the Conservatives by the wife of a former Putin minister, insisting she was not a "crony" of the Russian president.
VIDEO: 'No arms sent to Russian forces'The Defence Secretary Michael Fallon has insisted that Britain is not supplying Russia with military equipment.
NHS 'should work more with hospices'Hospices could play a greater role in end-of-life care and stop hospitals being the "default option", says former Tory party leader Lord Howard.
VIDEO: Healthy start for newbornsA new study shows that newborn babies can reap the health benefits of a delay in cutting their umbilical cord - whilst they're safe in their mothers' arms.
Priority school places plan for poorSchools in England could be allowed to offer priority places to the poorest children in their area under proposals put forward by the government.
Tor creator works to debug dark webOne of the co-creators of Tor says he is working with others to tackle a "bug" that undermines the anonymity offered by the dark web system.
VIDEO: A TV world without personality?Kevin Spacey's series House of Cards is a prime example of how the broadcasting world is changing. But will a world of on demand TV be devoid of passion and personality. BBC Newsnight's David Grossman reports.
Fur seals feel climate impactsChanges in the Antarctic climate are showing up in the fur seal population, say scientists who have studied the animals for 30 years on the British Overseas Territory of South Georgia.
VIDEO: Drones homing in on wildlife poachersCivilian drones are being tested across Africa's game reserves in a hi-tech battle with poachers threatening the continent's wildlife tourism industry.
Paedophile singer appeal bid refusedJudges throw out an appeal by paedophile rock star Ian Watkins to reduce the length of his jail term for child sex offences.
AUDIO: Neighbours's first indigenous actorSusan Bower, former executive producer at Neighbours and the University of Melbourne's Angeline Ferdinand discuss Neighbours's first indigenous actor.
Five ways Aldi cracked the supermarket businessKarl Albrecht, co-founder of the German discount supermarket chain, has died.
Is it worth lightning-proofing homes in the UK?When is it worth installing a lightning rod?
Death crash girl, 6, identifiedA six year-old girl who died in a road accident in Wiltshire is formally identified as Jess Marie Wright-Roberts.
Man fined for downing goldfish drinkA man filmed swallowing two goldfish in a pint glass as part of a dare, admits it was a "stupid prank" after he was fined £200 by magistrates.
Four die as lorry and car crashA couple and their two young children die after crash between a car and a lorry on the A801 near Polmont.
River rescue boy dies in hospitalPolice release the name of a 10-year-old boy who died after getting into difficulties in a river in Argyll.
Stormont paper sets out budget cutsThe finance minister has circulated a paper which will result in millions of pounds in cuts across departments, except health and education, according to Stormont sources.
Man shot in legs 'by appointment'A man who was injured in a gun attack in Londonderry was "shot by appointment", says a DUP MLA.
Boxer 'let down' over Games rulingA Welsh boxer refused a Commonwealth Games place over her involvement in kick boxing says she is disappointed in the sport's authorities.
Town ban 'violates golfer's rights'A ban preventing a golfer from returning to his home town after a car crash which killed a lecturer has been ruled unlawful.
Two deadly blasts hit Nigerian cityTwo blasts targeting an opposition leader and an Islamic cleric have hit the Nigerian city of Kaduna, killing at least 40 people, police say.
Somali musician-MP is shot deadPopular Somali musician and member of parliament Saado Ali Warsame is shot dead by Islamist militants in the capital, Mogadishu.
India MPs 'force-fed' Muslim workerBoth houses of India's parliament are adjourned in uproar after reports that some Hindu MPs tried to forcibly feed a Muslim man fasting for Ramadan.
S Korea ferry boss 'hid in closet'The fugitive South Korean tycoon wanted in connection with the Sewol ferry disaster hid in a closet to evade arrest during a police raid, prosecutors say.
Bulgarian prime minister resignsThe embattled Socialist prime minister of Bulgaria resigns after only a year in office to allow for an early election on 5 October.
Costa Concordia heads for scrapyardThe wreck of the Italian cruise ship Costa Concordia is being towed away for scrap, in one of the biggest maritime salvage operations ever staged.
Colombian army kills ELN rebelsThe Colombian armed forces kill eight rebels from the left-wing National Liberation Army in an operation in eastern Arauca province.
Non-stop Argentina debt talks demandA US judge orders Argentina and its creditors to meet "continuously" to avoid the nation defaulting on its debts later this month.
Suicide car bomb kills 21 in IraqA suicide car bomb has killed at least 21 people at a police checkpoint in Baghdad's Kadhimiya district, Iraqi police say.
France jails pro-Palestinian riotersA French court jails three young men for rioting after a pro-Palestinian demonstration in a mixed suburb of Paris degenerated into anti-Semitic violence.
Detroit porch shooting trial opensA Detroit man feared for his life before he shot an unarmed black woman standing on his porch, his lawyer says at the start of his murder trial.
Loud welcome for loud US touristsThe business community in a County Kerry village hits back at a cafe owner who has refused to serve "loud Americans".
'Feeble' EU and UK 'hypocrisy' - the papersClaims that European leaders are not being strict enough with Moscow over arms supplies feature on front pages - along with rebuttals from France.
Day in pictures: 22 July 201424 hours of news photos: 22 July
Prince George's first yearPrince George's first year
In pictures: Royal first birthdaysA long line of royal baby photos
In pictures: One man's HIV campaignAn Indonesian prisoner's campaign against HIV
Day in pictures: 21 July 201424 hours of news photos: 21 July
In pictures: India's 'original conservationists'The 'original conservationists' of India's tree-loving tribe
In pictures: Gaza conflictMost intense shelling since the launch of Israel's offensive
In pictures: James Garner's careerCareer of American actor James Garner, who has died at the age of 86
VIDEO: House of CommonsIsrael's response to rocket attacks must be "proportionate", insists a minister.
VIDEO: Last journey of Costa ConcordiaThe BBC's Alan Johnston reports on the journey so far of the wrecked cruise ship Costa Concordia as it is towed to Genoa for scrapping.
VIDEO: Red Cross attacked by Gaza civiliansPaul Adams sees a Red Cross evacuation mission come under attack by local people in Gaza City's Shejaiya neighbourhood
VIDEO: Games cyclists find Glasgow bearingsScotland Correspondent Lorna Gordon bumps into some of the team from Swaziland on the streets of Glasgow.
VIDEO: My GlasgowDanny MacAskill rides on Glasgow landmarks, including a breathtaking stunt on the iconic Finnieston Crane.
VIDEO: MH17 bodies arrive in NetherlandsTwo planes carrying bodies from crashed Malaysia Airlines flight MH17 have landed in the Netherlands.
VIDEO: Hundreds die in Syria 'deadliest week'More than 1,700 people have reportedly been killed in seven days as fighting in Syria intensifies.
VIDEO: Dozens killed in Taiwan plane crashMore than 40 people were killed when a TransAsia Airways passenger plane crashed after making a failed emergency landing in Taiwan, local officials say.
VIDEO: Peaches Geldof died of heroin overdosePeaches Geldof died of a heroin overdose, a coroner rules.
Which sport are you made for? Take our testTake our test to see which Commonwealth Games events match your abilities
Obituary: Dora BryanRemembering the talented character actress
How many Greek legends were really true?How spartan were Spartans? Did the Trojans have a horse?
Do four-year-olds need a graduation ceremony?Do four-year-olds need a graduation ceremony?
Is it normal to search envoys?Is it acceptable to search ministers for weapons?
The deaths uniting women across the worldThe deaths that unite women across the world
From an orphanage to entrepreneurFrom living in an orphanage to a self-made millionaire
The curious world of street furnitureThe curious world of England's street furniture
10 theories about the Brooklyn Bridge flags10 theories behind Brooklyn Bridge white flags
Europe's troubles exposed by MH17 crashMH17 crisis exposes EU's own troubles

4.9.3. rsslimit-2 outputs two items and rssbrief just outputs the titles

Suppose you just want the titles and you only want two items output:

<p> <xptr rend="rss rssbrief rsslimit-2" type="transclude" url="http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml" /> </p>

This will produce output like the following:

Commonwealth Games begin in Glasgow
PM to check arms export licences

4.9.4. jsdate-XXXX outputs the date the item was published

If you also want the date when the item was published, you can use:

<p> <xptr rend="jsdate-[d_F_Y] rss rssbrief rsslimit-2" type="transclude" url="http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml" /> </p>

Here the rend attribute has a component that starts with jsdate-. This is followed by some notation (e.g., [d_F_Y]) that indicates how you want the date formatted. It uses the same notation that is used by PHP for its date function with the addition of one character: a _ means generate a space.

The date is output in a <span> that has a class of rssdate and the default CSS hides any such span. So you will also need to define some CSS to ensure the date is displayed:

<html:style type="text/css"> .rssdate { display: inline; padding-left: 10px; } </html:style>

This will produce output like the following:

Commonwealth Games begin in Glasgow
PM to check arms export licences

Here's another example. The TEI elements:

<p> <xptr rend="jsdate-l,_F_jS,_Y rss rssnoimage rsslimit-2" type="transclude" url="http://newsrss.bbc.co.uk/rss/newsonline_uk_edition/front_page/rss.xml" /> </p>

will produce output like the following:

Commonwealth Games begin in GlasgowThe 2014 Commonwealth Games opening ceremony is under way at Celtic Park in Glasgow.
PM to check arms export licencesDavid Cameron vows to examine outstanding licences for the sale of arms to Russia after claims by MPs that they could breach the terms of an embargo.

4.10. Using HTML elements in a TEI file

Although TEI is a rich language so that most of what can be coded in HTML can also be coded in TEI, there are occasions when you may want to use some HTML in a TEI document.

If you wish to do this, you need to introduce a namespace that you can use to say that a particular element belongs to HTML rather than to TEI. Usually, the name html is used for this namespace.

Somewhere you have to indicate which name you are using. Usually, this is done by replacing the first line of the file:
<TEI.2>
by:
<TEI.2 xmlns:html="http://www.w3.org/1999/xhtml">
You can then use an HTML element (e.g., the <style> element) by prefixing its name with the namespace html:
<html:style type="text/css"> .overdue: { background-color: red; } </html:style>
Here is another example:
<html:script type="text/javascript"> var GCS_due_date = ""; ... </html:script>

If you want some HTML elements to appear in the <head> element of the HTML that gets generated, you should put these elements between the <fileDesc> and the <revisionDesc> elements (that appear in the <teiHeader>).

Suppose you do wish to add an HTML <style> element. The rules of HTML say the <style> element must finish up in the <head> element of the resulting HTML. So to achieve this, use something like:
... </fileDesc> <html:style type="text/css"> .overdue: { background-color: red; } </html:style> <revisionDesc> ...

4.11. Forms to collect data and send a message

It is possible to provide a form (in a TEI file) that collects some data from a user and sends that data to someone in an e-mail message. There are details about this in a document on FormMail.

4.12. Accessibility of documentation

Accessibility of our documentation is paramount to ensure documents are accessible to all readers and for OUCS to stay on the correct side of the law. It is necessary for all OUCS authors to familiarise themselves with the ways and means to make their documents as accessible as possible.

Authors need to make sure that they follow the following guidelines:

  • do not make links with the text here or click here, make links that mean something out of context of the sentence they are in. Similarly do not use the same titles for lots of different links on a page when they actually point to different places.
  • When using graphics always provide the <figDesc> element. If necessary go the extra step and make a [d] link for longer explanations of figures
  • When using tables, make sure they are comprehensible when they are linearised. Always include the summary attribute regardless of whether the table is for layout or data. The latter requires you to give some details of the table's content.
  • When you have finished making a web page, you can check its accessibility using online services such as those found in the Complete List of Web Accessibility Evaluation Tools (compiled by the Web Accessibility Initiative (WAI)).

Please use these checkers and make any changes required.

Up: Contents Previous: 3. Getting Started - The Basics Next: 5. Specialised Features