Integration of JTEI Schemas and Tools

What needs to be done

This page lays out the procedure we intend to take to integrate the schema, authoring tools and transformations created by JTEI (see [TEI Journal Encoding Package]) into the main P5 distribution, the TEI Stylesheets, and the Oxygen-TEI plugin. This work is being carried out on the instructions of Council ([1]). The objective is to achieve the following three major steps, if practical before the code freeze preceding the April 2015 release of the TEI Guidelines:

1. Integrate the JTEI article schema currently maintained by Ron Van den Branden and Martin Holmes into the main P5 release. Essentially this means the ODD file, which contains full detailed documentation for the customization. The JTEI schema will appear as one of the standard TEI-supported customizations alongside TEI Lite, TEI Tite etc. This presumably involves adding tei_journal.odd, tei_journal.template, and tei_journal.tei to the Exemplars directory. The .tei file is an example document which is validated against the generated schema; this could be a suitably complex genuine instance document from the journal.
2. Integrate the specialized transformations used by the Journal editors to generate ODT and OpenEdition output files from the article source into the TEI Stylesheets package. This will presumably involve creating a special profile, and may also require that we figure out how to warn users that these transformations are intended only to operate on documents complying with the journal schema.
3. Integrate support for the Journal schema and transformations into the oxygen-tei plugin. Some of this should presumably happen automatically, but other components such as the Author-mode CSS we have developed for semio-wysiwyg editing will need to be added manually.

In addition, we also need to thoroughly document what we do through the production of a TEI Council Working Paper (TCW); there is at present no documentation (to my knowledge) which addresses any of the processes above.

Who needs to be involved

Prime movers:

• Martin Holmes
• Ron Van den Branden

Indispensable advisors:

• Sebastian Rahtz (P5 infrastructure, Stylesheets, Oxygen plugin)
• Someone from Oxygen (Oxygen plugin, Oxygen release process and schedule)
• Other members of Council (final decisions/approval on various stages)

Initial decisions

1. What's the minimum we can do with the least effort? (Add the schema, template and .tei file to the P5 source, I think).
2. How do we best keep the work of the Journal editors moving while different parts of their codebase are migrated into different bits of the TEI infrastructure? (Scripts for Martin and Ron to run which keep anything committed to the TEI repo and the Stylesheets repo in sync with their own working repository, until the entire process is complete.)
3. What must we, and what ought we, to add in the way of tests to both P5 and the Stylesheets?

Unknowns and caveats

• The next Oxygen release is likely to be the end of April/beginning of May. At that point, we must not have any half-completed or non-working bits which involve the Oxygen plugin.
• I don't know much about how the Oxygen plugin works.
• I don't know what tests we should be implementing in P5 and in the Stylesheets.
• The Journal code is also in the process of moving from a free account on a commercial provider to a repository on tei-c.org; that repo will not be public (it's intended mainly for articles and materials in the process of being reviewed and edited), and the intention is to hive off the XML and Stylesheet code from it during the process. However, the Journal editors currently depend on an integrated Oxygen project for their work, so even though everything is being split up, it'll have to be relatively easy to bring it back together on local workstations for their work to continue.

Progress

• 2015-03-03: With help from SR, I added the three core files to the P5 Exemplars folder. These are:
  • tei_jtei.odd (copied from jtei.odd in the JTEI repo).
  • tei_jtei.tei (a new file I created which is a minimal valid file for the schema; this is stored in the JTEI repo too).
  • tei_jtei.template (copied from jtei-article-source.xml in the jTEI repo, with schema links removed by perl on the way).

• I also had to add images linked from the documentation in tei_jtei.odd, which are added relative to the ODD file, as they are referenced, so a new folder called img was created in Exemplars to hold them. Other ODDs were linked to files directly in Exemplars, but a subfolder is cleaner, so I ended up moving all images into a subfolder and changing those links. P5 built OK with this scenario, but there were some problems, which we subsequently overcame.

• 2015-04-06: P5 2.8.0 and the Stylesheets 7.34.0 were released, incorporating our jTEI materials, along with a new "official" copy of the plugin. No bugs reported so far.

Outstanding issues

• There is one aspect of the Exemplars build which caused problems: examples in an ODD are always validated against a schema generated from that ODD. That might normally be fine -- you only want to include examples that are relevant to your own ODD -- but for jTEI it's a problem, because articles will inevitably include examples of TEI code which are outside the constraints or our schema. This required a workaround in the Exemplars build. I intend to document the Exemplars Makefile inline in detail, and then abstract that documentation into some sort of readme.