Today, documents are usually prepared electronically using a word processor such as Word or OpenOffice. Such programs allow their users to make good-looking documents easily and quickly. However, there are problems associated with the multitude of different formats and programs used to produce documents. For instance:
OUCS has adopted an open, vendor independent format approach to maintain our documentation in an accessible and interchangeable format. Our system uses XML or eXtensible Markup Language to store documents. XML allows the user to develop their own rules to code up their documents. However, there are already many different versions of XML rules available so we do not need to develop anything new for OUCS. Our system uses a modified version of the Text Encoding Initiative (TEI) XML for writing documentation.
The Text Encoding Initiative (TEI) Guidelines are an international and interdisciplinary standard that enables libraries, museums, publishers, and individual scholars to represent a variety of literary and linguistic texts for online research, teaching, and preservation.
The TEI standard is maintained by a consortium of leading institutions and projects worldwide; Oxford is one of these institutions. Two of the major players in the TEI are members of OUCS: Lou Burnard and Sebastian Rahtz. Lou joined the Text Encoding Initiative project as its European Editor back in 1989 (a post he still holds), while Sebastian is one of the consortium's directors and actively develops the TEI itself.
Since 2002 it has been law to provide documents (including web pages) in accessible formats to users of alternative technologies such as screen readers. The relevant legislation is the Special Educational Needs and Disability Act (SENDA) 2001 which is part 4 of the Disability discrimination Act (DDA). This act brought Education establishments into line with commercial providers in the way that they provide information and services to the disabled community.
The W3C organisation have created various standards for web accessibility. These are:
All OUCS pages should reach level 1 standard. The University has decided that its web sites should ideally conform to the level 2 standard and meet as many level 3 points as possible.
The following document includes details on how to make your XML documents accessible to as wide an audience as possible. Please make sure that you follow these accessibility guidelines - it's the LAW!
The OUCS XML documentation system has six components:
Taking each of these parts in turn:
The rules of the TEI XML format are stored in a schema (we use the RELAXNG schema language) file. This file defines the structure of how XML is to be written and is the key to transforming the text from one format to another. In order to write a valid TEI XML document the schema has to be followed. Luckily there are many XML editors that look after the schema for you and show any errors when the document is tested against the schema.
An XSLT Stylesheet or Extensible Stylesheet Language Transformation Stylesheet is basically a set of rules to process a XML document. It turns an XML rendition of a file into the final version of a file. OUCS uses two versions of XSLT files, one turns an XML file into a web page (HTML format), the other turns XML into PDF format for printing.
CSS or Cascading Style Sheets are files containing information on how a document is to be presented e.g. bold, red headings or grey backgrounds. There are two versions used by OUCS: one displays the XML file directly and is fairly simple; the other displays the final web page and is fairly complex.
There are a few steps that need to be taken before you can get documents up on the web site. These are outlined below:
Before submitting your file to Subversion, you should check your document's syntax. Most XML editors have facilities to check the validity of your document against your schema. Make any corrections necessary before submitting the file to the main Subversion repository. Also bear in mind that your document should be fully accessible and SENDA compliant.
All elements can have additional properties beside the element name and content.
These properties are the attributes of an element and they consist of
name-value pairs. For example a <div> element can have the attribute
id="xxx", where xxx represents a name or number. In the example
id is 'email':
XML is very strict on its element structure, especially compared to HTML. In XML, tags usually have to be started and ended. They must be nested properly and used in the correct place within the document hierarchy. This generally means that you cannot open a new tag e.g. <p> without closing the previous <p> tag. (N.B. there are exceptions to this rule e.g. self-closing tags).
Viewing the OUCS template code in your editor shows the document structure. The complete page structure is shown below:
First comes the declaration that the file is a TEI document <TEI.2>. This is effectively the start tag for the document, all other elements must be correctly arranged or nested inside the <TEI.2> tags for the document to be valid TEI XML.
The first element inside <TEI.2> is the <teiHeader> element. Everything
within this element is part of the document's Metadata (Metadata is data
about the document, e.g. its title, author, creation date etc.). OUCS documents have a
number of fields in the <teiHeader>; some have to be manually completed, such as
the title of the document, while others are automatically added on document submission
Last changed by information. Usually, when writing your own documents,
you should complete the following metadata elements:
It will also be necessary to complete an extra sections in the header recording who is responsible
The end of the metadata is marked by the closing </teiHeader> tag.
After the metadata comes the body of the document. This can be split into three sections:
The majority of OUCS documents only use the body section for the text. This is shown in the next example:... Your text goes in here....
If you do want to include front and/or back additions to your document, the sections are coded in the following manner:Markup for OUCS documents Ian Senior May 2005 Your text goes in here.... Appendix More text in here...
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.
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:This is my heading This is a paragraph This is my inner section heading This is a paragraph in the inner 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:
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).
idattribute for every major structural unit in a text, and to derive the
idvalues in some systematic way, for example by appending a section number to a short code for the title of the work in question.
nattribute 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
nattribute is the place to record it.
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.
Here is an example of their use:This is my heading This is the body of the text This is the trailer to my text
N.B. At present it is not possible to use the <head> tag without using the <div> tag first.
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.
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
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
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
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
attribute is read out to them.
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 section 12 on page 34. See especially .
targetattribute 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 .... ... Concerning Identifiers...
idattribute 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 the paragraph on links ...Links may be made to any kind of element ...
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..... ....
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:
The following example shows how to link to another page and web siteSee local information about email clients or go to
The above example renders as follows:
To link to a specific section on another page you should use the following syntax:faults, problems, or special requests
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>)
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, ...)
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.
Example 1An unordered list First item in list Second item in list Third item in list
An unordered list
Example 2An ordered list First item in list Second item in list Third item in list
An ordered list
Example 3An ordered list with controlled numbering First item in list Second item in list Third item in list
An ordered list with controlled numbering
Example 4An ordered list with letters for labels First item in list Second item in list Third item in list
An ordered list with letters for labels
Example 5An ordered list with controlled lettering First item in list Second item in list Third item in list
An ordered list with controlled lettering
Example 6A glossary list One First item in list Two Second item in list Three Third item in list
A glossary list
The styles should not be mixed in the same list.
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.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
The above is rendered as follows:
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: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....
The above is rendered as follows:
labelfor labels or descriptive information, and
datafor actual data values. If omitted, it defaults to data.
The <table> element can also take the
cellpadding attributes defined in HTML, and the conversion to HTML
will pass them straight through.
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 shows the rise and fall of mortality figures during the plague years 1 2 3 St. Leonard's, Shoreditch 64 84 119 St. Botolph's, Bishopsgate 65 105 116 St. Giles's, Cripplegate 213 421 554
The above is rendered as:
|St. Leonard's, Shoreditch||64||84||119|
|St. Botolph's, Bishopsgate||65||105||116|
|St. Giles's, Cripplegate||213||421||554|
If a <table> element has a
rend attribute with the value
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.
Here is an example of what can be done:
|First Name||Last Name||Age||Total||Discount||Difference||Date and time||ISO||UK 1||UK 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 shows a user of the tablesorter rend (derived from an example at http://tablesorter.com/docs/) First Name    Last Name    Age    Total    Discount    Difference    Date and time ISO UK 1 UK 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
There are two ways in which the use of tablesorter can be customised. You will also find the documentation for tablesorter useful.
This is appropriate if you want to do your own customisation of tablesorter for specific tables that occur in a TEI file.
And you alter the table to have the following rends:...
Gotcha: if you do provide a <html:script> element,
remember to define the
For more details, see the section of this document
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:...
and refer to this value
in the initialisation code:
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.
This is appropriate if you want a micro site to have full control of the customisation of tablesorter.
has the following definition for the template
In the XSL for the micro site, you define a template that overrides this.
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:
0.5). If omitted, it defaults to 1.
A picture is inserted into a document using the
url attribute of the
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.
A newsfeed can be displayed by putting a
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.
This will produce output like the following:
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 firstname.lastname@example.org to get this done.
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
rsssummary to the rend:
This will produce output like the following:
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:
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:
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
This is followed by some notation (e.g.,
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:
_ means generate a space.
The date is output in a <span> that has a class of
and the default CSS hides any such span.
So you will also need to define some CSS to ensure the date is displayed:
This will produce output like the following:
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:
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.
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>).
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.
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:
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.
d] link for longer explanations of figures
summaryattribute regardless of whether the table is for layout or data. The latter requires you to give some details of the table's content.
Please use these checkers and make any changes required.
When an index or table of contents is to be encoded (rather than one being generated) for some reason, the <list> element discussed in section 4.6. Lists should be used.