TEIWiki - User contributions [en]

TEI manuscript catalogues

2017-10-15T13:38:03Z

Lou:

This page is a location to record manuscript catalogues which use TEI as a source, preservation, or output format. Please feel free to add any others that you know of -- Perhaps inserting them alphabetically by name?

----
* '''Name:''' Digital Averroes Research Environment (DARE)
* '''URL:''' http://dare.uni-koeln.de/
* '''Is TEI Available?''' Yes
* '''Description of Catalogue/Project:''' The Digital Averroes Research Environment (DARE) collects and edits the works of the Andalusian Philosopher Averroes or Abū l-Walīd Muḥammad Ibn Aḥmad Ibn Rušd, born in Cordoba in 1126, died in Marrakesh in 1198. DARE makes accessible online digital editions of Averroes's works, and images of all textual witnesses, including manuscripts, incunabula, and early prints. Averroes's writings and the scholarly literature are documented in a bibliographical database.
* '''Notes on use of TEI:''' Bibliographically and structurally, the content of the digital library of Averroes works will be described on the basis of the established standard OAI/PMH and the texts are to be encoded in XML in accordance to the guidelines of the Text Encoding Initiative (TEI P5).
----

----
* '''Name:''' FIHRIST
* '''URL:''' http://www.fihrist.org.uk/
* '''Is TEI Available?''' Yes -- TEI XML download of individual manuscript descriptions
* '''Description of Catalogue/Project:''' The FIHRIST catalogue provides a searchable interface to TEI XML manuscript descriptions from some of the major manuscript collections in the UK. With the continuing contribution of manuscript records from UK libraries, Fihrist aims to become a union catalogue for manuscripts in Arabic script. Partners include: Bodleian Library - University of Oxford, British Library, Cambridge University Library, The Islamic Manuscript Association, The Royal Asiatic Society of Great Britain and Ireland, SOAS - University of London, University of Birmingham, The John Rylands University Library - University of Manchester, Wellcome Library. See http://www.fihrist.org.uk/about for more information.
* '''Notes on use of TEI:''' The FIHRIST Schema was a customisation for Islamic manuscripts based on the [http://code.google.com/p/tei-enrich/ ENRICH TEI ODD customisation for western manuscript description] created for the [http://enrich.manuscriptorium.com/ ENRICH project].
----

----
* '''Name:''' Guide to Medieval and Renaissance Manuscripts in the Huntington Library (2003)
* '''URL:''' http://bancroft.berkeley.edu/digitalscriptorium/huntington/toc.html
* '''Is TEI Available?''' No
* '''Description of Catalogue/Project:''' This static web segment translates the two-volume printed ''Guide'' to TEI-XML and thence to HTML. There is a simple search facility; users are encouraged also to consult the indexes of authors, scribes, artists, places, dates, and titles, which have been converted from print and linked. Since the project doesn't say: it was led by Consuelo Dutschke, with encoding and best-practices contributions by Sharon Goetz and XSL rendering by Liz Shaw.
* '''Notes on use of TEI:''' HEHweb uses a customization of TEI P4 based upon MASTER and TEIMMSS drafts and discussions that were not yet final. Its use of <msDesc> and child elements follows the 1989 printed Huntington catalogue and is a recognizable early cousin of the P5 msDesc module.
----

* '''Name:''' Manuscriptorium
* '''URL:''' http://www.manuscriptorium.com
* '''Is TEI Available?''' Yes
* '''Description of Catalogue/Project:'''... creating a virtual research environment providing access to all existing digital documents in the sphere of historic book resources (manuscripts, incunabula, early printed books, maps, charters and other types of documents). These historical resources, otherwise scattered in various digital libraries around the world, are now available under a single digital library interface.
* '''Notes on use of TEI:''' Uses the TEI P5 Enrich customization with some additional local constraints.
----

----
* '''Name:''' Register of Early Modern Slovenian Manuscripts
* '''URL:''' http://ezb.ijs.si/nrss/
* '''Is TEI Available?''' Yes
* '''Description of Catalogue/Project:''' The web portal presents Slovenian manuscripts from the Baroque and Enlightenment periods. The on-line Register in open access comprises manuscript descriptions of the first 100 manuscripts, researched so far, and 7.000+ digital images. The system, based on Fedora Commons, enables browsing the manuscript descriptions and associated facsimiles, as well as complex searches over structured data, including taxonomies of text types and social contexts (monastic, diocesan, civil etc.) in which the manuscripts came into existence. Even as work in progress, the repository demonstrates the variety and longevity of manuscript culture in early modern period and its important role in Slovenian literature.
* '''Notes on use of TEI:''' No modifications.
----

----
* '''Name:''' Saramusik
* '''URL:''' http://www.saramusik.org
* '''Is TEI Available?''' No
* '''Description of Catalogue/Project: ''' SARAMusiK is an arabic catalogue project of known arabic manuscripts on Music. It is based on different paper catalogues. This catalogue is extented to include a critical edition of the texts.
* '''Notes on use of TEI:''' The main data is filled using a php/mysql database. The body text of the critical edition is stored using the TEI format. All output is in a TEI format.
----

----
* '''Name:''' Syriaca.org
* '''Project Status:''' In development
* '''URL:''' http://www.syriaca.org/
* '''URL:''' https://github.com/srophe/manuscripts/
* '''Is TEI Available?''' Yes -- TEI XML download of the whole repository on [https://github.com/srophe/manuscripts/ github].
* '''Description of Catalogue/Project:''' Syriaca.org is currently in active development. We aim to provide TEI records for Syriac manuscripts and also to serialize our data through RDF using the RDF crosswalks of [http://mesa.performantsoftware.com/ The Medieval Electronic Scholarly Alliance]. Our project is intentionally modeled after the very successul FIHRIST catalogue. We plan to eventually provide a similar searchable interface to TEI XML manuscript descriptions for multiple Syriac holdings at institutions around the world. We are currently actively cataloging the Syriac holdings of the British Library (using Wright's catalogue) and the holdings of American institutions (based on Clemons' checklist).
* '''Notes on use of TEI:''' The Syriaca.org Schema is a customization for Syriac manuscripts based on the [http://www.fihrist.org.uk/ Fihrist Schema], which was itself a customization of [http://code.google.com/p/tei-enrich/ ENRICH TEI ODD customisation for western manuscript description] created for the [http://enrich.manuscriptorium.com/ ENRICH project].
----

----
* '''Name:''' Manuscript database of the Herzog August Bibliothek Wolfenbüttel
* '''URL:''' http://diglib.hab.de/?db=mss
* '''Is TEI Available?''' yes
* '''Description of Catalogue/Project:''' Basically it shall have descriptions of '''all''' manuscripts of the HAB.
* '''Notes on use of TEI:''' The mssDB differentiates between a socalled Signaturdokument (roughly: Shelfmark file) and catalogue(s). The Shelfmark file represents the manuscript itself, containing the most important bits of information on the ms only, <facsimile> and references to descriptions. The descriptions are representations of a (usually printed) catalogue in electronic form thus preserving the historical form and information of that very catalogue entry. We use an ODD based upon the ENRICH ODD, taking it further e.g. by offering value lists on several attributes. The ODD is available at http://diglib.hab.de/rules/schema/ER/v0.4/europeana-regia.xml
----

----
* '''Name:''' e-codices - Virtual Manuscript Library of Switzerland
* '''URL:''' http://www.e-codices.unifr.ch
* '''Is TEI Available?''' yes
* '''Description of Catalogue/Project:''' The goal of e-codices is to provide access to all medieval and selected early modern manuscripts of Switzerland via a virtual library. It contains almost 1000 mss from 42 institutions.
* '''Notes on use of TEI:'''
----

----
* '''Name:''' Beta maṣāḥǝft: Manuscripts of Ethiopia and Eritrea
* '''Project Status:''' in development
* '''URL:'''
* '''Is TEI Available?''' Yes -- TEI XML download of the whole repository on [https://github.com/BetaMasaheft/Manuscripts github]
* '''Description of Catalogue/Project:''' The project Beta maṣāḥǝft: Manuscripts of Ethiopia and Eritrea (Schriftkultur des christlichen Äthiopiens: eine multimediale Forschungsumgebung) is a long-term project funded within the framework of the Academies' Programme (coordinated by the Union of the German Academies of Sciences and Humanities) under survey of the Akademie der Wissenschaften in Hamburg. The funding will be provided for 25 years, from 2016–2040. The project is hosted by the Hiob Ludolf Centre for Ethiopian Studies at the University of Hamburg. It aims at creating a virtual research environment that shall manage complex data related to predominantly Christian manuscript tradition of the Ethiopian and Eritrean Highlands.
* '''Notes on use of TEI:''' [https://github.com/BetaMasaheft/Documentation/wiki/guidelines Project Guidelines Documentation]
----



----
* '''Name:'''
* '''Project Status:''' (e.g. completed, ongoing, in development, no longer actively maintained, etc).
* '''URL:'''
* '''Is TEI Available?'''
* '''Description of Catalogue/Project:'''
* '''Notes on use of TEI:'''
----

[[category:SIG:Manuscripts]]
[[category:Markup]]

ODD

2017-10-02T19:33:41Z

Lou: /* See also */

'''ODD''' stands for "One Document Does it all". It is a TEI XML-conformant specification format that allows one to customize TEI P5 in a [[Wikipedia:literate programming|literate programming]] fashion. It uses elements from the new [http://www.tei-c.org/P5/Guidelines/TD.html Documentation Elements] module.

== Description ==
The TEI Guidelines, its DTD, and its schema fragments, are all produced from a single XML resource containing:

# Descriptive prose (lots of it)
# Examples of usage (plenty)
# Formal declarations for components of the TEI Abstract Model:
## elements and attributes
## modules
## classes and macros

We call this resource an ODD (One Document Does it all), although the master source is instantiated as a gazillion XML mini-documents.

A system of XSLT stylesheets called [[Roma]] has been created for the purpose of easy manipulation of ODD files.

== Example ==
The TEI scheme can only be used by customizing it. Customizations are also expressed in the ODD language. For example:

<pre>
<schemaSpec ident="myTEIlite">
<desc>This is TEI Lite with simplified heads</desc>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef key="linking"/>
<moduleRef key="core"/>
<moduleRef key="header"/>
<elementSpec ident="head" mode="change">
<content><textNode/></content>
</elementSpec>
</schemaSpec>
</pre>

produces a schema a bit like TEI Lite, with a slight change : the element <head> now can contain only text nodes.

== Uses besides the TEI Guidelines and various customizations ==

* [http://www.w3.org/TR/its/ Internationalization Tag Set (ITS)]
* various standards proposal designed within ISO committee TC 37 have been totally or partially written in TEI/ODD: MLIF, MAF, ISO 16642 rev., ISOTimeML

== "Pure ODD" ==

Over the years ODD has evolved in response to the needs of the TEI community, both as the core specification language for the TEI guidelines, and also as a generic customization language. Since 2004, much
effort has been put into making it less of a hybrid language, combining its own vocabulary with RelaxNG fragments and Schematron rules. Versions of TEI P5 later than 2.5 contain elements which can be used to express content models directly in the TEI ODD language, rather than in RELAXNG. ODD is thus an entirely self-contained generic specification language, independent
of other existing grammars, and hence known as Pure ODD. The proposals for Pure ODD were included in the Guidelines during January 2016, and are included as part of the 3.0.0 release

If your existing TEI schema was developed prior to this release, you should probably read up on [http://teic.github.io/TCW/purifyDoc.html How to Update your ODD]

== See also ==
*[http://en.wikipedia.org/wiki/ODD_%28Text_Encoding_Initiative%29 ODD (Text Encoding Initiative)] in Wikipedia
*[[ODD-dev]] Not updated since 2012
*[[ODD chaining]] Not updated since 2012
=== Documentation ===
* [http://www.tei-c.org/Guidelines/Customization/odds.xml Getting Started with P5 ODDs]
* [http://teic.github.io/TCW/howtoGenerate.html How to Make an ODD Automagically]
* [http://teic.github.io/TCW/howtoChain.html ODD chaining for Beginners]
* [http://teic.github.io/TCW/purifyDoc.html How to Update your ODD] (from a pre 3.0 version)
* [http://www.w3.org/TR/xml-i18n-bp/#tei-modularization A fragment of W3C's Best Practices for XML Internationalization concerning ODD customization for the Internationalization Tag Set (ITS).]
* [[Mapping ODD processing]]

=== Presentations ===
*[http://tei.oucs.ox.ac.uk/Oxford/2007-02-13-oucs/talk-odds.xml A talk about the ODD system], given on 13 Feb 2007 by Lou Burnard and Sebastian Rahtz at the OUCS ''Encoding Digital Texts'' workshop
*[http://tei.oucs.ox.ac.uk/Oxford/2006-09-methNet/Talks/RomaJourney.ppt A PowerPoint presentation on TEI/ODD] by Laurent Romary; OUCS, September 2006
*[http://www.balisage.net/Proceedings/vol7/html/Banski01/BalisageVol7-Banski01.html Literate serialization of linguistic metamodels] by Piotr Bański, Balisage-2011

=== Articles ===
* [http://jtei.revues.org/842 Resolving the Durand Conundrum], by Lou Burnard
* [http://conferences.idealliance.org/extreme/html/2004/Bauman01/EML2004Bauman01.html Odd Customizations], by Syd Bauman and Julia Flanders.
* [http://conferences.idealliance.org/extreme/html/2004/Burnard01/EML2004Burnard01.html RelaxNG with Son of ODD], by Lou Burnard and Sebastian Rahtz.
* [http://www.balisage.net/Proceedings/vol1/html/Bauman01/BalisageVol1-Bauman01.html Freedom to Constrain] by Syd Bauman

[[Category:Customization|!]]

ODD

2017-10-02T19:32:33Z

Lou: /* See also */

'''ODD''' stands for "One Document Does it all". It is a TEI XML-conformant specification format that allows one to customize TEI P5 in a [[Wikipedia:literate programming|literate programming]] fashion. It uses elements from the new [http://www.tei-c.org/P5/Guidelines/TD.html Documentation Elements] module.

== Description ==
The TEI Guidelines, its DTD, and its schema fragments, are all produced from a single XML resource containing:

# Descriptive prose (lots of it)
# Examples of usage (plenty)
# Formal declarations for components of the TEI Abstract Model:
## elements and attributes
## modules
## classes and macros

We call this resource an ODD (One Document Does it all), although the master source is instantiated as a gazillion XML mini-documents.

A system of XSLT stylesheets called [[Roma]] has been created for the purpose of easy manipulation of ODD files.

== Example ==
The TEI scheme can only be used by customizing it. Customizations are also expressed in the ODD language. For example:

<pre>
<schemaSpec ident="myTEIlite">
<desc>This is TEI Lite with simplified heads</desc>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef key="linking"/>
<moduleRef key="core"/>
<moduleRef key="header"/>
<elementSpec ident="head" mode="change">
<content><textNode/></content>
</elementSpec>
</schemaSpec>
</pre>

produces a schema a bit like TEI Lite, with a slight change : the element <head> now can contain only text nodes.

== Uses besides the TEI Guidelines and various customizations ==

* [http://www.w3.org/TR/its/ Internationalization Tag Set (ITS)]
* various standards proposal designed within ISO committee TC 37 have been totally or partially written in TEI/ODD: MLIF, MAF, ISO 16642 rev., ISOTimeML

== "Pure ODD" ==

Over the years ODD has evolved in response to the needs of the TEI community, both as the core specification language for the TEI guidelines, and also as a generic customization language. Since 2004, much
effort has been put into making it less of a hybrid language, combining its own vocabulary with RelaxNG fragments and Schematron rules. Versions of TEI P5 later than 2.5 contain elements which can be used to express content models directly in the TEI ODD language, rather than in RELAXNG. ODD is thus an entirely self-contained generic specification language, independent
of other existing grammars, and hence known as Pure ODD. The proposals for Pure ODD were included in the Guidelines during January 2016, and are included as part of the 3.0.0 release

If your existing TEI schema was developed prior to this release, you should probably read up on [http://teic.github.io/TCW/purifyDoc.html How to Update your ODD]

== See also ==
*[http://en.wikipedia.org/wiki/ODD_%28Text_Encoding_Initiative%29 ODD (Text Encoding Initiative)] in Wikipedia
*[[ODD-dev] Not updated since 2012]
*[[ODD chaining] Not updated since 2012]
=== Documentation ===
* [http://www.tei-c.org/Guidelines/Customization/odds.xml Getting Started with P5 ODDs]
* [http://teic.github.io/TCW/howtoGenerate.html How to Make an ODD Automagically]
* [http://teic.github.io/TCW/howtoChain.html ODD chaining for Beginners]
* [http://teic.github.io/TCW/purifyDoc.html How to Update your ODD] (from a pre 3.0 version)
* [http://www.w3.org/TR/xml-i18n-bp/#tei-modularization A fragment of W3C's Best Practices for XML Internationalization concerning ODD customization for the Internationalization Tag Set (ITS).]
* [[Mapping ODD processing]]

=== Presentations ===
*[http://tei.oucs.ox.ac.uk/Oxford/2007-02-13-oucs/talk-odds.xml A talk about the ODD system], given on 13 Feb 2007 by Lou Burnard and Sebastian Rahtz at the OUCS ''Encoding Digital Texts'' workshop
*[http://tei.oucs.ox.ac.uk/Oxford/2006-09-methNet/Talks/RomaJourney.ppt A PowerPoint presentation on TEI/ODD] by Laurent Romary; OUCS, September 2006
*[http://www.balisage.net/Proceedings/vol7/html/Banski01/BalisageVol7-Banski01.html Literate serialization of linguistic metamodels] by Piotr Bański, Balisage-2011

=== Articles ===
* [http://jtei.revues.org/842 Resolving the Durand Conundrum], by Lou Burnard
* [http://conferences.idealliance.org/extreme/html/2004/Bauman01/EML2004Bauman01.html Odd Customizations], by Syd Bauman and Julia Flanders.
* [http://conferences.idealliance.org/extreme/html/2004/Burnard01/EML2004Burnard01.html RelaxNG with Son of ODD], by Lou Burnard and Sebastian Rahtz.
* [http://www.balisage.net/Proceedings/vol1/html/Bauman01/BalisageVol1-Bauman01.html Freedom to Constrain] by Syd Bauman

[[Category:Customization|!]]

ODD-dev

2017-10-02T19:29:08Z

Lou: /* Problems which do not seem amenable to ODD as it stands and need a new version */

[[Category:Suggestions]]
[[Category:Customization]]

This page has been set up to record underlying problems with the TEI [[ODD]] language and look at methods for improving them.

== Areas of concern for [[ODD-Dev-meetingDH2012]] ==

The following areas of concern were collated by Sebastian Rahtz for discussion at the DH2012 ODD meeting:

=== Areas of ODD2 which are not expressive enough but which can be fixed without a new paradigm===
* Module inter-dependency (if you ask for module X, also bring in module Y)
* Bertrand's model classes questions

=== Areas of ODD2 which are not well-enough defined ===
* the processing model. what order are things worked on?
* there is no defined test suite for an ODD processor
* is the DTD/RELAXNG/XSD output defined or can a processor choose different methods?
* what documentation generation options are supported? how to document customizations

=== ODD-processing which is unimplemented at present ===
* Chaining of ODDs (a customization of a customization)
* Per-element attribute-based customisation at source (specialized @type on div)
* Supporting multiple customizations of the same element (in different areas)
* Declaring an attribute class and then customizing it straightaway
* Generating XSD natively

=== Problems which do not seem amenable to ODD as it stands and need a new version ===
* Durand Conundrum: Express content models as native TEI? : DONE
* Subclasses (element <foo> has a simpler content model if its in the header)
* Attribute/content interdependency (if <foo>, then attribute @y must be used)
* Alternation of attribute/element (either child <y> or attribute @y)
* Expressing XPath-based constraints (Schematron) in a TEI language with embedded documentation
* Short-cut content models based entirely on model classes (<classes><containerOf key="model.foo"/></classes>)

==Other problems / earlier discussions ==
=== Problem: Module inter-dependency ===
* '''Desc:''' In some cases elements in one TEI module (A) require that another TEI module (B) is loaded because the content models of an element in A directly requires something that is defined in B (e.g. a class or element) but no method exists indicate this module inter-dependency. This sort of dependency can, of course, happen inside a single module as well with a content model explicitly referring to a particular element which is then removed. Some concept of dependency of references needs to be implemented.
* '''Suggested solutions:'''
This is largely mitigated by ensuring that content models reference model classes rather than explicit elements. A further prosecution of class warfare might therefore be useful.
* '''Points for discussion:'''
** None so far

=== Problem: Subclasses ===
* '''Desc:''' The ability to add subclass membership to an element to, for example, grant it some extra attributes in a particular location. e.g. “I want the head inside figure to be the real <tt><tei:head></tt> element but have it be a member of <tt>att.mySpecialAttributes</tt> to give it some extra attributes, but only when it is inside <tt><figure></tt>”. This may also relate to Per-element attribute-based customisation in specific circumstances mentioned below.
* '''Suggested solutions:''' none so far
* '''Points for discussion:'''
# I ([[User:Syd|Syd]]) am under the impression that the problem cannot occur exactly as described. If you add attributes to the <tt><head></tt> element (whether directly or by adding it to the class <tt>att.mySpecialAttributes</tt>), it will not validate against <tt>tei_all</tt>, and has to be placed in another namespace. I.e., it ''cannot'' be <tt><tei:head></tt>.
***# '''Reply:''' Perhaps poorly phrased in the description. How about we reverse it: let's say you want to remove @n from <tt><figure></tt> globally, but then allow it back when inside <tt><figure></tt>. Obviously you can test that with schematron, but not (I think) simply by adding <tt><figure></tt> to a new attribute class. [[User:James|James]] 10:23, 1 September 2009 (EDT)

# That said, the desire to have special attributes on <tt><my:head></tt> when it is a child of <tt><figure></tt> and not otherwise is a very reasonable one.
# RELAX NG permits co-occurrence constraints like this, but ODD and DTDs do not. W3C Schema 1.0 does not. Rumor has it that XSD 1.1 will, but I haven't looked carefully.
# As it stands it would be very reasonable to add the attributes to <tt><my:head></tt> in the ODD tagdoc, and then add a “don't use these attributes unless a child of <tt><figure></tt>” as a <tt><constraintSpec></tt>, i.e., in Schematron.

It seems to me that this is very much in schematron country, because of the element content/context dependency.

=== Problem: Per-element attribute-based customisation ===
* '''Desc:''' The ability to customise the desc, valList, and other aspects of an attribute inherited from a class on a per-element basis. For example giving different suggested values for @type on an element, or a more specific description of an attribute when used on a certain element.
* '''Suggested solutions:''' This is probably the request of http://purl.org/tei/fr/337683, allowing specialization of elements back at source level rather than in a customization
* '''Points for discussion:'''
** None so far

=== Problem: attribute/content interdependency ===
* '''Desc:''' Attributes and content interdependency means that you can have either attribute or content but not both.
* '''Suggested solutions:''' none so far
* '''Points for discussion:'''
** None so far

=== Problem: Chaining of ODDs ===
* '''Desc:''' ODD should be able to be based not on the full TEI but on another ODD customisation of ODD.
* '''Suggested solutions:''' I think the new @source attribute makes a major step in this direction
* '''Points for discussion:'''
** None so far

=== Problem: Referencing ODD from Document Instance ===
NOTE: This was discussed by Counci in Ann Arbor in April 2012, and will be going ahead. The ticket for this is [[http://purl.org/tei/fr/1650195]].
* '''Desc:''' The best place to reference an ODD in a document instance that creates the schema that the document instance is meant to validate against. Equally, whether an ODD can be embedded (or XIncluded) into a document instance. This would create a truly portable TEI document which held the document itself, and the means to create the schema and schema documentation all in a single document. This is potentially useful as an archival format.
* '''Suggested solutions:'''
*Doesn't Roma now include details of the ODD from which a schema was generated as a comment inside the schema? That is probably as far as we should go in this direction.
** But Lou, a mere link to a TEI source, whilst an improvement isn't a consistently machine-processable way of storing that information. If I want to process a bunch of TEI document instances and find out what ODD they were created against, I have no good method of doing so. Somewhere in the header (in encodingDesc? tagsDecl?) should be an appropriate place for someone to, at very least, store a <ptr/> to the ODD file. XML comments inside generated schemas are not reliable and you may not have a copy of the schema, but want to regenerate it from the ODD. The simple case of embedding a link in the teiHeader somewhere seems quite a trivial bug in that the TEI doesn't make any recommendation of where to put it (so a prose change and maybe allowing <ptr/> somewhere). Comments in XML can be and are thrown away by XML processors according to the spec. The more difficult case of embedding the entire ODD with the document as an archival format is admittedly more extreme... I mean I have an example ODD which does this by allowing instances to embed it in encodingDesc, but a better solution might be more useable for archival formats of the TEI.

=== Problem: Classification of Elements as belonging to one or more category to aid interoperability ===
* '''Desc:''' This may be already possible in TEI ODD, but not clearly documented for this purpose. The idea is that any form of customization inside a <schemaSpec> or any element/attribute/class should be able to be categorized as to its nature(s). This categorization can then be used to know whether this item is considered important for interchange/interoperability on one or more lossy exports of the document for interchange or interoperable uses. Thus for various uses elements of a certain category could just be silently ignored, whereas others could be processed following their 'equiv', and other preserved as essential, etc.

ODD

2017-10-02T19:27:39Z

Lou: /* Future plans: "Pure ODD" */

'''ODD''' stands for "One Document Does it all". It is a TEI XML-conformant specification format that allows one to customize TEI P5 in a [[Wikipedia:literate programming|literate programming]] fashion. It uses elements from the new [http://www.tei-c.org/P5/Guidelines/TD.html Documentation Elements] module.

== Description ==
The TEI Guidelines, its DTD, and its schema fragments, are all produced from a single XML resource containing:

# Descriptive prose (lots of it)
# Examples of usage (plenty)
# Formal declarations for components of the TEI Abstract Model:
## elements and attributes
## modules
## classes and macros

We call this resource an ODD (One Document Does it all), although the master source is instantiated as a gazillion XML mini-documents.

A system of XSLT stylesheets called [[Roma]] has been created for the purpose of easy manipulation of ODD files.

== Example ==
The TEI scheme can only be used by customizing it. Customizations are also expressed in the ODD language. For example:

<pre>
<schemaSpec ident="myTEIlite">
<desc>This is TEI Lite with simplified heads</desc>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef key="linking"/>
<moduleRef key="core"/>
<moduleRef key="header"/>
<elementSpec ident="head" mode="change">
<content><textNode/></content>
</elementSpec>
</schemaSpec>
</pre>

produces a schema a bit like TEI Lite, with a slight change : the element <head> now can contain only text nodes.

== Uses besides the TEI Guidelines and various customizations ==

* [http://www.w3.org/TR/its/ Internationalization Tag Set (ITS)]
* various standards proposal designed within ISO committee TC 37 have been totally or partially written in TEI/ODD: MLIF, MAF, ISO 16642 rev., ISOTimeML

== "Pure ODD" ==

Over the years ODD has evolved in response to the needs of the TEI community, both as the core specification language for the TEI guidelines, and also as a generic customization language. Since 2004, much
effort has been put into making it less of a hybrid language, combining its own vocabulary with RelaxNG fragments and Schematron rules. Versions of TEI P5 later than 2.5 contain elements which can be used to express content models directly in the TEI ODD language, rather than in RELAXNG. ODD is thus an entirely self-contained generic specification language, independent
of other existing grammars, and hence known as Pure ODD. The proposals for Pure ODD were included in the Guidelines during January 2016, and are included as part of the 3.0.0 release

If your existing TEI schema was developed prior to this release, you should probably read up on [http://teic.github.io/TCW/purifyDoc.html How to Update your ODD]

== See also ==
*[http://en.wikipedia.org/wiki/ODD_%28Text_Encoding_Initiative%29 ODD (Text Encoding Initiative)] in Wikipedia
*[[ODD-dev]]
*[[ODD chaining]]
=== Documentation ===
* [http://www.tei-c.org/Guidelines/Customization/odds.xml Getting Started with P5 ODDs]
* [http://teic.github.io/TCW/howtoGenerate.html How to Make an ODD Automagically]
* [http://teic.github.io/TCW/howtoChain.html ODD chaining for Beginners]
* [http://teic.github.io/TCW/purifyDoc.html How to Update your ODD] (from a pre 3.0 version)
* [http://www.w3.org/TR/xml-i18n-bp/#tei-modularization A fragment of W3C's Best Practices for XML Internationalization concerning ODD customization for the Internationalization Tag Set (ITS).]
* [[Mapping ODD processing]]

=== Presentations ===
*[http://tei.oucs.ox.ac.uk/Oxford/2007-02-13-oucs/talk-odds.xml A talk about the ODD system], given on 13 Feb 2007 by Lou Burnard and Sebastian Rahtz at the OUCS ''Encoding Digital Texts'' workshop
*[http://tei.oucs.ox.ac.uk/Oxford/2006-09-methNet/Talks/RomaJourney.ppt A PowerPoint presentation on TEI/ODD] by Laurent Romary; OUCS, September 2006
*[http://www.balisage.net/Proceedings/vol7/html/Banski01/BalisageVol7-Banski01.html Literate serialization of linguistic metamodels] by Piotr Bański, Balisage-2011

=== Articles ===
* [http://jtei.revues.org/842 Resolving the Durand Conundrum], by Lou Burnard
* [http://conferences.idealliance.org/extreme/html/2004/Bauman01/EML2004Bauman01.html Odd Customizations], by Syd Bauman and Julia Flanders.
* [http://conferences.idealliance.org/extreme/html/2004/Burnard01/EML2004Burnard01.html RelaxNG with Son of ODD], by Lou Burnard and Sebastian Rahtz.
* [http://www.balisage.net/Proceedings/vol1/html/Bauman01/BalisageVol1-Bauman01.html Freedom to Constrain] by Syd Bauman

[[Category:Customization|!]]

Rahtz Prize for TEI Ingenuity

2016-09-12T20:23:16Z

Lou: /* Review Process and Criteria */

==About the Rahtz Prize==

The TEI Consortium has created the Rahtz Prize for TEI Ingenuity in memory of [https://en.wikipedia.org/wiki/Sebastian_Rahtz Sebastian Rahtz] (13 February 1955 – 15 March 2016). The award
is intended to honour Sebastian’s major technical and philosophical contributions to the TEI, and to encourage TEI innovation by the TEI community.

Sebastian was responsible for the design and implementation of a great deal of the TEI's technical infrastructure. Within the TEI community he was best known for the creation and maintenance of the XSLT Stylesheets that underlie much TEI conversion work, customization, and schema generation. As a member of both the TEI's Technical Council and its Board, he helped shape the direction of the Consortium.

The Rahtz Prize for TEI Ingenuity is awarded to an individual or team judged to have made a significant contribution to the [http://www.tei-c.org/About/mission.xml TEI-C's mission] in particular by
means of technical innovation. Many members of the TEI Community are engaged in exploring new
ways of implementing and expanding the coverage of the TEI system. It is hoped that this Prize will not only recognize excellent work already completed, but also encourage new projects and fresh approaches.

==Important Info and Dates ==

* $1,000 USD will be awarded to one individual or team per year
* 1 August: Submissions Due
* 15 September: Winner Selected
* Annual Business Meeting: Winner Announced

==Submission Rules and Guidelines==

Applications for the Rahtz Prize for TEI Ingenuity may be [https://goo.gl/forms/ZX4NKQ3cPHnBvSxK2 submitted online] ([https://goo.gl/forms/ZX4NKQ3cPHnBvSxK2 https://goo.gl/forms/ZX4NKQ3cPHnBvSxK2]) at any time but must be submitted by midnight in Hawaii on 1 August in order to be considered for awarding at that year's TEI members' meeting.

Along with contact information, applicants will be asked to submit a 500-1,500 summary describing the project/initiative. This summary should reflect the [http://www.tei-c.org/About/mission.xml TEI-C's mission] and the criteria as outlined below.

===Eligibility===
* Individuals or teams are eligible to apply. Membership to the TEI-Consortium is not a requirement.
* If awarded, the individuals/teams are eligible to submit another application three (3) years after the granted award.

==Review Process and Criteria==

Nominations will be reviewed by an Awards Panel comprising the Chair of the TEI-C Board of Directors, the Chair of the TEI-C Technical Council, and one invited, long-time and active member of the TEI Community. No member of the Panel may serve more than three consecutive years. Membership of the Panel will be agreed upon jointly by the Board and the Council by 1 July.

Nominations should demonstrate that the person or team nominated has made an outstanding
contribution to one or more of the following:

* innovative development of the TEI Guidelines
* creation of TEI-aware tools and technologies that further dissemination, adoption, and engaged use of the TEI Guidelines
* expansive and inclusive TEI training and outreach opportunities
* informed development and cultivation of particular TEI practitioner communities

The Awards Panel is not required to make an award in every year, nor to consider only the nominations received.

==Terms==
The recipient(s) will receive a cash award of $1,000 USD, or a round number of about the same value in the currency in which the prize is to be awarded. The final selection is made by the panel of judges and announced as part of the Business Meeting, which occurs as part of the annual TEI-C Conference and Members' Meeting. The disbursement of the cash award is arranged through the TEI-C Treasurer.

[[Category:Board]]

Rahtz Prize for TEI Ingenuity

2016-09-12T20:05:20Z

Lou: /* About the Rahtz Prize */

==About the Rahtz Prize==

The TEI Consortium has created the Rahtz Prize for TEI Ingenuity in memory of [https://en.wikipedia.org/wiki/Sebastian_Rahtz Sebastian Rahtz] (13 February 1955 – 15 March 2016). The award
is intended to honour Sebastian’s major technical and philosophical contributions to the TEI, and to encourage TEI innovation by the TEI community.

Sebastian was responsible for the design and implementation of a great deal of the TEI's technical infrastructure. Within the TEI community he was best known for the creation and maintenance of the XSLT Stylesheets that underlie much TEI conversion work, customization, and schema generation. As a member of both the TEI's Technical Council and its Board, he helped shape the direction of the Consortium.

The Rahtz Prize for TEI Ingenuity is awarded to an individual or team judged to have made a significant contribution to the [http://www.tei-c.org/About/mission.xml TEI-C's mission] in particular by
means of technical innovation. Many members of the TEI Community are engaged in exploring new
ways of implementing and expanding the coverage of the TEI system. It is hoped that this Prize will not only recognize excellent work already completed, but also encourage new projects and fresh approaches.

==Important Info and Dates ==

* $1,000 USD will be awarded to one individual or team per year
* 1 August: Submissions Due
* 15 September: Winner Selected
* Annual Business Meeting: Winner Announced

==Submission Rules and Guidelines==

Applications for the Rahtz Prize for TEI Ingenuity may be [https://goo.gl/forms/ZX4NKQ3cPHnBvSxK2 submitted online] ([https://goo.gl/forms/ZX4NKQ3cPHnBvSxK2 https://goo.gl/forms/ZX4NKQ3cPHnBvSxK2]) at any time but must be submitted by midnight in Hawaii on 1 August in order to be considered for awarding at that year's TEI members' meeting.

Along with contact information, applicants will be asked to submit a 500-1,500 summary describing the project/initiative. This summary should reflect the [http://www.tei-c.org/About/mission.xml TEI-C's mission] and the criteria as outlined below.

===Eligibility===
* Individuals or teams are eligible to apply. Membership to the TEI-Consortium is not a requirement.
* If awarded, the individuals/teams are eligible to submit another application three (3) years after the granted award.

==Review Process and Criteria==

The submissions will be reviewed by a panel of three judges: the Chair of the TEI-C Board of Directors, the Chair of the TEI-C Technical Council, and an invited, long-time and active member from the TEI Community. A new panel of judges may change as frequently as every year, but the same jury member should not serve more than 3 consecutive years. The Community judge will be identified and agreed upon jointly by the Board and the Council by 1 July.

Contributions should reflect:

* innovative development of the TEI-C Guidelines
* the creation of TEI-aware tools and technologies that further dissemination, adoption, and engaged use of the TEI-C Guidelines
* expansive and inclusive training and outreach opportunities
* the cultivation of particular TEI-C researcher and practitioner communities

==Terms==
The recipient(s) will receive a cash award of $1,000 USD, or a round number of about the same value in the currency in which the prize is to be awarded. The final selection is made by the panel of judges and announced as part of the Business Meeting, which occurs as part of the annual TEI-C Conference and Members' Meeting. The disbursement of the cash award is arranged through the TEI-C Treasurer.

[[Category:Board]]

Rahtz Prize for TEI Ingenuity

2016-09-12T20:04:06Z

Lou: /* About the Rahtz Prize */

==About the Rahtz Prize==

The TEI Consortium has created the Rahtz Prize for TEI Ingenuity in memory of [https://en.wikipedia.org/wiki/Sebastian_Rahtz Sebastian Rahtz] (13 February 1955 – 15 March 2016). The award
is intended to honour Sebastian’s major technical and philosophical contributions to the TEI, and to encourage TEI innovation by the TEI community.

Sebastian was responsible for the design and implementation of a great deal of the TEI's technical infrastructure. Inside the TEI community he was most well-known for the creation and maintenance of the XSLT Stylesheets that underlie much TEI conversion work, customization, and schema generation. As a member of both the TEI's Technical Council and its Board he helped shape the direction of the Consortium.

The Rahtz Prize for TEI Ingenuity is awarded to an individual or team judged to have made a significant contribution to the [http://www.tei-c.org/About/mission.xml TEI-C's mission] in particular by
means of technical innovation. Many members of the TEI Community are engaged in exploring new
ways of implementing and expanding the coverage of the TEI system. It is hoped that this Prize will not only recognize excellent work already completed, but also encourage new projects and fresh approaches.

==Important Info and Dates ==

* $1,000 USD will be awarded to one individual or team per year
* 1 August: Submissions Due
* 15 September: Winner Selected
* Annual Business Meeting: Winner Announced

==Submission Rules and Guidelines==

Applications for the Rahtz Prize for TEI Ingenuity may be [https://goo.gl/forms/ZX4NKQ3cPHnBvSxK2 submitted online] ([https://goo.gl/forms/ZX4NKQ3cPHnBvSxK2 https://goo.gl/forms/ZX4NKQ3cPHnBvSxK2]) at any time but must be submitted by midnight in Hawaii on 1 August in order to be considered for awarding at that year's TEI members' meeting.

Along with contact information, applicants will be asked to submit a 500-1,500 summary describing the project/initiative. This summary should reflect the [http://www.tei-c.org/About/mission.xml TEI-C's mission] and the criteria as outlined below.

===Eligibility===
* Individuals or teams are eligible to apply. Membership to the TEI-Consortium is not a requirement.
* If awarded, the individuals/teams are eligible to submit another application three (3) years after the granted award.

==Review Process and Criteria==

The submissions will be reviewed by a panel of three judges: the Chair of the TEI-C Board of Directors, the Chair of the TEI-C Technical Council, and an invited, long-time and active member from the TEI Community. A new panel of judges may change as frequently as every year, but the same jury member should not serve more than 3 consecutive years. The Community judge will be identified and agreed upon jointly by the Board and the Council by 1 July.

Contributions should reflect:

* innovative development of the TEI-C Guidelines
* the creation of TEI-aware tools and technologies that further dissemination, adoption, and engaged use of the TEI-C Guidelines
* expansive and inclusive training and outreach opportunities
* the cultivation of particular TEI-C researcher and practitioner communities

==Terms==
The recipient(s) will receive a cash award of $1,000 USD, or a round number of about the same value in the currency in which the prize is to be awarded. The final selection is made by the panel of judges and announced as part of the Business Meeting, which occurs as part of the annual TEI-C Conference and Members' Meeting. The disbursement of the cash award is arranged through the TEI-C Treasurer.

[[Category:Board]]

Editor for teaching TEI - features

2016-07-11T14:02:40Z

Lou: /* Comments, justification, discussion */

[[Category:Editing tools]]
__NOTOC__
This is an attempt at listing the minimal set of features that a TEI editor '''used for teaching purposes''' should have.

=== 1. Basic required features ===
1.1. multiplatform
<br>1.2. validation with Relax NG
<br>1.3. continuous validation
<br>1.4. contextual suggestions (following the schema)
<br>1.5. XSLT 2 transformation (Saxon HE? that would offer XQuery as well)
<br>1.6. easy to use
<br>1.7. free for students (as in beer)
<br>1.8. syntax highlighting for XML (that naturally includes XSLT)
<br>1.9. XPath queries (2.0 only would be fine)
<br>1.10 Support for Oxygen project files enabling configuration of validation, transformation and templating; or an equivalent system for another editor.

=== Comments, justification, discussion ===
(please use the hard-set numbers; note that discussion is still running at [[TEI-L]]; everyone is welcome to modify this page)
* Item 1.7. could imply a very moderate bulk licensing fee paid by the institution that provides training; we have to bear in mind that the entire discussion started because of a department refusing to pay regular licensing fees (deemed as too high) for a course that lasts a semester
* "I would move your 2.2 and 2.3 (xpath query and help pop ups) up to the essential category. These are features I use all the time when teaching." (Lou Burnard)
** just noting that a pop-up is only one of the possibilities (one can imagine a side panel appearing due to a keystroke sequence), but the discussion started originally from how oXygen could be dumbed down; I try to make the lists and considerations here slightly more general ([[User:Piotr Banski|Piotr]])
** very true Piotr! Whatever the interface, I agree with Lou that it's an important feature.
* 2.5: "From a sustainability perspective, I would add "open-source" to the feature set, maybe in the "2. Ideally..." section. This may not be much pertinent from the short term opportunistic point of view of a student (or a teacher), but may help consolidate tools appropriateness to TEI for the long term, which is what TEI is all about." (Serge Heiden)
* I have moved XPath queries from "Ideally" to "Basic features". In my experience, that's an essential point for students (and people in general). (Marjorie) I've constrained this to XPath 2.0; I think this would be sufficient. (Martin Holmes)
* Could we preserve the possibility to use a third-party commercial tool, like Saxon PE, if the users need them and want to acquire them?
* I've added Oxygen project files, or an equivalent system in a competing editor (Martin Holmes).
* Another essential feature for me would be the ability to script a sequence of transformations etc. in the way that oXygen currently does when generating RNG and XHTML from an ODD file. It's currently done with an Ant script, but any scripting language will do. I routinely do an exercise which involves editing an ODD, generating a schema, using it to create a new file, et da capo. This is easy and seamless in oXyGen: doing it via the oXGarage web interface would be cumbersome and confusing. (Lou)

=== 2. Ideally... ===
2.1. free (as in beer)
<br>2.2. Inline documentation (i.e. the little pop-ups with the definition of the element)
<br>2.3. pre-set templates (example?)
<br>2.4. syntax highlighting for XQuery
<br>2.5. open source
<br>2.6. validation with Relax NG '''based on the xml-model PI in the document'''
<br>2.7. possibility to auto-update the TEI schema at each new release

=== 3. Features that can be eliminated from a "teaching editor" in order to decrease its cost ===
3.1. No XSLT 3 (as a consequence of the fact that no commercial tool such as Saxon PE/EE could be used in such an editor)
<br>3.2. No need for XSLT or XQuery debuggers
<br>3.3. no need for database connectivity
<br>3.4. no need for a built-in SVN (etc.) client
<br>3.5. no need for a Tree Editor such as the one offered by oXygen
<br>3.6. no need for Compare Files/Directories tools
<br>3.7. no need for big-file editor or big-file support in general
<br>3.8. no need for syntax highlighting and editing support for some file types which are not XML-based (JavaScript, CSS, JSON, etc.).

=== Notes ===
The impetus for establishing the above came from a sub-thread on the [[TEI-L]] list bulleted by the following messages: [https://listserv.brown.edu/archives/cgi-bin/wa?A2=tei-l;fcdcab72.1607], [https://listserv.brown.edu/archives/cgi-bin/wa?A2=tei-l;af28895d.1607], [https://listserv.brown.edu/archives/cgi-bin/wa?A2=tei-l;83b06464.1607]. The idea is to see whether the community can agree on a single feature set that a dumbed-down commercial editor can implement is a "student version" with an appropriate license.
Or, as Martin Holmes puts it, we want to "arrive at something which would be utterly useless for the likes of me, and quite frustrating for serious users, but perfectly functional for teaching introductory XML encoding classes over a few months."

ODD

2016-01-25T15:38:40Z

Lou: /* Future plans: "Pure ODD" */

'''ODD''' stands for "One Document Does it all". It is a TEI XML-conformant specification format that allows one to customize TEI P5 in a [[Wikipedia:literate programming|literate programming]] fashion. It uses elements from the new [http://www.tei-c.org/P5/Guidelines/TD.html Documentation Elements] module.

== Description ==
The TEI Guidelines, its DTD, and its schema fragments, are all produced from a single XML resource containing:

# Descriptive prose (lots of it)
# Examples of usage (plenty)
# Formal declarations for components of the TEI Abstract Model:
## elements and attributes
## modules
## classes and macros

We call this resource an ODD (One Document Does it all), although the master source is instantiated as a gazillion XML mini-documents.

A system of XSLT stylesheets called [[Roma]] has been created for the purpose of easy manipulation of ODD files.

== Example ==
The TEI scheme can only be used by customizing it. Customizations are also expressed in the ODD language. For example:

<pre>
<schemaSpec ident="myTEIlite">
<desc>This is TEI Lite with simplified heads</desc>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef key="linking"/>
<moduleRef key="core"/>
<moduleRef key="header"/>
<elementSpec ident="head" mode="change">
<content><textNode/></content>
</elementSpec>
</schemaSpec>
</pre>

produces a schema a bit like TEI Lite, with a slight change : the element <head> now can contain only text nodes.

== Uses besides the TEI Guidelines and various customizations ==

* [http://www.w3.org/TR/its/ Internationalization Tag Set (ITS)]
* various standards proposal designed within ISO committee TC 37 have been totally or partially written in TEI/ODD: MLIF, MAF, ISO 16642 rev., ISOTimeML

== Future plans: "Pure ODD" ==

Over the years ODD has evolved in response to the needs of the TEI community, both as the core specification language for the TEI guidelines, and also as a generic customization language. Since 2004, much
effort has been put into making it less of a hybrid language, combining its own vocabulary with RelaxNG fragments and Schematron rules. Versions of TEI P5 later than 2.5 contain elements which can be used to express content models directly in the TEI ODD language, rather than in RELAXNG. This work is ongoing in the TEI Technical Council, the goal being to make ODD an entirely self-contained generic specification language, independent
of other existing grammars, and hence known as Pure ODD. See further [https://github.com/TEIC/pureodd "Pure ODD"]. There is a mailing list for discussing Pure ODD called [https://lists.sourceforge.net/lists/listinfo/tei-odds tei-odds].

The proposals for Pure ODD were finally included in the Guidelines during January 2016, for inclusion as part of the 3.0.0 release

== See also ==
*[http://en.wikipedia.org/wiki/ODD_%28Text_Encoding_Initiative%29 ODD (Text Encoding Initiative)] in Wikipedia
*[[ODD-dev]]
=== Documentation ===
*[http://www.tei-c.org/Guidelines/Customization/odds.xml Getting Started with P5 ODDs]
*[http://www.w3.org/TR/xml-i18n-bp/#tei-modularization A fragment of W3C's Best Practices for XML Internationalization concerning ODD customization for the Internationalization Tag Set (ITS).]
=== Presentations ===
*[http://tei.oucs.ox.ac.uk/Oxford/2007-02-13-oucs/talk-odds.xml A talk about the ODD system], given on 13 Feb 2007 by Lou Burnard and Sebastian Rahtz at the OUCS ''Encoding Digital Texts'' workshop
*[http://tei.oucs.ox.ac.uk/Oxford/2006-09-methNet/Talks/RomaJourney.ppt A PowerPoint presentation on TEI/ODD] by Laurent Romary; OUCS, September 2006
*[http://www.balisage.net/Proceedings/vol7/html/Banski01/BalisageVol7-Banski01.html Literate serialization of linguistic metamodels] by Piotr Bański, Balisage-2011

=== Articles ===
* [http://jtei.revues.org/842 Resolving the Durand Conundrum], by Lou Burnard
* [http://conferences.idealliance.org/extreme/html/2004/Bauman01/EML2004Bauman01.html Odd Customizations], by Syd Bauman and Julia Flanders.
* [http://conferences.idealliance.org/extreme/html/2004/Burnard01/EML2004Burnard01.html RelaxNG with Son of ODD], by Lou Burnard and Sebastian Rahtz.
* [http://www.balisage.net/Proceedings/vol1/html/Bauman01/BalisageVol1-Bauman01.html Freedom to Constrain] by Syd Bauman

[[Category:Customization|!]]

Council Agenda 2015-03

2015-03-27T10:32:48Z

Lou: /* Teleconference 2015-02-27 13:30 GMT */

== Teleconference 2015-02-27 13:30 GMT ==

* Review of action items from last telecon (see [[http://www.tei-c.org/Activities/Council/Meetings/tcm66.xml minutes]]).
* JTEI integration into P5, Stylesheets and Oxygen plugin (MH).
* Update on Pure ODD (LB)
* What's in/out of the upcoming release?
* other items?

ODD

2015-03-23T16:33:10Z

Lou: /* Future plans: "Pure ODD" */

'''ODD''' stands for "One Document Does it all". It is a TEI XML-conformant specification format that allows one to customize TEI P5 in a [[Wikipedia:literate programming|literate programming]] fashion. It uses elements from the new [http://www.tei-c.org/P5/Guidelines/TD.html Documentation Elements] module.

== Description ==
The TEI Guidelines, its DTD, and its schema fragments, are all produced from a single XML resource containing:

# Descriptive prose (lots of it)
# Examples of usage (plenty)
# Formal declarations for components of the TEI Abstract Model:
## elements and attributes
## modules
## classes and macros

We call this resource an ODD (One Document Does it all), although the master source is instantiated as a gazillion XML mini-documents.

A system of XSLT stylesheets called [[Roma]] has been created for the purpose of easy manipulation of ODD files.

== Example ==
The TEI scheme can only be used by customizing it. Customizations are also expressed in the ODD language. For example:

<pre>
<schemaSpec ident="myTEIlite">
<desc>This is TEI Lite with simplified heads</desc>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef key="linking"/>
<moduleRef key="core"/>
<moduleRef key="header"/>
<elementSpec ident="head" mode="change">
<content><textNode/></content>
</elementSpec>
</schemaSpec>
</pre>

produces a schema a bit like TEI Lite, with a slight change : the element <head> now can contain only text nodes.

== Uses besides the TEI Guidelines and various customizations ==

* [http://www.w3.org/TR/its/ Internationalization Tag Set (ITS)]
* various standards proposal designed within ISO committee TC 37 have been totally or partially written in TEI/ODD: MLIF, MAF, ISO 16642 rev., ISOTimeML

== Future plans: "Pure ODD" ==

Over the years ODD has evolved in response to the needs of the TEI community, both as the core specification language for the TEI guidelines, and also as a generic customization language. Since 2004, much
effort has been put into making it less of a hybrid language, combining its own vocabulary with RelaxNG fragments and Schematron rules. Versions of TEI P5 later than 2.5 contain elements which can be used to express content models directly in the TEI ODD language, rather than in RELAXNG. This work is ongoing in the TEI Technical Council, the goal being to make ODD an entirely self-contained generic specification language, independent
of other existing grammars, and hence known as Pure ODD. See further [https://github.com/TEIC/pureodd "Pure ODD"]. There is a mailing list for discussing Pure ODD called [https://lists.sourceforge.net/lists/listinfo/tei-odds tei-odds].

== See also ==
*[http://en.wikipedia.org/wiki/ODD_%28Text_Encoding_Initiative%29 ODD (Text Encoding Initiative)] in Wikipedia
*[[ODD-dev]]
=== Documentation ===
*[http://www.tei-c.org/Guidelines/Customization/odds.xml Getting Started with P5 ODDs]
*[http://www.w3.org/TR/xml-i18n-bp/#tei-modularization A fragment of W3C's Best Practices for XML Internationalization concerning ODD customization for the Internationalization Tag Set (ITS).]
=== Presentations ===
*[http://tei.oucs.ox.ac.uk/Oxford/2007-02-13-oucs/talk-odds.xml A talk about the ODD system], given on 13 Feb 2007 by Lou Burnard and Sebastian Rahtz at the OUCS ''Encoding Digital Texts'' workshop
*[http://tei.oucs.ox.ac.uk/Oxford/2006-09-methNet/Talks/RomaJourney.ppt A PowerPoint presentation on TEI/ODD] by Laurent Romary; OUCS, September 2006
*[http://www.balisage.net/Proceedings/vol7/html/Banski01/BalisageVol7-Banski01.html Literate serialization of linguistic metamodels] by Piotr Bański, Balisage-2011

=== Articles ===
* [http://jtei.revues.org/842 Resolving the Durand Conundrum], by Lou Burnard
* [http://conferences.idealliance.org/extreme/html/2004/Bauman01/EML2004Bauman01.html Odd Customizations], by Syd Bauman and Julia Flanders.
* [http://conferences.idealliance.org/extreme/html/2004/Burnard01/EML2004Burnard01.html RelaxNG with Son of ODD], by Lou Burnard and Sebastian Rahtz.
* [http://www.balisage.net/Proceedings/vol1/html/Bauman01/BalisageVol1-Bauman01.html Freedom to Constrain] by Syd Bauman

[[Category:Customization|!]]

ODD

2015-03-23T16:24:25Z

Lou: /* Example */

'''ODD''' stands for "One Document Does it all". It is a TEI XML-conformant specification format that allows one to customize TEI P5 in a [[Wikipedia:literate programming|literate programming]] fashion. It uses elements from the new [http://www.tei-c.org/P5/Guidelines/TD.html Documentation Elements] module.

== Description ==
The TEI Guidelines, its DTD, and its schema fragments, are all produced from a single XML resource containing:

# Descriptive prose (lots of it)
# Examples of usage (plenty)
# Formal declarations for components of the TEI Abstract Model:
## elements and attributes
## modules
## classes and macros

We call this resource an ODD (One Document Does it all), although the master source is instantiated as a gazillion XML mini-documents.

A system of XSLT stylesheets called [[Roma]] has been created for the purpose of easy manipulation of ODD files.

== Example ==
The TEI scheme can only be used by customizing it. Customizations are also expressed in the ODD language. For example:

<pre>
<schemaSpec ident="myTEIlite">
<desc>This is TEI Lite with simplified heads</desc>
<moduleRef key="tei"/>
<moduleRef key="textstructure"/>
<moduleRef key="linking"/>
<moduleRef key="core"/>
<moduleRef key="header"/>
<elementSpec ident="head" mode="change">
<content><textNode/></content>
</elementSpec>
</schemaSpec>
</pre>

produces a schema a bit like TEI Lite, with a slight change : the element <head> now can contain only text nodes.

== Uses besides the TEI Guidelines and various customizations ==

* [http://www.w3.org/TR/its/ Internationalization Tag Set (ITS)]
* various standards proposal designed within ISO committee TC 37 have been totally or partially written in TEI/ODD: MLIF, MAF, ISO 16642 rev., ISOTimeML

== Future plans: "Pure ODD" ==

Over the years ODD has evolved progressively to reflect more and more needs of the TEI community, both as the core specification language for the TEI guidelines, but also as generic customization language for any TEI users. Still ODD remains a hybrid environment combining its own vacabulary with RelaxNG fragments and at times, validation vocabularies from external languages (e.g. Schematron). The Technical Council contemplates putting on its work program a revision of the ODD infrastructure, considering either to drop it altogether in favor of one existing schema language, or extend its capabilities to make it a self contained and generic specification language. Some thoughts are included at [[ODD-dev]], and the effort to make it self-contained is now referred to as [https://github.com/TEIC/pureodd "Pure ODD"]. There is a mailing list for discussing Pure ODD called [https://lists.sourceforge.net/lists/listinfo/tei-odds tei-odds].

== See also ==
*[http://en.wikipedia.org/wiki/ODD_%28Text_Encoding_Initiative%29 ODD (Text Encoding Initiative)] in Wikipedia
*[[ODD-dev]]
=== Documentation ===
*[http://www.tei-c.org/Guidelines/Customization/odds.xml Getting Started with P5 ODDs]
*[http://www.w3.org/TR/xml-i18n-bp/#tei-modularization A fragment of W3C's Best Practices for XML Internationalization concerning ODD customization for the Internationalization Tag Set (ITS).]
=== Presentations ===
*[http://tei.oucs.ox.ac.uk/Oxford/2007-02-13-oucs/talk-odds.xml A talk about the ODD system], given on 13 Feb 2007 by Lou Burnard and Sebastian Rahtz at the OUCS ''Encoding Digital Texts'' workshop
*[http://tei.oucs.ox.ac.uk/Oxford/2006-09-methNet/Talks/RomaJourney.ppt A PowerPoint presentation on TEI/ODD] by Laurent Romary; OUCS, September 2006
*[http://www.balisage.net/Proceedings/vol7/html/Banski01/BalisageVol7-Banski01.html Literate serialization of linguistic metamodels] by Piotr Bański, Balisage-2011

=== Articles ===
* [http://jtei.revues.org/842 Resolving the Durand Conundrum], by Lou Burnard
* [http://conferences.idealliance.org/extreme/html/2004/Bauman01/EML2004Bauman01.html Odd Customizations], by Syd Bauman and Julia Flanders.
* [http://conferences.idealliance.org/extreme/html/2004/Burnard01/EML2004Burnard01.html RelaxNG with Son of ODD], by Lou Burnard and Sebastian Rahtz.
* [http://www.balisage.net/Proceedings/vol1/html/Bauman01/BalisageVol1-Bauman01.html Freedom to Constrain] by Syd Bauman

[[Category:Customization|!]]

Global @resp attribute

2014-12-05T15:01:57Z

Lou: /* PROSE */

==IMPLEMENTATION PLAN==

Council agreed to go ahead with this 2014-11-18. What follows is an implementation plan.

===SPECS===

# Rename (i.e. <code>svn rename</code>) att.responsibility.xml to att.global.responsibility.xml, and remove its membership of att.source.
# Add the class to att.global.xml.
# Add a reference to PHHR to the spec (this is the excellent discussion of @resp/@cert vs <respons>/<certainty>).
# Replace att.responsibility everywhere it occurs with att.source (to preserve @source where it is now allowed).
# Change the definition of @cert in certainty.xml to mode="change".
# Change the definition of @resp in space.xml to mode="change".
# Add the following example to att.global.responsibility.xml:

<egXML xmlns="http://www.tei-c.org/ns/Examples">



<l>Punkes, Panders, baſe extortionizing
sla<choice><sic>n</sic><corr resp="#JENS1_transcriber">u</corr></choice>es,</l>



<respStmt xml:id="JENS1_transcriber">
<resp when="2014">Transcriber</resp>
<name>Janelle Jenstad</name>
</respStmt>
</egXML>

===SPEC REFERENCES===

Change all instances of this:

<code><specDesc key="att.responsibility" </code>

to this:

<code><specDesc key="att.global.responsibility" </code>

and all instances of this:

<code><ident type="class">att.responsibility</ident></code>

to this:

<code><ident type="class">att.global.responsibility</ident></code>

In the ST chapter (containing all the spec XIncludes), change this:

<code><include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/att.responsibility.xml"/></code>

to this:

<code><include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/att.global.responsibility.xml"/></code>

===PROSE===

1. In att.global.responsibility.xml, change the definition from this:

att.responsibility provides attributes indicating who is
responsible for something asserted by the markup and the
degree of certainty associated with it.

to this:

att.global.responsibility provides attributes indicating the agency
responsible for some aspect of the text, the markup or
something asserted by the markup, and the degree of certainty
associated with it.

and add a note to this effect:

Note that a simple @resp pointing to a person or
organization is likely to be somewhat ambiguous with regard
to the nature of the responsibility. For this reason, we
recommend that @resp be used to point not to an agent
(person or org) but to a respStmt, author, editor or similar
element which clarifies the exact role played by the agent.
Pointing to multiple respStmts allows the encoder to specify
clearly each of the roles played in part of a TEI file (creating,
transcribing, encoding, editing, proofing etc.).

2. In 3.4 (CO), update this paragraph:

For most of the elements discussed here, some encoders
may wish to indicate both a responsibility, that is, a
code indicating the person or agency responsible for
making the editorial intervention in question, and also
an indication of the degree of certainty which the encoder
wishes to associate with the intervention. Because these
requirements are common to many of the elements discussed
in this section, they are provided by attribute classes,
specifically att.editLike, which itself inherits
attributes from three further classes called
att.responsibility, att.source, and att.dimensions
respectively. Any of the elements discussed here thus may
potentially carry any of the following optional attributes:

to this:

For most of the elements discussed here, some encoders
may wish to indicate both a responsibility, that is, a
code indicating the person or agency responsible for
making the editorial intervention in question, and also
an indication of the degree of certainty which the encoder
wishes to associate with the intervention. These
requirements are served by the att.global.responsibility
class, along with att.source and att.dimensions. Any of
the elements discussed here thus may potentially carry
any of the following optional attributes:

3. In 3.4.1 (CO), change this:

The <att>resp</att> attribute is available for
all elements which are members of the <ident type="class">att.responsibility</ident>
class. The same class makes available a <att>cert</att>
attribute, which may be used...

to this:

The <att>resp</att> attribute is available for
all elements which are members of the <ident type="class">att.global.responsibility</ident>
class. The same class makes available a <att>cert</att>
attribute, which may be used...

4. In 17.2 (AI), change this:

<p>These elements are all members of the class <ident type="class">att.interpLike</ident>,
and thus share the following attributes:
<specList><specDesc key="att.interpLike" atts="type inst"/>
<specDesc key="att.responsibility" atts="cert resp"/></specList>
</p>

to this:

<p>These elements are all members of the class <ident type="class">att.interpLike</ident>,
and thus share the following attributes:
<specList><specDesc key="att.interpLike" atts="type inst"/>
They also inherit the following attributes from <ident type="class">att.global.responsibility</ident>
<specDesc key="att.global.responsibility" atts="cert resp"/></specList>
</p>

5. In 13.1.1 (ND), change this:

Some members of the <ident type="class">att.naming</ident> class
are also members of the <ident type="class">att.responsibility</ident>
class, from which they inherit the following attributes:
<specList><specDesc key="att.responsibility" atts="resp cert"/></specList>
This enables an encoder to record the agency responsible for a given
assertion (for example, the name) and the confidence placed in that
assertion by the encoder.

to this:

All members of the <ident type="class">att.naming</ident> class also
inherit the following attributes from the
<ident type="class">att.global.responsibility</ident> class:
<specList><specDesc key="att.responsibility" atts="resp cert"/></specList>
This enables an encoder to record the agency responsible for a given
assertion (for example, the name) and the confidence placed in that
assertion by the encoder.

6. In 13.3.2 (ND), replace this:

<p>The <gi>person</gi> element carries several attributes.
First, as a member of <ident type="class">att.editLike</ident>, which
is a subclass of the <ident type="class">att.responsibility</ident>
class, it carries the usual attributes for providing
details about the information
recorded for that person itself, such as its reliability or source: <specList>
<specDesc key="att.responsibility" atts="cert resp"/>
<specDesc key="att.editLike" atts="evidence"/>
<specDesc key="att.source" atts="source"/>
</specList>

with this:

<p>The <gi>person</gi> element carries several attributes.
As a member of the classes <ident type="class">att.global.responsibility</ident>,
and <ident type="class">att.editLike</ident>, which
is a subclass of the <ident type="class">att.source</ident>
class, it carries the usual attributes for providing
details about the information
recorded for that person, such as its reliability or source: <specList>
<specDesc key="att.global.responsibility" atts="cert resp"/>
<specDesc key="att.editLike" atts="evidence"/>
<specDesc key="att.source" atts="source"/>
</specList>

7. In 11.3.1.1 (PH), change this:

Several of these elements bear additional attributes
for specifying who responsible for the interpretation
represented by the markup, and the certainty associated
with it.

to this:

All of these elements bear additional attributes
for specifying who is responsible for the interpretation
represented by the markup, and the associated certainty.

8. In 12.1.2 (TC), change this:

The <ident type="class">att.textCritical</ident> class also
inherits the following attributes from the
<ident type="class">att.responsibility</ident> class: <specList>
<specDesc key="att.responsibility" atts="resp cert"/>
</specList>

to this:

These elements also
inherit the following attributes from the
<ident type="class">att.global.responsibility</ident> class: <specList>
<specDesc key="att.global.responsibility" atts="resp cert"/>
</specList>

9. DELETE from 21.3 (CE) the following paragraph:

<p>Some elements bear specialized <att>resp</att> or <att>agent</att>
attributes, which have specific meanings that vary from element to
element; the <gi>respons</gi> element should be reserved for the general
aspects of responsibility common to all text transcription and
markup, and should not be confused with the more specific attributes on
individual elements.</p>

10. In 3.4.1 (CO), change this part of an example:

<respStmt>
<resp>editor</resp>
<name xml:id="msm">C.M. Sperberg-McQueen</name>
</respStmt>

to this:

<respStmt xml:id="msm">
<resp>editor</resp>
<name>C.M. Sperberg-McQueen</name>
</respStmt>

to show the more robust recommended use of @resp to point to a respStmt rather than just a name. Then change the following comment from this:

Here the <att>resp</att> attribute
has been used to indicate responsibility for the
correction. Its value (<val>#msm</val>) is an
example of the <term>pointer</term> values discussed
in section <ptr target="#COXR"/>; in this case,
it points to a <gi>name</gi> element within the TEI
header, but any element might be indicated in this way,
including for example a <gi>person</gi> element (if the
module described in <ptr target="#ND"/> has been included),
or one of the bibliographic elements described in
<ptr target="#COBI"/>, if the correction has been taken
from some other source. The <att>resp</att> attribute is
available for all elements which are members of the
<ident type="class">att.responsibility</ident> class.

to this:

Here the <att>resp</att> attribute
has been used to indicate responsibility for the
correction. Its value (<val>#msm</val>) is an
example of the <term>pointer</term> values discussed
in section <ptr target="#COXR"/>; in this case,
it points to a <gi>respStmt</gi> element within the TEI
header, but any element might be indicated in this way,
including for example a <gi>name</gi> element, or (if the
module described in <ptr target="#ND"/> has been included) a
<gi>person</gi> element.
The <att>resp</att> attribute is
available for all elements which are members of the
<ident type="class">att.responsibility</ident> class.

Note the removal of the section about a bibliographical source, which I believe should be addressed using @source; when the issue of a global @source is addressed, this section may be modified again.

===SUPPORTED CUSTOMIZATIONS===

1. In tei_tite.odd, change this:

<classSpec ident="att.responsibility" mode="delete" module="tei" type="atts"/>


to this:

<classSpec ident="att.global.responsibility" mode="delete" module="tei" type="atts"/>


(I believe the mention of @atLeast in the comment to be erroneous.)

===BUILD TESTS===

Add to the build process a couple of tests for the use of @resp
and @cert in contexts where they were not previously allowed.

<hr/>
END OF IMPLEMENTATION PLAN
<hr/>

==PREVIOUS CONTENT==

===Proposal for a Global @resp attribute===

This page summarizes the discussions of LB, HC and MH on [http://sourceforge.net/p/tei/feature-requests/443/Feature request 443].

==THE PROBLEM PART 1: @resp==

Many, many users want to use @resp all over the place; but the current meaning of @resp is already confusingly dependent on its context:

@resp: "(responsible party) indicates the agency responsible for the intervention or interpretation, for example an editor or transcriber."

In the Glines, we have examples of @resp use to express responsibility for:

*editorial interventions such as <corr>, <ex>, <supplied>
*specifying a <spanGrp> or <interpGrp>
*writing a <note>
*identifying a <persName> as such
*specifying the place and date of someone's birth (<event>)
*counting the populations of red and grey squirrels between specific dates (<population>)
*providing supplementary info about a witness (<witDetail>)
*writing an abstract (<abstract>)
*describing the origin of a MS (<origin>)
*the entire act of transcribing and encoding a passage (<respons>)

and many more things. Sometimes @resp refers to manipulating text in an editorial capacity; sometimes to making judgements and applying markup; and sometimes to providing information or explanation.

There is clearly a need to allow people to use @resp globally. Since our own Glines show examples of it to describe the complete act of transcribing and encoding, it makes no sense to limit its context such that it could not be used for any of the component elements of an encoded text; and since we already have examples of its use in the header, there is no reason to exclude that either. Since there are examples of its use to specify responsibility for the selection and application of a TEI tag, there is no reason to prevent a user from assigning responsibility for the application of any TEI tag; ergo the attribute should be global.

The problem of what @resp refers to in any specific context remains, but the examples from the <respons> spec provide a straightforward solution: rather than pointing directly to an agent, @resp should point to a <respStmt>, in which the nature of the responsibility is clear in the <resp>(s).

==THE PROBLEM PART 2: @cert==

att.responsibility also contains @cert. Should this also be global?

Given that whenever we assign responsibility for something to an agent, there is always the possibility that we are not certain about it, then there is no context in which @resp could be used without the possible need for @cert. Therefore @cert should also be global.

The solution:

# Promote att.responsibility to att.global.responsibility, and make it a member of att.global.
# Add a note to @resp recommending that wherever possible it point not directly to an agent but to a <respStmt>.
# Add several examples to the att.responsibility specification showing a variety of uses of @resp pointing to <respStmt>.
# Update all references to att.responsibility in the Glines prose (e.g. in Names and Dates, we have "Some members of the att.naming class are also members of the att.responsibility class, from which they inherit the following attributes..."
# Look at all chapter sections which address the use of att.[global.]responsibility attributes and make any required changes, including suggesting that @resp point at <respStmt> where this is appropriate. This includes Chapters 3, 13, and 17.
# Expand 21.3 (http://www.tei-c.org/release/doc/tei-p5-doc/en/html/CE.html#CERESP), "Attribution of responsibility", so that it also mentions the use of @resp as a simpler alternative to a full <respons> element.

==PERIPHERAL ISSUE: @source==

We have had some discussions about whether it makes sense for @source to be global along with @resp and @cert. This is based on the notion that, if you're assigning responsibility to someone for something, and expressing some uncertainty about it, you may well wish to say on what source you're basing the assertion. We disagree about the need for this.

HC contends that in any place one might want to indicate an intellectual contribution by an editor/encoder of the document, one might equally well want to cite an external authority for that contribution. HC also feels @source has a stronger argument for universality than @cert.

MH is also close to being convinced of this. Since it involves a different attribute class, though, we could deal with it in a separate ticket.

Council agenda 2014-11

2014-11-16T18:27:39Z

Lou: /* Tuesday 18 November 2014 */

=Draft Agenda for TEI Technical Council Meeting 2014-11-17 to 2014-11-19=

== Monday 17 November 2014 ==
09:00 - 10:30
* TEI Simple
* Pure ODD
Apologies: discussion of contextual dependency issues not yet started.
Do we need <textNode>? or <mixedContent>? Decision is holding up completion of [http://tei.it.ox.ac.uk/Oxford/2014-10-odds/pureODDtutorial.xml [introductory tutorial]].
* TEI DH2015 HackAThon
* Correspondence
10:30 - 10:45
* Tea Break
10:45 - 13:00
* Ticket Discussion and Assignment
13:00 - 14:30
* Lunch
14:30 - 16:00 (15:30 - Tea Break)
* Tickets Recap and other discussion
16:00 - 17:00
* Ticket implementation or other TEI Work
18:00- Dinner at Josh Sosin's house. HC will pick up from the hotel at 18:15

== Tuesday 18 November 2014 ==
09:00 - 10:30
* JTEI Schema and authoring package: should the schema be adopted as an "official" customization, and should the authoring package be integrated into the oxygen-tei plugin? (MH)
* Global @resp and friends (MH, LB, HC)
* LOC date attrs (SB; see [http://loc.gov/standards/datetime/pre-submission.html LOC draft standard])
* ISO-TEI Workgroup on Speech Transcription (LB; see [http://bit.ly/1jyZC37 "final draft oct 2014"]) recommends one new element.
10:30 - 10:45
* Tea Break
10:45 - 13:00
* Tickets
13:00 - 14:00
* Lunch ?
14:00 - 17:00
* Tickets Discussion
18:00-
* DInner @ 19:00? Possibilities include Dos Perros (http://dosperrosrestaurant.com/); Bull City Burger and Brewery (http://www.bullcityburgerandbrewery.com/Bull_City_Burger_and_Brewery/Home.html); many others

== Wednesday 19 November 2014 ==
09:00 - 10:30
* Presentation on how OxGarage works (JC)
* TEI Validation Service (PSt)
* Critical Apparatus proposal update (HC)
10:30 - 10:45
* Tea Break
10:45 - 13:00
* Ticket Discussion and Assignment
13:10 - 14:30
* Lunch (?)
14:30 - 15:30
* Tickets Recap and other discussion
15:30
* tea break
15:30 - 17:00
* Ticket implementation or other TEI Work
18:00 -
*

[[Category:Council]]

Council agenda 2014-11

2014-11-16T18:15:33Z

Lou: /* Monday 17 November 2014 */

=Draft Agenda for TEI Technical Council Meeting 2014-11-17 to 2014-11-19=

== Monday 17 November 2014 ==
09:00 - 10:30
* TEI Simple
* Pure ODD
Apologies: discussion of contextual dependency issues not yet started.
Do we need <textNode>? or <mixedContent>? Decision is holding up completion of [http://tei.it.ox.ac.uk/Oxford/2014-10-odds/pureODDtutorial.xml [introductory tutorial]].
* TEI DH2015 HackAThon
* Correspondence
10:30 - 10:45
* Tea Break
10:45 - 13:00
* Ticket Discussion and Assignment
13:00 - 14:30
* Lunch
14:30 - 16:00 (15:30 - Tea Break)
* Tickets Recap and other discussion
16:00 - 17:00
* Ticket implementation or other TEI Work
18:00- Dinner at Josh Sosin's house. HC will pick up from the hotel at 18:15

== Tuesday 18 November 2014 ==
09:00 - 10:30
* JTEI Schema and authoring package: should the schema be adopted as an "official" customization, and should the authoring package be integrated into the oxygen-tei plugin? (MH)
* Global @resp and friends (MH, LB, HC)
* LOC date attrs (SB; see [http://loc.gov/standards/datetime/pre-submission.html LOC draft standard])
10:30 - 10:45
* Tea Break
10:45 - 13:00
* Tickets
13:00 - 14:00
* Lunch ?
14:00 - 17:00
* Tickets Discussion
18:00-
* DInner @ 19:00? Possibilities include Dos Perros (http://dosperrosrestaurant.com/); Bull City Burger and Brewery (http://www.bullcityburgerandbrewery.com/Bull_City_Burger_and_Brewery/Home.html); many others

== Wednesday 19 November 2014 ==
09:00 - 10:30
* Presentation on how OxGarage works (JC)
* TEI Validation Service (PSt)
* Critical Apparatus proposal update (HC)
10:30 - 10:45
* Tea Break
10:45 - 13:00
* Ticket Discussion and Assignment
13:10 - 14:30
* Lunch (?)
14:30 - 15:30
* Tickets Recap and other discussion
15:30
* tea break
15:30 - 17:00
* Ticket implementation or other TEI Work
18:00 -
*

[[Category:Council]]

Council agenda 2014-11

2014-11-16T18:10:34Z

Lou: /* Monday 17 November 2014 */

=Draft Agenda for TEI Technical Council Meeting 2014-11-17 to 2014-11-19=

== Monday 17 November 2014 ==
09:00 - 10:30
* TEI Simple
* Pure ODD
Do we need <textNode>? or <mixedContent>? Decision is holding up completion of [http://tei.it.ox.ac.uk/Oxford/2014-10-odds/pureODDtutorial.xml [introductory tutorial]].
* TEI DH2015 HackAThon
* Correspondence
10:30 - 10:45
* Tea Break
10:45 - 13:00
* Ticket Discussion and Assignment
13:00 - 14:30
* Lunch
14:30 - 16:00 (15:30 - Tea Break)
* Tickets Recap and other discussion
16:00 - 17:00
* Ticket implementation or other TEI Work
18:00- Dinner at Josh Sosin's house. HC will pick up from the hotel at 18:15

== Tuesday 18 November 2014 ==
09:00 - 10:30
* JTEI Schema and authoring package: should the schema be adopted as an "official" customization, and should the authoring package be integrated into the oxygen-tei plugin? (MH)
* Global @resp and friends (MH, LB, HC)
* LOC date attrs (SB; see [http://loc.gov/standards/datetime/pre-submission.html LOC draft standard])
10:30 - 10:45
* Tea Break
10:45 - 13:00
* Tickets
13:00 - 14:00
* Lunch ?
14:00 - 17:00
* Tickets Discussion
18:00-
* DInner @ 19:00? Possibilities include Dos Perros (http://dosperrosrestaurant.com/); Bull City Burger and Brewery (http://www.bullcityburgerandbrewery.com/Bull_City_Burger_and_Brewery/Home.html); many others

== Wednesday 19 November 2014 ==
09:00 - 10:30
* Presentation on how OxGarage works (JC)
* TEI Validation Service (PSt)
* Critical Apparatus proposal update (HC)
10:30 - 10:45
* Tea Break
10:45 - 13:00
* Ticket Discussion and Assignment
13:10 - 14:30
* Lunch (?)
14:30 - 15:30
* Tickets Recap and other discussion
15:30
* tea break
15:30 - 17:00
* Ticket implementation or other TEI Work
18:00 -
*

[[Category:Council]]

Council agenda 2014-10

2014-10-03T09:33:59Z

Lou: /* Teleconference Agenda */

==Teleconference Agenda==
* TEI Conference, Members Meeting, and Elections (JC)
* TEI Simple (SR)
* Update on CorrespDesc (PWS)
* November Face to Face (HC)
* Outstanding issues in Pure ODD (LB)
*
* your items here
*
*
* AOB

Council agenda 2014-06

2014-06-29T12:21:31Z

Lou: /* Tuesday 1 July 2014 */

=Draft Agenda for TEI Technical Council Meeting 2014-06-30 to 2014-07-02.=

== Monday 30 June 2014 ==
09:00 - 10:30
* TEI Simple
* PureODD: Can Lou tell us where we're at and where we're going, and Sebastian talk about implementation (working, planned, and blue-sky)?
** whether it makes sense to have @allowText on sub elements of <content>
** what a set of elementRef as direct children of <content> means
** what the same thing means with @allowText
** when and how to convert Gidlines to Pure ODD
** testing testing testing
* TEI DH2014 HackAThon
15:00 - 17:00
* Ticket implementation or other TEI Work
18:00-
* Picnic in University Parks. (James will lead from Rewley House)

== Tuesday 1 July 2014 ==
09:00 - 10:30
* Text directionality additions: final reading and approval
* Update on ISO Speech transcription proposal (http://bit.ly/1jyZC37)
* Update on TBX ODD
* Global Applicability of att.responsibility
* Autumn Face-to-Face meeting
10:30 - 13:00
* Tickets
13:00 - 14:00
* Lunch (Rewley Dining Room)
14:00 - 15:00
* Tickets Recap or other discussion
15:00 - 17:00
* Ticket implementation or other TEI Work
18:00-
* Supper: Old Bookbinders Ale House http://oldbookbinders.co.uk/

== Wednesday 2 July 2014 ==
09:00 - 10:30
* MDH on Guidelines translation (with help from FC): Italian and German teams are not making much progress. Is there anything we can do?
* TEI Standoff and Linked Data representations
* TEI Future Developments (e.g. Roadmap to P6, Bluesky thinking, etc.)
10:30 - 13:00
* Ticket Discussion and Assignment
13:00 - 14:30
* Lunch (Pierre Victoire)
14:30 - 15:00
* Tickets Recap and other discussion
15:00 - 17:00
* Ticket implementation or other TEI Work
18:00 -
* Supper: restaurant to be agreed.

[[Category:Council]]

Text Directionality Draft

2014-04-28T12:47:40Z

Lou:

This preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]] is now (28 April 2014) in the process of being transferred to the TEI svn repository where it will appear as a new section in file Source/Guidelines/en/WD-NonStandardCharacters.xml

'''Please do not make further changes here.'''

See the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions in which the same language may appear in different modes, for example either vertically or horizontally. East Asian scripts were traditionally written from top to bottom within the line, with their lines sequenced from right to left. Although modern Japanese, Chinese, and Korean are often written horizontally, the traditional vertical writing mode is still widely used. There are also comparatively rare cases of ancient scripts written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or scripts such as Ogham where the writing direction is from bottom to top around the edge of an inscribed object.

When different languages are combined, it is possible that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts; for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed vertically and sometimes horizontally. The writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will usually imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode.

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. The order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardized way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem: first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script); and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> specifies that "characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: upright">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: upright</code> specifies that "characters from horizontal-only scripts are rendered upright, i.e. in their standard horizontal orientation. Characters from vertical scripts are set with their intrinsic orientation and shaped normally" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]).

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

[Question MDH to LB: Why is this bit detached from the original horizontal text section above? Because he section above isn't specifically about horizontal texts only, though it uses one as an initial example]

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely] [(MDH) A <g> element would normally be used for a glyph which has no Unicode representation; therefore it has no directionality per the Unicode character database; therefore its effect would be potentially disruptive. Imagine a case where a rtl text run ends with a weak-directionality character such as a period, followed by a <g> for a glyph which the encoder knows should represent an rtl character, but which isn't in Unicode, followed by a strongly ltr character.] [If the encoder knows that the glyph or character concerned has a strongly ltr character then they should use the <charProp> element to document this fact within the <glyph> or <char> definition, as per http://www.tei-c.org/release/doc/tei-p5-doc/en/html/WD.html#ucsprops. If they want a rendering agent to deal with the character properly, they are at liberty to put a strongly ltr character as content for the <g> ]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
<lb/>ΗΕΡΜΟΝΤΙΝA
<lb/><seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg>
<lb/>ΕΝΟΣΥΕΝΕΑϜ
<lb/><seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg>
<lb/>ΡΕΤΑΙΑΣΟΝΑ
<lb/><seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg>
<lb/>ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

As with other parts of the CSS specification, the intended effect of CSS Transforms properties and values are defined with reference to a specific [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model]; the language is designed to describe how an HTML document should be formatted. This is not, of course, the case for the TEI, which lacks any explicit processing or formatting model, and attempts to define objects as far as possible without consideration of their visual appearance. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not particularly problematic. CSS provides a useful and well-defined vocabulary to describe many aspects of the appearance of source texts, benefitting particularly from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-26T15:20:19Z

Lou: /* Horizontal directionality */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions in which the same language may appear in different modes, for example either vertically or horizontally. East Asian scripts were traditionally written from top to bottom within the line, with their lines sequenced from right to left. Although modern Japanese, Chinese, and Korean are often written horizontally, the traditional vertical writing mode is still widely used. There are also comparatively rare cases of ancient scripts written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or scripts such as Ogham where the writing direction is from bottom to top around the edge of an inscribed object.

When different languages are combined, it is possible that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts; for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed vertically and sometimes horizontally. The writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will usually imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode.

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. The order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardized way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem: first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script); and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> specifies that "characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: upright">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: upright</code> specifies that "characters from horizontal-only scripts are rendered upright, i.e. in their standard horizontal orientation. Characters from vertical scripts are set with their intrinsic orientation and shaped normally" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]).

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

[Question MDH to LB: Why is this bit detached from the original horizontal text section above? Because he section above isn't specifically about horizontal texts only, though it uses one as an initial example]

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely] [(MDH) A <g> element would normally be used for a glyph which has no Unicode representation; therefore it has no directionality per the Unicode character database; therefore its effect would be potentially disruptive. Imagine a case where a rtl text run ends with a weak-directionality character such as a period, followed by a <g> for a glyph which the encoder knows should represent an rtl character, but which isn't in Unicode, followed by a strongly ltr character.] [If the encoder knows that the glyph or character concerned has a strongly ltr character then they should use the <charProp> element to document this fact within the <glyph> or <char> definition, as per http://www.tei-c.org/release/doc/tei-p5-doc/en/html/WD.html#ucsprops. If they want a rendering agent to deal with the character properly, they are at liberty to put a strongly ltr character as content for the <g> ]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
<lb/>ΗΕΡΜΟΝΤΙΝA
<lb/><seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg>
<lb/>ΕΝΟΣΥΕΝΕΑϜ
<lb/><seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg>
<lb/>ΡΕΤΑΙΑΣΟΝΑ
<lb/><seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg>
<lb/>ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

As with other parts of the CSS specification, the intended effect of CSS Transforms properties and values are defined with reference to a specific [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model]; the language is designed to describe how an HTML document should be formatted. This is not, of course, the case for the TEI, which lacks any explicit processing or formatting model, and attempts to define objects as far as possible without consideration of their visual appearance. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not particularly problematic. CSS provides a useful and well-defined vocabulary to describe many aspects of the appearance of source texts, benefitting particularly from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-26T15:11:29Z

Lou: /* Vertical text with embedded horizontal text */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions in which the same language may appear in different modes, for example either vertically or horizontally. East Asian scripts were traditionally written from top to bottom within the line, with their lines sequenced from right to left. Although modern Japanese, Chinese, and Korean are often written horizontally, the traditional vertical writing mode is still widely used. There are also comparatively rare cases of ancient scripts written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or scripts such as Ogham where the writing direction is from bottom to top around the edge of an inscribed object.

When different languages are combined, it is possible that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts; for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed vertically and sometimes horizontally. The writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will usually imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode.

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. The order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardized way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem: first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script); and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> specifies that "characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: upright">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: upright</code> specifies that "characters from horizontal-only scripts are rendered upright, i.e. in their standard horizontal orientation. Characters from vertical scripts are set with their intrinsic orientation and shaped normally" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]).

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

[Question MDH to LB: Why is this bit detached from the original horizontal text section above? Because he section above isn't specifically about horizontal texts only, though it uses one as an initial example]

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely] [(MDH) A <g> element would normally be used for a glyph which has no Unicode representation; therefore it has no directionality per the Unicode character database; therefore its effect would be potentially disruptive. Imagine a case where a rtl text run ends with a weak-directionality character such as a period, followed by a <g> for a glyph which the encoder knows should represent an rtl character, but which isn't in Unicode, followed by a strongly ltr character.]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
<lb/>ΗΕΡΜΟΝΤΙΝA
<lb/><seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg>
<lb/>ΕΝΟΣΥΕΝΕΑϜ
<lb/><seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg>
<lb/>ΡΕΤΑΙΑΣΟΝΑ
<lb/><seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg>
<lb/>ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

As with other parts of the CSS specification, the intended effect of CSS Transforms properties and values are defined with reference to a specific [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model]; the language is designed to describe how an HTML document should be formatted. This is not, of course, the case for the TEI, which lacks any explicit processing or formatting model, and attempts to define objects as far as possible without consideration of their visual appearance. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not particularly problematic. CSS provides a useful and well-defined vocabulary to describe many aspects of the appearance of source texts, benefitting particularly from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-26T14:58:42Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions in which the same language may appear in different modes, for example either vertically or horizontally. East Asian scripts were traditionally written from top to bottom within the line, with their lines sequenced from right to left. Although modern Japanese, Chinese, and Korean are often written horizontally, the traditional vertical writing mode is still widely used. There are also comparatively rare cases of ancient scripts written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or scripts such as Ogham where the writing direction is from bottom to top around the edge of an inscribed object.

When different languages are combined, it is possible that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts; for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed vertically and sometimes horizontally. The writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will usually imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode.

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. The order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardized way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem: first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script); and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: upright">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The value <code>text-orientation: mixed</code> specifies that "characters from horizontal-only scripts are rendered upright, i.e. in their standard horizontal orientation. Characters from vertical scripts are set with their intrinsic orientation and shaped normally" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]).

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

[Question MDH to LB: Why is this bit detached from the original horizontal text section above? Because he section above isn't specifically about horizontal texts only, though it uses one as an initial example]

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely] [(MDH) A <g> element would normally be used for a glyph which has no Unicode representation; therefore it has no directionality per the Unicode character database; therefore its effect would be potentially disruptive. Imagine a case where a rtl text run ends with a weak-directionality character such as a period, followed by a <g> for a glyph which the encoder knows should represent an rtl character, but which isn't in Unicode, followed by a strongly ltr character.]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
<lb/>ΗΕΡΜΟΝΤΙΝA
<lb/><seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg>
<lb/>ΕΝΟΣΥΕΝΕΑϜ
<lb/><seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg>
<lb/>ΡΕΤΑΙΑΣΟΝΑ
<lb/><seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg>
<lb/>ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

As with other parts of the CSS specification, the intended effect of CSS Transforms properties and values are defined with reference to a specific [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model]; the language is designed to describe how an HTML document should be formatted. This is not, of course, the case for the TEI, which lacks any explicit processing or formatting model, and attempts to define objects as far as possible without consideration of their visual appearance. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not particularly problematic. CSS provides a useful and well-defined vocabulary to describe many aspects of the appearance of source texts, benefitting particularly from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-26T14:55:03Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions in which the same language may appear in different modes, for example either vertically or horizontally. East Asian scripts were traditionally written from top to bottom within the line, with their lines sequenced from right to left. Although modern Japanese, Chinese, and Korean are often written horizontally, the traditional vertical writing mode is still widely used. There are also comparatively rare cases of ancient scripts written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or scripts such as Ogham where the writing direction is from bottom to top around the edge of an inscribed object.

When different languages are combined, it is possible that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts; for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal orientation. The writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will usually imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode.

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. The order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardized way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem: first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script); and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: upright">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The value <code>text-orientation: mixed</code> specifies that "characters from horizontal-only scripts are rendered upright, i.e. in their standard horizontal orientation. Characters from vertical scripts are set with their intrinsic orientation and shaped normally" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]).

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

[Question MDH to LB: Why is this bit detached from the original horizontal text section above? Because he section above isn't specifically about horizontal texts only, though it uses one as an initial example]

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely] [(MDH) A <g> element would normally be used for a glyph which has no Unicode representation; therefore it has no directionality per the Unicode character database; therefore its effect would be potentially disruptive. Imagine a case where a rtl text run ends with a weak-directionality character such as a period, followed by a <g> for a glyph which the encoder knows should represent an rtl character, but which isn't in Unicode, followed by a strongly ltr character.]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
<lb/>ΗΕΡΜΟΝΤΙΝA
<lb/><seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg>
<lb/>ΕΝΟΣΥΕΝΕΑϜ
<lb/><seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg>
<lb/>ΡΕΤΑΙΑΣΟΝΑ
<lb/><seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg>
<lb/>ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

As with other parts of the CSS specification, the intended effect of CSS Transforms properties and values are defined with reference to a specific [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model]; the language is designed to describe how an HTML document should be formatted. This is not, of course, the case for the TEI, which lacks any explicit processing or formatting model, and attempts to define objects as far as possible without consideration of their visual appearance. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not particularly problematic. CSS provides a useful and well-defined vocabulary to describe many aspects of the appearance of source texts, benefitting particularly from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-26T14:54:22Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions in which the same language may appear in different modes, for example either vertically or horizontally. East Asian scripts were traditionally written from top to
bottom within the line, with their lines sequenced from right to
left. Although modern Japanese, Chinese, and Korean are often written
horizontally, the traditional vertical writing mode is still widely used. There are also comparatively rare cases of ancient scripts written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or scripts such as Ogham where the writing direction is from bottom to top around the edge of an inscribed object.

When different languages are combined, it is possible that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts; for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal orientation. The writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will usually imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode.

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. The order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardized way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem: first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script); and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: upright">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The value <code>text-orientation: mixed</code> specifies that "characters from horizontal-only scripts are rendered upright, i.e. in their standard horizontal orientation. Characters from vertical scripts are set with their intrinsic orientation and shaped normally" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]).

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

[Question MDH to LB: Why is this bit detached from the original horizontal text section above? Because he section above isn't specifically about horizontal texts only, though it uses one as an initial example]

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely] [(MDH) A <g> element would normally be used for a glyph which has no Unicode representation; therefore it has no directionality per the Unicode character database; therefore its effect would be potentially disruptive. Imagine a case where a rtl text run ends with a weak-directionality character such as a period, followed by a <g> for a glyph which the encoder knows should represent an rtl character, but which isn't in Unicode, followed by a strongly ltr character.]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
<lb/>ΗΕΡΜΟΝΤΙΝA
<lb/><seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg>
<lb/>ΕΝΟΣΥΕΝΕΑϜ
<lb/><seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg>
<lb/>ΡΕΤΑΙΑΣΟΝΑ
<lb/><seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg>
<lb/>ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

As with other parts of the CSS specification, the intended effect of CSS Transforms properties and values are defined with reference to a specific [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model]; the language is designed to describe how an HTML document should be formatted. This is not, of course, the case for the TEI, which lacks any explicit processing or formatting model, and attempts to define objects as far as possible without consideration of their visual appearance. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not particularly problematic. CSS provides a useful and well-defined vocabulary to describe many aspects of the appearance of source texts, benefitting particularly from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-23T11:05:54Z

Lou: /* Horizontal directionality */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is possible that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts; for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal orientation. The writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will usually imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode.

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. The order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardized way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem: first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script); and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: upright">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The value <code>text-orientation: mixed</code> specifies that "characters from horizontal-only scripts are rendered upright, i.e. in their standard horizontal orientation. Characters from vertical scripts are set with their intrinsic orientation and shaped normally" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]).

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

[Question MDH to LB: Why is this bit detached from the original horizontal text section above? Because he section above isn't specifically about horizontal texts only, though it uses one as an initial example]

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely] [(MDH) A <g> element would normally be used for a glyph which has no Unicode representation; therefore it has no directionality per the Unicode character database; therefore its effect would be potentially disruptive. Imagine a case where a rtl text run ends with a weak-directionality character such as a period, followed by a <g> for a glyph which the encoder knows should represent an rtl character, but which isn't in Unicode, followed by a strongly ltr character.]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
<lb/>ΗΕΡΜΟΝΤΙΝA
<lb/><seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg>
<lb/>ΕΝΟΣΥΕΝΕΑϜ
<lb/><seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg>
<lb/>ΡΕΤΑΙΑΣΟΝΑ
<lb/><seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg>
<lb/>ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

As with other parts of the CSS specification, the intended effect of CSS Transforms properties and values are defined with reference to a specific [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model]; the language is designed to describe how an HTML document should be formatted. This is not, of course, the case for the TEI, which lacks any explicit processing or formatting model, and attempts to define objects as far as possible without consideration of their visual appearance. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not particularly problematic. CSS provides a useful and well-defined vocabulary to describe many aspects of the appearance of source texts, benefitting particularly from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T17:08:52Z

Lou: /* Caveats */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id" style="text-orientation:upright">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id" style="text-orientation:upright">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
<lb/>ΗΕΡΜΟΝΤΙΝA
<lb/><seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg>
<lb/>ΕΝΟΣΥΕΝΕΑϜ
<lb/><seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg>
<lb/>ΡΕΤΑΙΑΣΟΝΑ
<lb/><seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg>
<lb/>ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

As with other parts of the CSS specification, the intended effect of CSS Transforms properties and values are defined with reference to a specific [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model]; the language is designed to describe how an HTML document should be formatted. This is not, of course, the case for the TEI which lacks any explicit processing or formatting model, and attempts to define objects as far as possible without consideration of their visual appearance. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not particularly problematic. CSS provides a useful and well-defined vocabulary to describe many aspects of the appearance of source texts, benefitting particularly from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T16:59:46Z

Lou: /* Boustrophedon */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id" style="text-orientation:upright">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id" style="text-orientation:upright">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
<lb/>ΗΕΡΜΟΝΤΙΝA
<lb/><seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg>
<lb/>ΕΝΟΣΥΕΝΕΑϜ
<lb/><seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg>
<lb/>ΡΕΤΑΙΑΣΟΝΑ
<lb/><seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg>
<lb/>ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T16:55:22Z

Lou: /* Rotation */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id" style="text-orientation:upright">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id" style="text-orientation:upright">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. This CSS module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

We might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T16:53:00Z

Lou: /* Horizontal directionality */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id" style="text-orientation:upright">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id" style="text-orientation:upright">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<s xml:lang="en" style="direction: ltr">The Arabic term
<term xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?] [how might a <g> element introduce ambiguity? only if the glyph or character concerned is vague about its directionality surely]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T16:49:04Z

Lou: /* Bottom-to-top writing */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id" style="text-orientation:upright">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id" style="text-orientation:upright">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====
Of the rather small number of scripts which appear to be written bottom-to-top, perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

[can't we find an Ogham example? ]

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T16:47:02Z

Lou: /* Vertical orientation in horizontal scripts */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id" style="text-orientation:upright">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id" style="text-orientation:upright">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where no vertically-written script is involved. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode the third of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
<lb/>Cash Value
<lb/>of
<lb/>Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its lines are to be read from left to right (so the line containing "of" is to the right of that containing "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T16:40:38Z

Lou: /* Vertical text with embedded horizontal text */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters, in particular for punctuation which needs to be positioned differently in vertical and in horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages which are normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

The text-orientation property allows us to indicate whether or not glyphs are rotated. In the following example, we have indicated that the list uses a vertical-rl writing mode, but that the orientation of individual glyphs may vary:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). Since the default value for <code>text-orientation</code> is "mixed", this rule is not strictly required. However, if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then an encoding like the following could be used to make this explicit:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id" style="text-orientation:upright">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id" style="text-orientation:upright">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T16:30:50Z

Lou: /* Vertical writing modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of Japanese), or left-to-right (as in the case of Mongolian).

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

For the sake of simplicity, we have not attempted to capture in this encoding such aspects as the indenting of lines in the first Japanese version, or the central alignment of the other two versions, nor any other renditional features such as font weight or size etc. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T14:32:17Z

Lou: /* Examples */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

The CSS recommendations provides several properties which can be used to encode aspects of the "writing mode". The most useful of these is the property "writing-mode" which may be used to specify a reading-order for both characters within a single line and lines within a single block of text. The property "text-orientation" may also used to indicate the orientation of individual characters with respect to the line, and the property "direction" to determine the reading order of characters within a line only. We give some examples of each below.

====Vertical writing modes====

The writing-mode property is particularly useful for languages which can be written in different writing modes, such as Chinese and Japanese. It has the following possible values:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

Each value has two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian).

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T14:04:34Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (we use this term to refer to the orientation of individual glyphs within a line and the order in which they should be read), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

As we noted above, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusual examples running bottom-to-top). Another CSS property, called the writing mode, can be used to specify this:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property have two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). Both Chinese and Japanese can be written in different writing modes, and the ability to encode which has been used in a given document is therefore very useful.

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-21T13:56:56Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the way (or ways) that those glyphs are arranged on the writing surface. For the majority of modern languages, writing is arranged as a series of lines which are to be read from top to bottom. Within each line, individual characters are frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). Writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to Unicode character U+FE11, the vertical mode comma. This ensures that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example when a language using Roman script is embedded within vertically organized Chinese text, it may sometimes be displayed in vertical and sometimes in horizontal writing mode. And the writing mode may also vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this] [if we cannot find substantial evidence to support this recommendation we should imho drop it. LB]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. T he order in which the Arabic characters appear when rendered would be the same, even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

This is because Arabic glyphs are always displayed right to left, even when they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a strong left-to-right bidirectionality setting, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes). These additional codepoints can be used to signal to rendering software that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code for each. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section [ref to #STGAre here] ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this W3C module has the status of a candidate recommendation: see further http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties associated with writing modes, notably :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in [ref to #HD57-1 here]). Although the CSS specifications are mainly used to provide instructions for software when rendering a digital text, they also provide a useful means of describing the visual properties of a pre-existing document in a formal and standardised way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will probably include many other properties of course.

===Examples===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

As we noted above, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusual examples running bottom-to-top). Another CSS property, called the writing mode, can be used to specify this:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property have two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). Both Chinese and Japanese can be written in different writing modes, and the ability to encode which has been used in a given document is therefore very useful.

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-01T19:55:47Z

Lou: /* Text directionality */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the conventions governing the disposition of those glyphs on the writing surface. For the majority of modern languages, writing is presented as a series of lines which are to be read from top to bottom. Within each line, individual characters are most frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). However, writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to the vertical mode glyph, U+FE11, to ensure that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example English embedded within vertically organized Chinese text. Similarly, the default writing mode may vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. Even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

the order in which the Arabic characters appear when rendered would be the same. This is because Arabic glyphs are always displayed right to left, even if they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a bidirectionality setting of strong left-to-right, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes), which are additional codepoints whose function is to signal to a user-agent that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section ?? ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this module has the status of a candidate recommendation: see http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties listed here:

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in section ??). Although the CSS specifications are written primarily to provide instructions for the use of software when rendering a digital text, it is also a useful as a means of describing the visual properties of a pre-existing document in a formal way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will also include many other properties of course.

===Examples===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="direction: rtl; unicode-bidi: embed">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property to record the observed directionality of the text is unambiguous, even though it is (as we noted above) superfluous. <ref>The use of the <code>unicode-bidi</code> property here may require some explanation. By default this property has the value "normal", the effect of which in this context would be to ignore any value supplied for the <code>direction</code> property. The CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm."</ref>

Mixed directionality is very common in languages such as Arabic and Hebrew, particularly when numbers (which are always given LTR) or phrases from other LTR languages are embedded, and it is quite unusual though not impossible for ambiguities to arise.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

As we noted above, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusual examples running bottom-to-top). Another CSS property, called the writing mode, can be used to specify this:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property have two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence are arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). Both Chinese and Japanese can be written in different writing modes, and the ability to encode which has been used in a given document is therefore very useful.

The following example shows three versions of the same poem, first in Japanese, written top to bottom; next in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

We might encode this as follows:

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-04-01T18:57:04Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the conventions governing the disposition of those glyphs on the writing surface. For the majority of modern languages, writing is presented as a series of lines which are to be read from top to bottom. Within each line, individual characters are most frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). However, writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to the vertical mode glyph, U+FE11, to ensure that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example English embedded within vertically organized Chinese text. Similarly, the default writing mode may vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. Even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

the order in which the Arabic characters appear when rendered would be the same. This is because Arabic glyphs are always displayed right to left, even if they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a bidirectionality setting of strong left-to-right, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes), which are additional codepoints whose function is to signal to a user-agent that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the rightmost end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code. In situations where this approach may result in ambiguity or lack of precision, or if the encoder wishes to record directional information explicitly in their encoding, we recommend using the global @style attribute to supply detail about the writing mode applicable to the content of any element. The @style attribute (discussed in section ?? ) permits use of any formatting language; for these purposes however, we recommend use of CSS, which now includes a Writing Modes module <ref>At the time of writing, this module has the status of a candidate recommendation: see http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties listed here:

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). Rather than specify it on every element, it will often be more efficient, to express sets of commonly-used styling rules as <rendition> elements in the <teiHeader> and then point to them using the global @rendition attribute (see further the discussion in section ??). Although the CSS specifications are written primarily to provide instructions for the use of software when rendering a digital text, it is also a useful as a means of describing the visual properties of a pre-existing document in a formal way.

In the next section, we present some examples of how CSS can be used to describe a variety of writing modes. A full description of the appearance of a document will also include many other properties of course.

===Text directionality===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="unicode-bidi: embed; direction: rtl">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property is straightforward, but the <code>unicode-bidi</code> property requires some explanation. These three segments are all inline; they form part of a single sentence, although they happen to be encoded on separate lines in this example. The default value for <code>unicode-bidi</code> is "normal", and the CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm." In other words, if we want to make it clear that the <code>direction</code> property is effective here, we must include a value for <code>unicode-bidi</code> which will make it so.

However, as mentioned above, all of the directional encoding in this example is superfluous; ambiguity does not arise in this particular case. Moreover, "ltr" is the default value for the <code>direction</code> property, so we do not need to specify it for the English segments. However, consider the following example, contributed by Efraim Feinstein, in which Hebrew and English text are mixed. (This example is presented in the form of graphics, because we cannot rely on user agents that may be rendering or displaying these Guidelines to provide a consistent output.)

[[File:En he embedding.png|800px]]

Here, an English period appears in between two runs of Hebrew text. Should that period be interpreted as part of a single run of right-to-left text, or should it be deemed to terminate the first run and precede the second? For the Unicode Bidi Algorithm, punctuation is not strongly directional; it inherits directionality from the surrounding characters. Without further clues, therefore, it would interpret the example as a sequence of three runs (English, Hebrew, English), and arrive at an incorrect interpretation. A clear and correct interpretation requires that not only that the glyphs themselves be transcribed in the correct logical order, but that the encoding eliminate potential ambiguity by delimiting the two Hebrew runs separately, like this:

<syntaxhighlight lang="xml">
<p>
Here's a sentence that begins in English
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ויש מלים בעברית והפסק</seg>.
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ועוד מלים בעברית</seg>
and it continues in English.
</p>
</syntaxhighlight>

Here the English is unmarked for directionality, but the period is clearly not included in either of the RTL runs, so the ambiguity inherent in the plain text is avoided. Once again, we might argue that the <code>@xml:lang</code> attribute should provide enough information; the important component here is the explicit delimitation of two distinct RTL runs. But additional clarity in the encoding certainly does no harm.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

So far, we have looked only at left-to-right and right-to-left text running horizontally, using the <code>direction: ltr|rtl</code> property. However, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusal examples running bottom-to-top, as we shall see below). Handling vertical directionality requires the use of another CSS property, the writing mode:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property include two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence may be arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). This example shows a Japanese haiku poem transcribed first in Japanese, then in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl"
xml:id="furu-ike-ya_jp" corresp="#furu-ike-ya_romaji #furu-ike-ya_en">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb"
xml:id="furu-ike-ya_romaji" corresp="#furu-ike-ya_jp #furu-ike-ya_en">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en"
xml:id="furu-ike-ya_en" corresp="#furu-ike-ya_jp #furu-ike-ya_romaji">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-03-31T13:02:43Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the conventions governing the disposition of those glyphs on the writing surface. For the majority of modern languages, writing is presented as a series of lines which are to be read from top to bottom. Within each line, individual characters are most frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). However, writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language normally uses the same ''writing mode'' (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to the vertical mode glyph, U+FE11, to ensure that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example English embedded within vertically organized Chinese text. Similarly, the default writing mode may vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. Even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

the order in which the Arabic characters appear when rendered would be the same. This is because Arabic glyphs are always displayed right to left, even if they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a bidirectionality setting of strong left-to-right, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks such as the period or comma for example) have weak or neutral settings because they may appear in several contexts.

The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render sequences of characters which have differing directionality properties in a predictable and reliable way, using only those properties. <ref>Because this algorithm may not always give the desired result, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes), which are additional codepoints whose function is to signal to a user-agent that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. "In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available." (http://www.w3.org/International/questions/qa-bidi-controls)</ref>. It should be remembered however that individual sequences of characters are always stored in a file in the order in which they should be read, irrespective of the order in which the characters making up a sequence should be displayed or rendered. For example, in a RTL language such as Hebrew, the first character in a file will be that which is displayed at the end of the first line of text.

An encoder wishing to document or to control the order in which sequences of characters in a TEI document are displayed will usually do so by segmenting the text into sequences presented in the desired order and specifying an appropriate language code. In situations where this approach may result in ambiguity or lack of precision, we recommend using the @style attribute to supply more precise directionality information. The @style attribute (discussed in section ?? of the Guidelines) permits use of any formatting language; for these purposes however, we recommend use of CSS, since this now includes a Writing Modes module <ref>At the time of writing, this module has the status of a candidate recommendation: see http://dev.w3.org/csswg/css-writing-modes/ </ref> which permits direct specification of a number of useful properties :

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

The global TEI @style attribute applies to the element on which it is specified (and in most cases, its descendants). It is also appropriate, and will often be more efficient, to express the rules in TEI <rendition> elements in the <teiHeader> and point to them using @rendition attributes. It should also be remembered that the CSS specifications are written primarily to guide users providing instructions for the rendering of digital texts, and implementers creating user-agents which will act on these instructions. However, our usage in the context of a TEI document is primarily ''descriptive'' rather than ''prescriptive''; we are typically describing the features of a text we are encoding, rather than providing instructions for rendering it. Our purpose below is not to enumerate an exhaustive set of strategies for encoding any writing mode feature you may encounter; rather we will show some simple examples which serve as an introduction to the topic.

===Text directionality===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="unicode-bidi: embed; direction: rtl">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property is straightforward, but the <code>unicode-bidi</code> property requires some explanation. These three segments are all inline; they form part of a single sentence, although they happen to be encoded on separate lines in this example. The default value for <code>unicode-bidi</code> is "normal", and the CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm." In other words, if we want to make it clear that the <code>direction</code> property is effective here, we must include a value for <code>unicode-bidi</code> which will make it so.

However, as mentioned above, all of the directional encoding in this example is superfluous; ambiguity does not arise in this particular case. Moreover, "ltr" is the default value for the <code>direction</code> property, so we do not need to specify it for the English segments. However, consider the following example, contributed by Efraim Feinstein, in which Hebrew and English text are mixed. (This example is presented in the form of graphics, because we cannot rely on user agents that may be rendering or displaying these Guidelines to provide a consistent output.)

[[File:En he embedding.png|800px]]

Here, an English period appears in between two runs of Hebrew text. Should that period be interpreted as part of a single run of right-to-left text, or should it be deemed to terminate the first run and precede the second? For the Unicode Bidi Algorithm, punctuation is not strongly directional; it inherits directionality from the surrounding characters. Without further clues, therefore, it would interpret the example as a sequence of three runs (English, Hebrew, English), and arrive at an incorrect interpretation. A clear and correct interpretation requires that not only that the glyphs themselves be transcribed in the correct logical order, but that the encoding eliminate potential ambiguity by delimiting the two Hebrew runs separately, like this:

<syntaxhighlight lang="xml">
<p>
Here's a sentence that begins in English
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ויש מלים בעברית והפסק</seg>.
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ועוד מלים בעברית</seg>
and it continues in English.
</p>
</syntaxhighlight>

Here the English is unmarked for directionality, but the period is clearly not included in either of the RTL runs, so the ambiguity inherent in the plain text is avoided. Once again, we might argue that the <code>@xml:lang</code> attribute should provide enough information; the important component here is the explicit delimitation of two distinct RTL runs. But additional clarity in the encoding certainly does no harm.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

So far, we have looked only at left-to-right and right-to-left text running horizontally, using the <code>direction: ltr|rtl</code> property. However, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusal examples running bottom-to-top, as we shall see below). Handling vertical directionality requires the use of another CSS property, the writing mode:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property include two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence may be arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). This example shows a Japanese haiku poem transcribed first in Japanese, then in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl"
xml:id="furu-ike-ya_jp" corresp="#furu-ike-ya_romaji #furu-ike-ya_en">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb"
xml:id="furu-ike-ya_romaji" corresp="#furu-ike-ya_jp #furu-ike-ya_en">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en"
xml:id="furu-ike-ya_en" corresp="#furu-ike-ya_jp #furu-ike-ya_romaji">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-03-27T17:56:04Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the conventions governing the disposition of those glyphs on the writing surface. For the majority of modern languages, writing is presented as a series of lines which are to be read from top to bottom. Within each line, individual characters are most frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). However, writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language always uses the same ''writing mode'' (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to the vertical mode glyph, U+FE11, to ensure that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example English embedded within vertically organized Chinese text. Similarly, the default writing mode may vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. Even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

the order in which the Arabic characters appear will be the same. This is because Arabic glyphs are to be read left to right, even if they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a bidirectionality setting of strong left-to-right, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks, for example) have weak or neutral settings because they may appear in several contexts. The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render these bidirectional texts with predictable and reliable results, using only the bidirectionality class values of their glyphs. Because this algorithm is not always infallible, Unicode also provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes), which are additional codepoints whose function is to signal to a user-agent that a specific directionality setting should be turned on or off. However, in the case of documents encoded in XML, there is no need to use such characters, and in fact the W3C explicitly advises against it. <ref>"In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available," http://www.w3.org/International/questions/qa-bidi-controls </ref>

. We concur with this recommendation, and the remainder of this section and the next provide a set of encoding strategies for handling text directionality without the use of directional formatting characters. The approach we recommend is based on two external specifications, in line with our normal practice of incorporating existing standards where they are available and appropriate. Those specifications are the CSS Writing Modes module (http://dev.w3.org/csswg/css-writing-modes/) and the CSS Transforms module (http://www.w3.org/TR/css3-transforms/). Since (at the time of writing) neither of these modules has yet reached the stage of a Recommendation, the advice offered below should be regarded as provisional, and you should check your usage of the properties concerned against the current version of each specification where possible.

The following sections will present a few simple examples of phenomena relating to text directionality and transformation, along with some suggested encoding strategies based on the following CSS properties from CSS Writing Modes:

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

along with the <code>transform</code> property from CSS Transforms.

In the following examples, CSS rules are encoded in the global TEI @style attribute, which applies them directly to the element on which they are specified (and in most cases, its descendants). It is also appropriate, and will often be more efficient, to express the rules in TEI <rendition> elements in the <teiHeader> and point to them using @rendition attributes. It should also be remembered that the CSS specifications are written primarily to guide users providing instructions for the rendering of digital texts, and implementers creating user-agents which will act on these instructions. However, our usage in the context of a TEI document is primarily ''descriptive'' rather than ''prescriptive''; we are typically describing the features of a text we are encoding, rather than providing instructions for rendering it. Our purpose below is not to enumerate an exhaustive set of strategies for encoding any writing mode feature you may encounter; rather we will show some simple examples which serve as an introduction to the topic.

===Text directionality===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="unicode-bidi: embed; direction: rtl">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property is straightforward, but the <code>unicode-bidi</code> property requires some explanation. These three segments are all inline; they form part of a single sentence, although they happen to be encoded on separate lines in this example. The default value for <code>unicode-bidi</code> is "normal", and the CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm." In other words, if we want to make it clear that the <code>direction</code> property is effective here, we must include a value for <code>unicode-bidi</code> which will make it so.

However, as mentioned above, all of the directional encoding in this example is superfluous; ambiguity does not arise in this particular case. Moreover, "ltr" is the default value for the <code>direction</code> property, so we do not need to specify it for the English segments. However, consider the following example, contributed by Efraim Feinstein, in which Hebrew and English text are mixed. (This example is presented in the form of graphics, because we cannot rely on user agents that may be rendering or displaying these Guidelines to provide a consistent output.)

[[File:En he embedding.png|800px]]

Here, an English period appears in between two runs of Hebrew text. Should that period be interpreted as part of a single run of right-to-left text, or should it be deemed to terminate the first run and precede the second? For the Unicode Bidi Algorithm, punctuation is not strongly directional; it inherits directionality from the surrounding characters. Without further clues, therefore, it would interpret the example as a sequence of three runs (English, Hebrew, English), and arrive at an incorrect interpretation. A clear and correct interpretation requires that not only that the glyphs themselves be transcribed in the correct logical order, but that the encoding eliminate potential ambiguity by delimiting the two Hebrew runs separately, like this:

<syntaxhighlight lang="xml">
<p>
Here's a sentence that begins in English
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ויש מלים בעברית והפסק</seg>.
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ועוד מלים בעברית</seg>
and it continues in English.
</p>
</syntaxhighlight>

Here the English is unmarked for directionality, but the period is clearly not included in either of the RTL runs, so the ambiguity inherent in the plain text is avoided. Once again, we might argue that the <code>@xml:lang</code> attribute should provide enough information; the important component here is the explicit delimitation of two distinct RTL runs. But additional clarity in the encoding certainly does no harm.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

So far, we have looked only at left-to-right and right-to-left text running horizontally, using the <code>direction: ltr|rtl</code> property. However, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusal examples running bottom-to-top, as we shall see below). Handling vertical directionality requires the use of another CSS property, the writing mode:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property include two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence may be arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). This example shows a Japanese haiku poem transcribed first in Japanese, then in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl"
xml:id="furu-ike-ya_jp" corresp="#furu-ike-ya_romaji #furu-ike-ya_en">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb"
xml:id="furu-ike-ya_romaji" corresp="#furu-ike-ya_jp #furu-ike-ya_en">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en"
xml:id="furu-ike-ya_en" corresp="#furu-ike-ya_jp #furu-ike-ya_romaji">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-03-27T17:32:00Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the conventions governing the disposition of those glyphs on the writing surface. For the majority of modern languages, writing is presented as a series of lines which are to be read from top to bottom. Within each line, individual characters are most frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). However, writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language always uses the same ''writing mode'' (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different languages are combined, it is probable that different writing modes will be needed: for example, in Hebrew text, running right to left, sequences of Latin digits still run left to right. When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to the vertical mode glyph, U+FE11, to ensure that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example English embedded within vertically organized Chinese text. Similarly, the default writing mode may vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this]).

Consider the case of an English text containing a few Arabic words :

<code>The Arabic term قلم رصاص means "pencil".</code>

A correct TEI encoding might read as follows:

<syntaxhighlight lang="xml">
<s xml:lang="en" >The Arabic term
<term xml:lang="ar" >قلم رصاص</term>
means "pencil".</s>
</syntaxhighlight>

We might assume that it is the presence of the xml:lang attribute with value "ar" that causes processing software to display the Arabic from right to left, but in fact, this is not the case. Even if the markup were not present:

<syntaxhighlight lang="xml">
<s>The Arabic term قلم رصاص means "pencil".</s>
</syntaxhighlight>

the order in which the Arabic characters appear will be the same. This is because Arabic glyphs are to be read left to right, even if they appear within a left-to-right English sentence. Like most other codepoints in the Unicode standard, they have a specific directionality setting which helps any rendering software determine how they should be ordered. The Latin glyph "a" has a bidirectionality setting of strong left-to-right, as do the digits 0 to 9; the Hebrew א (alef) is strongly right-to-left. Of course, some glyphs (common punctuation marks, for example) have weak or neutral settings because they may appear in several contexts. The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) defines a number of rules enabling software to render these bidirectional texts with predictable and reliable results, using only the bidirectionality class values of their glyphs.

In some mixed-mode texts, though, the Bidirectional Algorithm may not give the desired results. To deal with this, Unicode provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes), also called "bidi formatting code characters", which are additional codepoints whose only function is to signal to a user-agent that a specific directionality setting should be turned on or off. These can be inserted into a text to influence the outcome of the bidirectional algorithm. However, in the case of documents encoded in XML, the W3C explicitly advises that markup rather than directional formatting characters should be used ("In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available," http://www.w3.org/International/questions/qa-bidi-controls). We concur with this recommendation, and the remainder of this section and the next provide a set of encoding strategies for handling text directionality without the use of directional formatting characters. The approach we recommend is based on two external specifications, in line with our normal practice of incorporating existing standards where they are available and appropriate. Those specifications are the CSS Writing Modes module (http://dev.w3.org/csswg/css-writing-modes/) and the CSS Transforms module (http://www.w3.org/TR/css3-transforms/). Since (at the time of writing) neither of these modules has yet reached the stage of a Recommendation, the advice offered below should be regarded as provisional, and you should check your usage of the properties concerned against the current version of each specification where possible.

The following sections will present a few simple examples of phenomena relating to text directionality and transformation, along with some suggested encoding strategies based on the following CSS properties from CSS Writing Modes:

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

along with the <code>transform</code> property from CSS Transforms.

In the following examples, CSS rules are encoded in the global TEI @style attribute, which applies them directly to the element on which they are specified (and in most cases, its descendants). It is also appropriate, and will often be more efficient, to express the rules in TEI <rendition> elements in the <teiHeader> and point to them using @rendition attributes. It should also be remembered that the CSS specifications are written primarily to guide users providing instructions for the rendering of digital texts, and implementers creating user-agents which will act on these instructions. However, our usage in the context of a TEI document is primarily ''descriptive'' rather than ''prescriptive''; we are typically describing the features of a text we are encoding, rather than providing instructions for rendering it. Our purpose below is not to enumerate an exhaustive set of strategies for encoding any writing mode feature you may encounter; rather we will show some simple examples which serve as an introduction to the topic.

===Text directionality===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="unicode-bidi: embed; direction: rtl">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property is straightforward, but the <code>unicode-bidi</code> property requires some explanation. These three segments are all inline; they form part of a single sentence, although they happen to be encoded on separate lines in this example. The default value for <code>unicode-bidi</code> is "normal", and the CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm." In other words, if we want to make it clear that the <code>direction</code> property is effective here, we must include a value for <code>unicode-bidi</code> which will make it so.

However, as mentioned above, all of the directional encoding in this example is superfluous; ambiguity does not arise in this particular case. Moreover, "ltr" is the default value for the <code>direction</code> property, so we do not need to specify it for the English segments. However, consider the following example, contributed by Efraim Feinstein, in which Hebrew and English text are mixed. (This example is presented in the form of graphics, because we cannot rely on user agents that may be rendering or displaying these Guidelines to provide a consistent output.)

[[File:En he embedding.png|800px]]

Here, an English period appears in between two runs of Hebrew text. Should that period be interpreted as part of a single run of right-to-left text, or should it be deemed to terminate the first run and precede the second? For the Unicode Bidi Algorithm, punctuation is not strongly directional; it inherits directionality from the surrounding characters. Without further clues, therefore, it would interpret the example as a sequence of three runs (English, Hebrew, English), and arrive at an incorrect interpretation. A clear and correct interpretation requires that not only that the glyphs themselves be transcribed in the correct logical order, but that the encoding eliminate potential ambiguity by delimiting the two Hebrew runs separately, like this:

<syntaxhighlight lang="xml">
<p>
Here's a sentence that begins in English
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ויש מלים בעברית והפסק</seg>.
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ועוד מלים בעברית</seg>
and it continues in English.
</p>
</syntaxhighlight>

Here the English is unmarked for directionality, but the period is clearly not included in either of the RTL runs, so the ambiguity inherent in the plain text is avoided. Once again, we might argue that the <code>@xml:lang</code> attribute should provide enough information; the important component here is the explicit delimitation of two distinct RTL runs. But additional clarity in the encoding certainly does no harm.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

So far, we have looked only at left-to-right and right-to-left text running horizontally, using the <code>direction: ltr|rtl</code> property. However, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusal examples running bottom-to-top, as we shall see below). Handling vertical directionality requires the use of another CSS property, the writing mode:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property include two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence may be arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). This example shows a Japanese haiku poem transcribed first in Japanese, then in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl"
xml:id="furu-ike-ya_jp" corresp="#furu-ike-ya_romaji #furu-ike-ya_en">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb"
xml:id="furu-ike-ya_romaji" corresp="#furu-ike-ya_jp #furu-ike-ya_en">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en"
xml:id="furu-ike-ya_en" corresp="#furu-ike-ya_jp #furu-ike-ya_romaji">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-03-27T16:03:58Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the conventions governing the disposition of those glyphs on the writing surface. For the majority of modern languages, writing is presented as a series of lines which are to be read from top to bottom. Within each line, individual characters are most frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). However, writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language always uses the same ''writing mode'' (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to the vertical mode glyph, U+FE11, to ensure that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example English embedded within vertically organized Chinese text. Similarly, the default writing mode may vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, just as it may vary in response to the size and shape of the carrier in the case of a monumental inscription.

For many, perhaps most, TEI documents there may be no need to encode the writing mode explicitly, even in so-called "mixed mode" texts containing passages written in languages which use different writing modes. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; while Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. In a TEI document, language and script are explicitly stated in the markup using the attribute xml:lang (reference); this indication will imply a particular default writing mode. Even where this attribute is not used, passages in different scripts will use different Unicode characters, and will thus imply a particular default writing mode. Nevertheless, the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this]).

Consider the case of an English text containing a few Arabic words--what is termed a "bidirectional" text:

<code>The Arabic term قلم رصاص means "pencil".</code>

Since Arabic is always written from right to left, we can assume that the Arabic glyphs are to be read in that direction, even if they are in the context of a left-to-right English sentence. In fact, most codepoints in the Unicode standard have a specific directionality setting which helps any rendering engine to determine how they should be ordered. The Latin glyph "a" has a bidirectionality setting of strong left-to-right; the Hebrew א (alef) is strongly right-to-left. Other glyphs have weak or neutral settings because of the contexts in which they may appear. The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) provides a complex series of rules enabling user agents to render most mixed-mode texts with predictable and reliable results, based on the bidirectionality class values of their glyphs.

In some mixed-mode texts, though, the Bidirectional Algorithm may not give the desired results. To deal with this, Unicode provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes), also called "bidi formatting code characters", which are additional codepoints whose only function is to signal to a user-agent that a specific directionality setting should be turned on or off. These can be inserted into a text to influence the outcome of the bidirectional algorithm. However, in the case of documents encoded in XML, the W3C explicitly advises that markup rather than directional formatting characters should be used ("In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available," http://www.w3.org/International/questions/qa-bidi-controls). We concur with this recommendation, and the remainder of this section and the next provide a set of encoding strategies for handling text directionality without the use of directional formatting characters. The approach we recommend is based on two external specifications, in line with our normal practice of incorporating existing standards where they are available and appropriate. Those specifications are the CSS Writing Modes module (http://dev.w3.org/csswg/css-writing-modes/) and the CSS Transforms module (http://www.w3.org/TR/css3-transforms/). Since (at the time of writing) neither of these modules has yet reached the stage of a Recommendation, the advice offered below should be regarded as provisional, and you should check your usage of the properties concerned against the current version of each specification where possible.

The following sections will present a few simple examples of phenomena relating to text directionality and transformation, along with some suggested encoding strategies based on the following CSS properties from CSS Writing Modes:

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

along with the <code>transform</code> property from CSS Transforms.

In the following examples, CSS rules are encoded in the global TEI @style attribute, which applies them directly to the element on which they are specified (and in most cases, its descendants). It is also appropriate, and will often be more efficient, to express the rules in TEI <rendition> elements in the <teiHeader> and point to them using @rendition attributes. It should also be remembered that the CSS specifications are written primarily to guide users providing instructions for the rendering of digital texts, and implementers creating user-agents which will act on these instructions. However, our usage in the context of a TEI document is primarily ''descriptive'' rather than ''prescriptive''; we are typically describing the features of a text we are encoding, rather than providing instructions for rendering it. Our purpose below is not to enumerate an exhaustive set of strategies for encoding any writing mode feature you may encounter; rather we will show some simple examples which serve as an introduction to the topic.

===Text directionality===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="unicode-bidi: embed; direction: rtl">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property is straightforward, but the <code>unicode-bidi</code> property requires some explanation. These three segments are all inline; they form part of a single sentence, although they happen to be encoded on separate lines in this example. The default value for <code>unicode-bidi</code> is "normal", and the CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm." In other words, if we want to make it clear that the <code>direction</code> property is effective here, we must include a value for <code>unicode-bidi</code> which will make it so.

However, as mentioned above, all of the directional encoding in this example is superfluous; ambiguity does not arise in this particular case. Moreover, "ltr" is the default value for the <code>direction</code> property, so we do not need to specify it for the English segments. However, consider the following example, contributed by Efraim Feinstein, in which Hebrew and English text are mixed. (This example is presented in the form of graphics, because we cannot rely on user agents that may be rendering or displaying these Guidelines to provide a consistent output.)

[[File:En he embedding.png|800px]]

Here, an English period appears in between two runs of Hebrew text. Should that period be interpreted as part of a single run of right-to-left text, or should it be deemed to terminate the first run and precede the second? For the Unicode Bidi Algorithm, punctuation is not strongly directional; it inherits directionality from the surrounding characters. Without further clues, therefore, it would interpret the example as a sequence of three runs (English, Hebrew, English), and arrive at an incorrect interpretation. A clear and correct interpretation requires that not only that the glyphs themselves be transcribed in the correct logical order, but that the encoding eliminate potential ambiguity by delimiting the two Hebrew runs separately, like this:

<syntaxhighlight lang="xml">
<p>
Here's a sentence that begins in English
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ויש מלים בעברית והפסק</seg>.
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ועוד מלים בעברית</seg>
and it continues in English.
</p>
</syntaxhighlight>

Here the English is unmarked for directionality, but the period is clearly not included in either of the RTL runs, so the ambiguity inherent in the plain text is avoided. Once again, we might argue that the <code>@xml:lang</code> attribute should provide enough information; the important component here is the explicit delimitation of two distinct RTL runs. But additional clarity in the encoding certainly does no harm.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

So far, we have looked only at left-to-right and right-to-left text running horizontally, using the <code>direction: ltr|rtl</code> property. However, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusal examples running bottom-to-top, as we shall see below). Handling vertical directionality requires the use of another CSS property, the writing mode:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property include two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence may be arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). This example shows a Japanese haiku poem transcribed first in Japanese, then in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl"
xml:id="furu-ike-ya_jp" corresp="#furu-ike-ya_romaji #furu-ike-ya_en">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb"
xml:id="furu-ike-ya_romaji" corresp="#furu-ike-ya_jp #furu-ike-ya_en">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en"
xml:id="furu-ike-ya_en" corresp="#furu-ike-ya_jp #furu-ike-ya_romaji">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-03-27T15:36:18Z

Lou: /* Writing Modes */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the conventions governing the disposition of those glyphs on the writing surface. For the majority of modern languages, writing is presented as a series of lines which are to be read from top to bottom. Within each line, individual characters are most frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). However, writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language always uses the same ''writing mode'' (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to the vertical mode glyph, U+FE11, to ensure that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example English embedded within vertically organized Chinese text. Similarly, the default writing mode may vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, or by the size and shape of a monument.

The directionality features of scripts, and the consequences arising out of them, are generally referred to as "writing modes". For many documents encoded in TEI, there may be no need to encode any information relating to writing mode, because it will be obvious. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. It may appear that directionality can be reliably deduced from the language and script settings, and these are probably already encoded using the @xml:lang attribute in TEI documents (although the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this]). Even in the case of many "mixed mode" documents (documents in which languages or scripts with different writing modes are mixed together), it may not be necessary to be explicit about directionality. Consider the case of an English text containing a few Arabic words--what is termed a "bidirectional" text:

<code>The Arabic term قلم رصاص means "pencil".</code>

Since Arabic is always written from right to left, we can assume that the Arabic glyphs are to be read in that direction, even if they are in the context of a left-to-right English sentence. In fact, most codepoints in the Unicode standard have a specific directionality setting which helps any rendering engine to determine how they should be ordered. The Latin glyph "a" has a bidirectionality setting of strong left-to-right; the Hebrew א (alef) is strongly right-to-left. Other glyphs have weak or neutral settings because of the contexts in which they may appear. The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) provides a complex series of rules enabling user agents to render most mixed-mode texts with predictable and reliable results, based on the bidirectionality class values of their glyphs.

In some mixed-mode texts, though, the Bidirectional Algorithm may not give the desired results. To deal with this, Unicode provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes), also called "bidi formatting code characters", which are additional codepoints whose only function is to signal to a user-agent that a specific directionality setting should be turned on or off. These can be inserted into a text to influence the outcome of the bidirectional algorithm. However, in the case of documents encoded in XML, the W3C explicitly advises that markup rather than directional formatting characters should be used ("In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available," http://www.w3.org/International/questions/qa-bidi-controls). We concur with this recommendation, and the remainder of this section and the next provide a set of encoding strategies for handling text directionality without the use of directional formatting characters. The approach we recommend is based on two external specifications, in line with our normal practice of incorporating existing standards where they are available and appropriate. Those specifications are the CSS Writing Modes module (http://dev.w3.org/csswg/css-writing-modes/) and the CSS Transforms module (http://www.w3.org/TR/css3-transforms/). Since (at the time of writing) neither of these modules has yet reached the stage of a Recommendation, the advice offered below should be regarded as provisional, and you should check your usage of the properties concerned against the current version of each specification where possible.

The following sections will present a few simple examples of phenomena relating to text directionality and transformation, along with some suggested encoding strategies based on the following CSS properties from CSS Writing Modes:

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

along with the <code>transform</code> property from CSS Transforms.

In the following examples, CSS rules are encoded in the global TEI @style attribute, which applies them directly to the element on which they are specified (and in most cases, its descendants). It is also appropriate, and will often be more efficient, to express the rules in TEI <rendition> elements in the <teiHeader> and point to them using @rendition attributes. It should also be remembered that the CSS specifications are written primarily to guide users providing instructions for the rendering of digital texts, and implementers creating user-agents which will act on these instructions. However, our usage in the context of a TEI document is primarily ''descriptive'' rather than ''prescriptive''; we are typically describing the features of a text we are encoding, rather than providing instructions for rendering it. Our purpose below is not to enumerate an exhaustive set of strategies for encoding any writing mode feature you may encounter; rather we will show some simple examples which serve as an introduction to the topic.

===Text directionality===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="unicode-bidi: embed; direction: rtl">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property is straightforward, but the <code>unicode-bidi</code> property requires some explanation. These three segments are all inline; they form part of a single sentence, although they happen to be encoded on separate lines in this example. The default value for <code>unicode-bidi</code> is "normal", and the CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm." In other words, if we want to make it clear that the <code>direction</code> property is effective here, we must include a value for <code>unicode-bidi</code> which will make it so.

However, as mentioned above, all of the directional encoding in this example is superfluous; ambiguity does not arise in this particular case. Moreover, "ltr" is the default value for the <code>direction</code> property, so we do not need to specify it for the English segments. However, consider the following example, contributed by Efraim Feinstein, in which Hebrew and English text are mixed. (This example is presented in the form of graphics, because we cannot rely on user agents that may be rendering or displaying these Guidelines to provide a consistent output.)

[[File:En he embedding.png|800px]]

Here, an English period appears in between two runs of Hebrew text. Should that period be interpreted as part of a single run of right-to-left text, or should it be deemed to terminate the first run and precede the second? For the Unicode Bidi Algorithm, punctuation is not strongly directional; it inherits directionality from the surrounding characters. Without further clues, therefore, it would interpret the example as a sequence of three runs (English, Hebrew, English), and arrive at an incorrect interpretation. A clear and correct interpretation requires that not only that the glyphs themselves be transcribed in the correct logical order, but that the encoding eliminate potential ambiguity by delimiting the two Hebrew runs separately, like this:

<syntaxhighlight lang="xml">
<p>
Here's a sentence that begins in English
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ויש מלים בעברית והפסק</seg>.
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ועוד מלים בעברית</seg>
and it continues in English.
</p>
</syntaxhighlight>

Here the English is unmarked for directionality, but the period is clearly not included in either of the RTL runs, so the ambiguity inherent in the plain text is avoided. Once again, we might argue that the <code>@xml:lang</code> attribute should provide enough information; the important component here is the explicit delimitation of two distinct RTL runs. But additional clarity in the encoding certainly does no harm.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

So far, we have looked only at left-to-right and right-to-left text running horizontally, using the <code>direction: ltr|rtl</code> property. However, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusal examples running bottom-to-top, as we shall see below). Handling vertical directionality requires the use of another CSS property, the writing mode:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property include two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence may be arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). This example shows a Japanese haiku poem transcribed first in Japanese, then in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl"
xml:id="furu-ike-ya_jp" corresp="#furu-ike-ya_romaji #furu-ike-ya_en">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb"
xml:id="furu-ike-ya_romaji" corresp="#furu-ike-ya_jp #furu-ike-ya_en">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en"
xml:id="furu-ike-ya_en" corresp="#furu-ike-ya_jp #furu-ike-ya_romaji">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-03-27T15:35:52Z

Lou: /* Introduction */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Writing Modes===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the conventions governing the disposition of those glyphs on the writing surface. For the majority of modern languages, writing is presented as a series of lines which are to be read from top to bottom. Within each line, individual characters are most frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). However, writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language always uses the same ' writing mode'' (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the same language may appear in different modes, for example either vertically or horizontally. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

When different writing modes are available for the same language, it may be that different glyphs will be preferred when the script is used in different modes. For example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used in preference to the vertical mode glyph, U+FE11, to ensure that the comma appears in the correct position relative to the surrounding glyphs. Even for scripts which are usually written in exactly the same way, different writing modes may be encountered in particular contexts, for example English embedded within vertically organized Chinese text. Similarly, the default writing mode may vary in response to layout constraints such as those imposed by a complex table, where column or row labels may be written vertically or diagonally to make the most effective use of available space, or by the size and shape of a monument.

The directionality features of scripts, and the consequences arising out of them, are generally referred to as "writing modes". For many documents encoded in TEI, there may be no need to encode any information relating to writing mode, because it will be obvious. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. It may appear that directionality can be reliably deduced from the language and script settings, and these are probably already encoded using the @xml:lang attribute in TEI documents (although the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this]). Even in the case of many "mixed mode" documents (documents in which languages or scripts with different writing modes are mixed together), it may not be necessary to be explicit about directionality. Consider the case of an English text containing a few Arabic words--what is termed a "bidirectional" text:

<code>The Arabic term قلم رصاص means "pencil".</code>

Since Arabic is always written from right to left, we can assume that the Arabic glyphs are to be read in that direction, even if they are in the context of a left-to-right English sentence. In fact, most codepoints in the Unicode standard have a specific directionality setting which helps any rendering engine to determine how they should be ordered. The Latin glyph "a" has a bidirectionality setting of strong left-to-right; the Hebrew א (alef) is strongly right-to-left. Other glyphs have weak or neutral settings because of the contexts in which they may appear. The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) provides a complex series of rules enabling user agents to render most mixed-mode texts with predictable and reliable results, based on the bidirectionality class values of their glyphs.

In some mixed-mode texts, though, the Bidirectional Algorithm may not give the desired results. To deal with this, Unicode provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes), also called "bidi formatting code characters", which are additional codepoints whose only function is to signal to a user-agent that a specific directionality setting should be turned on or off. These can be inserted into a text to influence the outcome of the bidirectional algorithm. However, in the case of documents encoded in XML, the W3C explicitly advises that markup rather than directional formatting characters should be used ("In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available," http://www.w3.org/International/questions/qa-bidi-controls). We concur with this recommendation, and the remainder of this section and the next provide a set of encoding strategies for handling text directionality without the use of directional formatting characters. The approach we recommend is based on two external specifications, in line with our normal practice of incorporating existing standards where they are available and appropriate. Those specifications are the CSS Writing Modes module (http://dev.w3.org/csswg/css-writing-modes/) and the CSS Transforms module (http://www.w3.org/TR/css3-transforms/). Since (at the time of writing) neither of these modules has yet reached the stage of a Recommendation, the advice offered below should be regarded as provisional, and you should check your usage of the properties concerned against the current version of each specification where possible.

The following sections will present a few simple examples of phenomena relating to text directionality and transformation, along with some suggested encoding strategies based on the following CSS properties from CSS Writing Modes:

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

along with the <code>transform</code> property from CSS Transforms.

In the following examples, CSS rules are encoded in the global TEI @style attribute, which applies them directly to the element on which they are specified (and in most cases, its descendants). It is also appropriate, and will often be more efficient, to express the rules in TEI <rendition> elements in the <teiHeader> and point to them using @rendition attributes. It should also be remembered that the CSS specifications are written primarily to guide users providing instructions for the rendering of digital texts, and implementers creating user-agents which will act on these instructions. However, our usage in the context of a TEI document is primarily ''descriptive'' rather than ''prescriptive''; we are typically describing the features of a text we are encoding, rather than providing instructions for rendering it. Our purpose below is not to enumerate an exhaustive set of strategies for encoding any writing mode feature you may encounter; rather we will show some simple examples which serve as an introduction to the topic.

===Text directionality===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="unicode-bidi: embed; direction: rtl">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property is straightforward, but the <code>unicode-bidi</code> property requires some explanation. These three segments are all inline; they form part of a single sentence, although they happen to be encoded on separate lines in this example. The default value for <code>unicode-bidi</code> is "normal", and the CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm." In other words, if we want to make it clear that the <code>direction</code> property is effective here, we must include a value for <code>unicode-bidi</code> which will make it so.

However, as mentioned above, all of the directional encoding in this example is superfluous; ambiguity does not arise in this particular case. Moreover, "ltr" is the default value for the <code>direction</code> property, so we do not need to specify it for the English segments. However, consider the following example, contributed by Efraim Feinstein, in which Hebrew and English text are mixed. (This example is presented in the form of graphics, because we cannot rely on user agents that may be rendering or displaying these Guidelines to provide a consistent output.)

[[File:En he embedding.png|800px]]

Here, an English period appears in between two runs of Hebrew text. Should that period be interpreted as part of a single run of right-to-left text, or should it be deemed to terminate the first run and precede the second? For the Unicode Bidi Algorithm, punctuation is not strongly directional; it inherits directionality from the surrounding characters. Without further clues, therefore, it would interpret the example as a sequence of three runs (English, Hebrew, English), and arrive at an incorrect interpretation. A clear and correct interpretation requires that not only that the glyphs themselves be transcribed in the correct logical order, but that the encoding eliminate potential ambiguity by delimiting the two Hebrew runs separately, like this:

<syntaxhighlight lang="xml">
<p>
Here's a sentence that begins in English
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ויש מלים בעברית והפסק</seg>.
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ועוד מלים בעברית</seg>
and it continues in English.
</p>
</syntaxhighlight>

Here the English is unmarked for directionality, but the period is clearly not included in either of the RTL runs, so the ambiguity inherent in the plain text is avoided. Once again, we might argue that the <code>@xml:lang</code> attribute should provide enough information; the important component here is the explicit delimitation of two distinct RTL runs. But additional clarity in the encoding certainly does no harm.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

So far, we have looked only at left-to-right and right-to-left text running horizontally, using the <code>direction: ltr|rtl</code> property. However, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusal examples running bottom-to-top, as we shall see below). Handling vertical directionality requires the use of another CSS property, the writing mode:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property include two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence may be arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). This example shows a Japanese haiku poem transcribed first in Japanese, then in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl"
xml:id="furu-ike-ya_jp" corresp="#furu-ike-ya_romaji #furu-ike-ya_en">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb"
xml:id="furu-ike-ya_romaji" corresp="#furu-ike-ya_jp #furu-ike-ya_en">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en"
xml:id="furu-ike-ya_en" corresp="#furu-ike-ya_jp #furu-ike-ya_romaji">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft

2014-03-27T14:20:08Z

Lou: /* Introduction */

This is a preliminary draft of proposed sections for the TEI Guidelines, created by the [[Text Directionality Workgroup]]. Please see the associated [[Text Directionality Draft Questions]] document for some issues to think about before and after reading this draft, and feel free to respond there and to add new questions. There is also a [[Talk:Text_Directionality_Draft|talk page]] for more informal discussion.

==Text directionality and transformation==

===Introduction===

The scripts used for writing human languages vary not only in the glyphs they use, but also in the conventions governing the disposition of those glyphs on the writing surface. For the majority of modern languages, writing is presented as a series of lines which are to be read from top to bottom. Within each line, individual characters are most frequently presented from left to right (English, Russian, Greek), but there are also several widely-used scripts which run right-to-left (Arabic, Hebrew). However, writing in which the lines of glyphs are presented vertically and read from right to left is also often encountered, notably in older East Asian scripts (Sinitic characters, Japanese Kana, Korean Hangul, Vietnamese chữ nôm). In many cases, a language always uses the same writing mode (that is, the orientation of individual glyphs within a line and reading order of the lines), but there are exceptions, such as Japanese or modern Chinese, in which the language may appear indifferently in different modes. There are also comparatively rare cases of ancient scripts which are characteristically written with lines running left to right, each line being read top to bottom (Ancient Uighur, classical Mongolian and Manchu), or even (in the case of Ogham) from bottom to top.

There are also instances of writing which changes direction on alternate lines (boustrophedon, discussed in detail below).

When a language or script can be arranged in two or more different directions, there are often other consequences arising out of the choice; for example, when Japanese is written horizontally, the Unicode character U+3001, the "ideographic comma", is used, whereas in vertical writing an alternative glyph, U+FE11, may be used to ensure that the comma appears in the correct position relative to the surrounding glyphs. In addition, scripts which normally have a single directionality (such as English) may be written in a different direction in the context of another language (English words inserted into vertical Chinese text, for example), or in response to layout constraints such as those imposed by a complex table, in which column or row labels may be written vertically to make the most effective use of available space.

The directionality features of scripts, and the consequences arising out of them, are generally referred to as "writing modes". For many documents encoded in TEI, there may be no need to encode any information relating to writing mode, because it will be obvious. Modern printed texts in most European languages, for instance, may be expected to use left-to-right/top-to-bottom directionality; Arabic or Hebrew texts are expected to run right-to-left/top-to-bottom. It may appear that directionality can be reliably deduced from the language and script settings, and these are probably already encoded using the @xml:lang attribute in TEI documents (although the W3C i18n Working Group recommends against reliance on language tags for encoding directionality information [per Richard Ishida, W3C; I need to find a formal reference for this]). Even in the case of many "mixed mode" documents (documents in which languages or scripts with different writing modes are mixed together), it may not be necessary to be explicit about directionality. Consider the case of an English text containing a few Arabic words--what is termed a "bidirectional" text:

<code>The Arabic term قلم رصاص means "pencil".</code>

Since Arabic is always written from right to left, we can assume that the Arabic glyphs are to be read in that direction, even if they are in the context of a left-to-right English sentence. In fact, most codepoints in the Unicode standard have a specific directionality setting which helps any rendering engine to determine how they should be ordered. The Latin glyph "a" has a bidirectionality setting of strong left-to-right; the Hebrew א (alef) is strongly right-to-left. Other glyphs have weak or neutral settings because of the contexts in which they may appear. The Unicode Bidirectional Algorithm (http://www.unicode.org/reports/tr9/) provides a complex series of rules enabling user agents to render most mixed-mode texts with predictable and reliable results, based on the bidirectionality class values of their glyphs.

In some mixed-mode texts, though, the Bidirectional Algorithm may not give the desired results. To deal with this, Unicode provides a set of "directional formatting characters" (http://www.unicode.org/reports/tr9/#Directional_Formatting_Codes), also called "bidi formatting code characters", which are additional codepoints whose only function is to signal to a user-agent that a specific directionality setting should be turned on or off. These can be inserted into a text to influence the outcome of the bidirectional algorithm. However, in the case of documents encoded in XML, the W3C explicitly advises that markup rather than directional formatting characters should be used ("In (X)HTML and XML do not use the paired Unicode bidi formatting code characters where equivalent markup is available," http://www.w3.org/International/questions/qa-bidi-controls). We concur with this recommendation, and the remainder of this section and the next provide a set of encoding strategies for handling text directionality without the use of directional formatting characters. The approach we recommend is based on two external specifications, in line with our normal practice of incorporating existing standards where they are available and appropriate. Those specifications are the CSS Writing Modes module (http://dev.w3.org/csswg/css-writing-modes/) and the CSS Transforms module (http://www.w3.org/TR/css3-transforms/). Since (at the time of writing) neither of these modules has yet reached the stage of a Recommendation, the advice offered below should be regarded as provisional, and you should check your usage of the properties concerned against the current version of each specification where possible.

The following sections will present a few simple examples of phenomena relating to text directionality and transformation, along with some suggested encoding strategies based on the following CSS properties from CSS Writing Modes:

<code>
direction: ltr | rtl<br/>
writing-mode: horizontal-tb | vertical-rl | vertical-lr<br/>
text-orientation: mixed | upright | sideways-right | sideways-left | sideways | use-glyph-orientation<ref>The value "use-glyph-orientation" may be dropped from the CSS Writing Modes specification.</ref><br/>
unicode-bidi: normal | embed | isolate | bidi-override | isolate-override | plaintext
</code>

along with the <code>transform</code> property from CSS Transforms.

In the following examples, CSS rules are encoded in the global TEI @style attribute, which applies them directly to the element on which they are specified (and in most cases, its descendants). It is also appropriate, and will often be more efficient, to express the rules in TEI <rendition> elements in the <teiHeader> and point to them using @rendition attributes. It should also be remembered that the CSS specifications are written primarily to guide users providing instructions for the rendering of digital texts, and implementers creating user-agents which will act on these instructions. However, our usage in the context of a TEI document is primarily ''descriptive'' rather than ''prescriptive''; we are typically describing the features of a text we are encoding, rather than providing instructions for rendering it. Our purpose below is not to enumerate an exhaustive set of strategies for encoding any writing mode feature you may encounter; rather we will show some simple examples which serve as an introduction to the topic.

===Text directionality===

====Horizontal directionality====

Returning to our previous simple example

<code>The Arabic term قلم رصاص means "pencil".</code>

we could use the <code>direction</code> property to make directionality explicit:

<code>direction: ltr | rtl</code>

<syntaxhighlight lang="xml">
<seg xml:lang="en" style="direction: ltr">The Arabic term </seg>
<seg xml:lang="ar" style="unicode-bidi: embed; direction: rtl">قلم رصاص</seg>
<seg xml:lang="en" style="direction: ltr">means "pencil".</seg>
</syntaxhighlight>

The use of the <code>direction</code> property is straightforward, but the <code>unicode-bidi</code> property requires some explanation. These three segments are all inline; they form part of a single sentence, although they happen to be encoded on separate lines in this example. The default value for <code>unicode-bidi</code> is "normal", and the CSS Writing Modes specification stipulates that the <code>direction</code> property "has no effect on bidi reordering when specified on inline elements whose unicode-bidi property’s value is normal, because the element does not open an additional level of embedding with respect to the bidirectional algorithm." In other words, if we want to make it clear that the <code>direction</code> property is effective here, we must include a value for <code>unicode-bidi</code> which will make it so.

However, as mentioned above, all of the directional encoding in this example is superfluous; ambiguity does not arise in this particular case. Moreover, "ltr" is the default value for the <code>direction</code> property, so we do not need to specify it for the English segments. However, consider the following example, contributed by Efraim Feinstein, in which Hebrew and English text are mixed. (This example is presented in the form of graphics, because we cannot rely on user agents that may be rendering or displaying these Guidelines to provide a consistent output.)

[[File:En he embedding.png|800px]]

Here, an English period appears in between two runs of Hebrew text. Should that period be interpreted as part of a single run of right-to-left text, or should it be deemed to terminate the first run and precede the second? For the Unicode Bidi Algorithm, punctuation is not strongly directional; it inherits directionality from the surrounding characters. Without further clues, therefore, it would interpret the example as a sequence of three runs (English, Hebrew, English), and arrive at an incorrect interpretation. A clear and correct interpretation requires that not only that the glyphs themselves be transcribed in the correct logical order, but that the encoding eliminate potential ambiguity by delimiting the two Hebrew runs separately, like this:

<syntaxhighlight lang="xml">
<p>
Here's a sentence that begins in English
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ויש מלים בעברית והפסק</seg>.
<seg xml:lang="he" style="unicode-bidi: isolate; direction: rtl">ועוד מלים בעברית</seg>
and it continues in English.
</p>
</syntaxhighlight>

Here the English is unmarked for directionality, but the period is clearly not included in either of the RTL runs, so the ambiguity inherent in the plain text is avoided. Once again, we might argue that the <code>@xml:lang</code> attribute should provide enough information; the important component here is the explicit delimitation of two distinct RTL runs. But additional clarity in the encoding certainly does no harm.

[Would it be helpful to have another example presenting ambiguity arising out of the use of a g element at the end of a text run?]

====Vertical writing modes====

So far, we have looked only at left-to-right and right-to-left text running horizontally, using the <code>direction: ltr|rtl</code> property. However, there are many scripts and languages which are written vertically (mostly top-to-bottom, but with a few unusal examples running bottom-to-top, as we shall see below). Handling vertical directionality requires the use of another CSS property, the writing mode:

<code>writing-mode: horizontal-tb | vertical-rl | vertical-lr</code>

The values for this property include two components: "horizontal" or "vertical" specifies the inline writing direction, while the second component specifies the direction in which lines in a block, and blocks in a sequence may be arranged: from top to bottom (as in most European languages, in which lines and paragraphs are arranged from top to bottom on a page), from right to left (as in the case of some East Asian languages such as Japanese, which we will see below), or left-to-right (e.g. Mongolian). This example shows a Japanese haiku poem transcribed first in Japanese, then in Romaji (Japanese in Latin script), and finally in an English translation.

[[File:Basho_furu_ike_ya.png|thumb|left|alt=Basho poem|Taken from p.42 of ''Haiku: Japanese Art and Poetry''. Judith Patt, Michiko Warkentyne (calligraphy) and Barry Till. 2010. Used with permission.]]

<syntaxhighlight lang="xml">
<div>
<lg xml:lang="ja" style="writing-mode: vertical-rl"
xml:id="furu-ike-ya_jp" corresp="#furu-ike-ya_romaji #furu-ike-ya_en">
<l>古池や</l>
<l>蛙</l>>
<l>飛び込む</l>
<l>水の音</l>
</lg>

<lg xml:lang="ja-Latn" style="writing-mode: horizontal-tb"
xml:id="furu-ike-ya_romaji" corresp="#furu-ike-ya_jp #furu-ike-ya_en">
<l>furu ike ya</l>
<l>kawazu tobikomu</l>
<l>mizu no oto</l>
</lg>

<lg xml:lang="en"
xml:id="furu-ike-ya_en" corresp="#furu-ike-ya_jp #furu-ike-ya_romaji">
<l>Old pond,</l>
<l>and a frog dives in—</l>
<l>"Splash"!</l>
</lg>

<bibl>—Bashō (1644–1694)</bibl>
</div>
</syntaxhighlight>

Note: for the sake of simplicity, the indenting of lines in the vertical Japanese and the central alignment of the other components have been ignored in this encoding, since this section focuses on language and writing mode issues. The Japanese transcription has <code>writing-mode: vertical-rl</code>, which is required because Japanese may be written either in this mode or horizontally. The transcription in Romaji has <code>@xml:lang="ja-Latn"</code> (Japanese written in Latin script) and has a horizontal writing mode; this may seem superfluous, but vertically-written romaji is not unknown.

<div style="clear: both"> </div>

====Vertical text with embedded horizontal text====

When Japanese is written vertically, the glyph orientation remains the same as when it is written horizontally. In other words, glyphs are not rotated (although as noted above some different glyphs may be used for some characters the two orientations; punctuation for instance needs to be positioned differently in vertical versus horizontal text). However, it is very common for languages written vertically to have embedded runs of text from languages normally written horizontally. This raises the issue of the orientation of the glyphs from the horizontal language. Are they written upright, as they would normally appear in horizontal text runs, or are they rotated? Consider this fragment from a Japanese article about the Indonesian language, which takes the form of a glossary list:

[[File:Ja vertical indonesian frag sm.jpg|thumb|left|alt=Glossary list|Taken from p.62 of "インドネシア語". 崎山理. 1985. ''外国語との対照II''. 講座日本語学 11.]]

This might be transcribed as follows:

<syntaxhighlight lang="xml">
<list type="gloss" xml:lang="ja"
style="writing-mode: vertical-rl; text-orientation: mixed">

<label xml:lang="id">hampir</label> 　
<item>「近い、ほとんど」</item>

<label xml:lang="id">baru</label>
<item>「新しい、ばかい」</item>


</list>
</syntaxhighlight>

The rule <code>text-orientation: mixed</code> gives the expected orientation: "In vertical writing modes, characters from horizontal-only scripts are set sideways, i.e. 90° clockwise from their standard orientation in horizontal text. Characters from vertical scripts are set with their intrinsic orientation" ([http://www.w3.org/TR/2013/WD-css-writing-modes-3-20131024/#text-orientation CSS Writing Modes]). In actual fact, the default value for <code>text-orientation</code> is "mixed", so this rule is not strictly required, but if the Indonesian glyphs (which are roman characters) had been set vertically, like this:

<div style="clear: both"> </div>

[[File:Ja vertical indonesian frag rotated sm.jpg|50px|thumb|left|alt=Glossary list|Fragment of previous image with Indonesian glyphs upright.]]

then the encoding would have to be explicit, and we could capture the orientation with <code>text-orientation: upright</code>.

<div style="clear: both"> </div>

====Vertical orientation in horizontal scripts====

It is not unusual to see text from horizontal languages written vertically even where it is not embedded in a text run from a vertically-written script. This example is a fragment from a table of information about agricultural development on Vancouver Island, written in 1855:

[[File:bcgenesis co 305 06 00131v table extract.jpg|thumb|center|600px|alt=Agricultural report table|Enclosure with 10048, CO 305/6, p. 109 http://bcgenesis.uvic.ca/getDoc.htm?id=V55116.scx]]

Four subheading cells in this fragment contain English text, written vertically, bottom-to-top, to conserve space on the page. This is not a "native orientation" for English; readers would not find it easy to read this text, and might be inclined to rotate the page in order to read it in a more natural way. To describe this sort of phenomenon, we can use the text-orientation property again:

<code>text-orientation: mixed|upright|sideways-right|sideways-left|sideways|use-glyph-orientation</code>

For full details on this property, we refer the reader to the CSS Writing Modes specification. For the present example, we will make use only of the "sideways-left" value, which "causes text to be set as if in a horizontal layout, but rotated 90° counter-clockwise." We might encode one of the four cells containing vertical text like this:

<syntaxhighlight lang="xml">
<cell style="writing-mode: vertical-lr; text-orientation: sideways-left">
Cash Value<lb/>
of<lb/>
Farms
</cell>
</syntaxhighlight>

The <code>writing-mode</code> captures the fact that the script is written vertically, and its line/block flow is from left to right (so "of" is to the right of "Cash value"), while the <code>text-orientation</code> value encodes the orientation (rotated 90° counter-clockwise). We might also add <code>text-align: center</code> to the style, to express the fact that the text is centrally-aligned; alignment properties are mapped relative to the line flow, so the word "of" is visibly centred relative to the physical top and bottom of the box, which are the left and right from the point of view of the line flow.

====Bottom-to-top writing====

There are a very small number of scripts which appear to be written bottom-to-top; perhaps the most well-known is Ogham, an alphabet used mainly to write Archaic Irish. The CSS Writing Modes specification does not explicitly provide for the distinction between top-to-bottom and bottom-to-top in vertically-written scripts; it is argued that all instances of bottom-to-top scripts are actually left-to-right horizontal scripts, oriented vertically because of the constraints of the medium on which they are inscribed (as in the case of Ogham inscriptions on tombstones). In other words, the case of scripts like this is analogous to the vertical English text-runs in the table cells in the example above, and can be handled in exactly the same manner (<code>writing-mode: vertical-lr; text-orientation: sideways-left</code>).

====Summary====

In this section, we have presented one approach to encoding text directionality features in TEI files, using the properties and values from the CSS Writing Modes module, encoded in the global TEI @style attribute (or in the TEI <code><rendition></code> element and linked with the @rendition attribute). For most texts, it will not be necessary to encode any information about text directionality, either because it follows unambiguously from <code>@xml:lang</code> values, or because it can be expected to be handled unequivocally by the Unicode Bidi Algorithm. Where it is important to encode text directionality, we believe that most phenomena can be well described through the use of the CSS Writing Modes features; of those which cannot, other approaches based on the CSS Transforms module are presented below.

===Text transformation===

====Rotation====

In what follows, we examine a range of textual phenomena which in some ways appear very similar to those examined above, and even overlap with them. We can categorize these as text transformation features, and suggest some strategies for encoding them based on the properties detailed in the [http://www.w3.org/TR/css3-transforms/ CSS Transforms] specification. The CSS Transforms module provides a complex array of properties, values and functions which can be used to rotate, skew, translate and otherwise transform textual and graphical objects. We can borrow this vocabulary in order to describe textual phenomena in a precise manner.

We begin with a simple example of a rotational transform:

[[File:Rotation_on_z_axis.png|frame‎]]

Here a block of text has been rotated around its z-axis. This is clearly not a "writing mode"; the writing mode for this text is horizontal, left to right. Furthermore, even if we wished to treat this as a writing mode, we could not do so, because there is no way to use writing modes properties to describe an text orientation which is angled at 45 degrees; no human languages are consistently written in this orientation. It is more appropriate to treat this as a rotational transformation. We can do this using two properties: <code>transform</code> and <code>transform-origin</code>. (Both of these properties have quite complex value sets, and we will not look at all of them here. See the [http://www.w3.org/TR/css3-transforms/ specification] for full details.)

The <code>transform</code> property takes as its value one or more of the transform functions, one of which is the function <code>rotateZ</code>:

<syntaxhighlight lang="xml">

<ab style="transform:rotateZ(-45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

Any rotation must take place clockwise around an axis positioned relative to the element being rotated, and the <code>transform-origin</code> property can be used to specify the pivot point. By default, the value of <code>transform-origin</code> is "50% 50%", the point at the centre of the element, but these values can be changed to reflect rotation around a different origin point. (The TEI [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-zone.html zone element] also bears an attribute @rotate which can specify rotation in degrees around the z-axis, but it is not available for any other element.)

An element may also be rotated about either of its other axes. For example, this shows rotation around the Y (vertical) axis:

[[File:Rotation_on_y_axis.png|frame‎‎]]

<syntaxhighlight lang="xml">

<ab style="transform:rotateY(45deg)">TEI-C.ORG</ab>

</syntaxhighlight>

These are obviously trivial examples, but similar features do appear in historical texts. George Herbert's ''The Temple'' includes two stanzas headed "Easter Wings" which are both normally printed in a rotated form so that they represent a pair of wings:

[[File:Herbert church p35 sm.jpg|thumb|left|300px|Page 35 of Herbert's ''The Temple'', second stanza of Easter Wings (or second poem so named). Used with permission of the Folger Library.]]

This could be encoded thus:

<syntaxhighlight lang="xml">
<lg style="transform:rotateZ(90deg)">
<l>My tender age in ſorrow did beginne:</l>
<l>And ſtill with ſickneſſes and ſhame</l>

</lg>
</syntaxhighlight>

but we might also argue that this is in fact a vertical writing mode, and express it with <code>writing-mode: vertical-rl; text-orientation: sideways-right</code>.

<div style="clear: both;"> </div>

====Boustrophedon====

We may also use rotation as a method of handling a true writing mode which is not covered by the CSS Writing Modes: boustrophedon. This is a writing mode common in inscriptions in Latin, Greek and other languages, in which alternate lines run from left to right and from right to left; its name derives from the path of an ox pulling a plough. Right-to-left lines in boustrophedon have another unexpected feature: their glyphs are reversed, so that these lines appear as "mirror writing". This example shows a transcription of a Greek inscription at Dodona:

[[File:Boustrophedon small J.NW.Epeiros.13.p03.jpg|thumb|left|300px|Drawing of a leaden plaque bearing an inquiry by Hermon from the oracular precinct at Dodona. Image and transcription from http://poinikastas.csad.ox.ac.uk, used with permission.]]

This might be transcribed as follows (ignoring word boundaries for the moment):

<syntaxhighlight lang="xml">
<ab>
ΗΕΡΜΟΝΤΙΝΑ <lb/>
<seg style="rotateY(180deg)">ΚΑΘΕΟΝΠΟΤΘΕΜ</seg> <lb/>
ΕΝΟΣΥΕΝΕΑϜ <lb/>
<seg style="rotateY(180deg)">ΟΙΥΕΝΟΙΤΙΕΚΚ</seg> <lb/>
ΡΕΤΑΙΑΣΟΝΑ <lb/>
<seg style="rotateY(180deg)">ΣΙΜΟΣΟΤΤΑΙΕ</seg> <lb/>
ΑΣΣΑΙ
</ab>
</syntaxhighlight>

The 180-degree rotation around the Y (vertical) axis here gives us exactly the effect of the RTL line in boustrophedon; the order of glyphs is reversed, and so is their individual orientation (in fact, we see them "from the back", as it were). <code><seg></code> elements have been used here because these are clearly not "lines" in the sense of poetic lines; the text is continuous prose, and linebreaks are incidental.

There are obviously some unsatisfactory aspects of this manner of encoding boustrophedon. In the inscription above, some words run across linebreaks, so if we wished to tag both words and the right-to-left phenomena, one hierarchy would have to be privileged over the other. By using a transform function rather than a writing mode property, we are apparently suggesting that boustrophedon is not in fact a writing mode, whereas it clearly is. But the CSS Writing Modes specification does not provide support for boustrophedon, because it is a rather obscure historical phenomenon; using a rotational transform is one practical alternative.

<div style="clear: both;"> </div>

====Caveats====

The effect and behaviour of CSS Transforms properties and values according to the specification are highly dependent on the computed [http://www.w3.org/TR/CSS2/visuren.html Visual formatting model] of an HTML document. TEI currently does not have an explicit processing or formatting model. That is, it is by no means clear whether any given TEI element should be interpreted, for instance, as a block-level or inline-level element; for many elements we may think we can assume block-level (<code><ab></code>, "anonymous block") or inline-level (<code><w></code>, "word") from the semantics, but even this is risky. As long as the properties and values from the CSS Transforms module are used as a convenient, well-specified descriptive language to capture features of a text, without any expectation of using them directly and reliably for rendering, this is not problematic; we are simply borrowing a useful vocabulary from an external source, and benefiting from the clarity of definition provided by the specification. However, if there is any expectation of using this information to render a text in a predictable and accurate way, it will be essential to provide enough styling information throughout the document hierarchy to resolve all ambiguities with regard to size, positioning, block status, etc. before any element undergoes a transform operation.

<references/>

[[Category:Council]]

Text Directionality Draft Questions

2014-03-27T13:25:54Z

Lou: /* Where does this section belong in the Guidelines? */

These are some questions for readers of the [[Text Directionality Draft]] document (members of Council and of the [[Text Directionality Workgroup]]). Feel free to add comments and new questions.

'''Note that comments are also being made on the [[Talk:Text_Directionality_Draft|draft's talk page]].'''

===Is the draft written at the appropriate level of detail?===

There may be way too much or way too little detail here.

At the simplest level, we could say "CSS Writing Modes and CSS Transforms provide properties and values for encoding text directionality and transformation. You may wish to use them in the TEI <code>@style</code> attribute, or in <code><rendition>/@rendition</code>," and stop there. I think that would be unhelpful and unkind, since the CSS specifications are not really human-friendly, and there are some aspects of our suggested usage which is orthogonal to the way the specifications are addressed, since we're using the CSS properties descriptively rather than prescriptively.

On the other hand, you may feel that even more detail is required, with more and better examples. The examples for transforms, for example, are rudimentary and scarcely hint at the actual complexity of the CSS specification.

===Where does this section belong in the Guidelines?===

NOTE: At the Council meeting in Oxford in November, it was decided that this new section should be incorporated into a rewritten Chapter 5 (currently named "Languages and Character Sets"), along with section 10.6.6 from Chapter 10 ("Languages and Writing Systems").

<span style="background-color: #d0d0d0;">Originally, I thought it should be added to the end of the "Languages and Character Sets" front matter section, but I no longer think so; the draft contains examples of TEI encoding which wouldn't make sense to someone who has not yet actually read the body of the Guidelines. Other possible locations would be [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/MS.html#mslangs 10.6.6 Languages and writing systems], or [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/WD.html Chapter 5: Non-standard Characters and Glyphs] (which would obviously have to be retitled). The draft may even not belong in the Guidelines at all; it could be a peripheral document on the TEI website or on the wiki.</span>

Further discussion between me and Martin suggests that in fact 10.6.1 should stay where it is (this is the section of the msDescription chapter that talks about documenting the languages used in a text, irrespective of their transcription) but that it would also be desirable to have a single place where all aspects of the use of languages, characters, scripts, glyphs, writing modes would be encompassed, which might be referred to from several places. The directionality draft material could go into this, but it's not clear where such a unified chapter belongs. The existing chapter [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/WD.html Chapter 5: Non-standard Characters and Glyphs] is separate from the existing introductory chapter
[http://www.tei-c.org/release/doc/tei-p5-doc/en/html/CH.html vi Languages and Character Sets] because the former describes specific elements whereas the latter introduces general principles. It might make better logical sense to revise the latter to include at least some of the new material on directionality. [[User: Lou]]

[[Category:Council]]

User:Lou

2014-03-27T13:15:03Z

Lou:

Lou Burnard has several online identies. The latest is http://about.me/louburnard

User:Lou

2014-03-27T13:10:37Z

Lou:

Lou Burnard

Text Directionality Draft Questions

2014-03-27T13:09:57Z

Lou:

These are some questions for readers of the [[Text Directionality Draft]] document (members of Council and of the [[Text Directionality Workgroup]]). Feel free to add comments and new questions.

'''Note that comments are also being made on the [[Talk:Text_Directionality_Draft|draft's talk page]].'''

===Is the draft written at the appropriate level of detail?===

There may be way too much or way too little detail here.

At the simplest level, we could say "CSS Writing Modes and CSS Transforms provide properties and values for encoding text directionality and transformation. You may wish to use them in the TEI <code>@style</code> attribute, or in <code><rendition>/@rendition</code>," and stop there. I think that would be unhelpful and unkind, since the CSS specifications are not really human-friendly, and there are some aspects of our suggested usage which is orthogonal to the way the specifications are addressed, since we're using the CSS properties descriptively rather than prescriptively.

On the other hand, you may feel that even more detail is required, with more and better examples. The examples for transforms, for example, are rudimentary and scarcely hint at the actual complexity of the CSS specification.

===Where does this section belong in the Guidelines?===

NOTE: At the Council meeting in Oxford in November, it was decided that this new section should be incorporated into a rewritten Chapter 5 (currently named "Languages and Character Sets"), along with section 10.6.6 from Chapter 10 ("Languages and Writing Systems").

<span style="background-color: #d0d0d0;">Originally, I thought it should be added to the end of the "Languages and Character Sets" front matter section, but I no longer think so; the draft contains examples of TEI encoding which wouldn't make sense to someone who has not yet actually read the body of the Guidelines. Other possible locations would be [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/MS.html#mslangs 10.6.6 Languages and writing systems], or [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/WD.html Chapter 5: Non-standard Characters and Glyphs] (which would obviously have to be retitled). The draft may even not belong in the Guidelines at all; it could be a peripheral document on the TEI website or on the wiki.</span>

Further discussion between me and Martin suggests that in fact 10.6.1 should stay where it is (this is the section of the msDescription chapter that talks about documenting the languages used in a text, irrespective of their transcription) but that it would also be desirable to have a single place where all aspects of the use of languages, characters, scripts, glyphs, writing modes would be encompassed. The directionality draft material would go into this, but it's not clear where such a unified chapter belongs. [[User: Lou]]

[[Category:Council]]