Integration of JTEI Schemas and Tools - Revision history

Mholmes: /* Progress */

2015-04-07T18:16:41Z

‎Progress

Mholmes: /* Progress */

2015-03-04T18:36:31Z

‎Progress

Mholmes: /* Progress */

2015-03-04T01:01:19Z

‎Progress

Mholmes: /* Unknowns and caveats */

2015-03-03T17:03:56Z

‎Unknowns and caveats

Mholmes: /* Unknowns and caveats */

2015-03-03T00:13:09Z

‎Unknowns and caveats

Mholmes: /* What needs to be done */

2015-03-03T00:12:43Z

‎What needs to be done

Mholmes: /* Unknowns and caveats */

2015-03-02T21:48:00Z

‎Unknowns and caveats

Mholmes: /* Unknowns and caveats */

2015-03-02T21:44:19Z

‎Unknowns and caveats

Mholmes: /* Initial decisions */

2015-03-02T21:37:29Z

‎Initial decisions

Mholmes: /* What needs to be done */

2015-03-02T21:29:34Z

‎What needs to be done

@@ Line 40: / Line 40: @@
 ** 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).
+** 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 seem to put their linked files directly in Exemplars, but I think a subfolder might be cleaner.
+* 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.
-P5 built OK with this scenario, but there were some problems, for which we've implemented some temporary workarounds:
+* 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.
-===Documentation not building===
+===Outstanding issues===
-In theory, we should be able to cause the documentation to build by adding my desired PDF to the end of this list in Exemplars/Makefile:
+* 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.

@@ Line 44: / Line 44: @@
 * 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 seem to put their linked files directly in Exemplars, but I think a subfolder might be cleaner.
-P5 seems to build OK, and the new template is available in the oxygen-tei framework once the Jenkins test version of the plugin is updated; so far so good. What didn't appear was the documentation built from the ODD file, which should have ended up in the release/doc/tei-p5-exemplars/ folder; I've made a guess at how to make that happen, by adding my desired PDF to the end of this list in Exemplars/Makefile:
+P5 built OK with this scenario, but there were some problems, for which we've implemented some temporary workarounds:
 DOCODDS=tei_tite.doc.pdf tei_lite.doc.pdf tei_jtei.doc.pdf
-We'll see if that works.
+This should not only build the pdf but also the HTML and epub, if I understand correctly. However, if we do that, the PDF build generates an error, so I've undone that for the moment.

@@ Line 37: / Line 37: @@
 ==Progress==
-* 2015-03-03: Added the three core files to the P5 Exemplars folder. These are:
+* 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.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.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)
+** tei_jtei.template (copied from jtei-article-source.xml in the JTEI repo, with schema links removed by perl on the way).
-Now waiting to see what Jenkins makes of these additions.
+* 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 seem to put their linked files directly in Exemplars, but I think a subfolder might be cleaner.

← Older revision		Revision as of 17:03, 3 March 2015
Line 34:		Line 34:
	* I don't know what tests we should be implementing in P5 and in the Stylesheets.		* 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.		* 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: 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)
		+
		+	Now waiting to see what Jenkins makes of these additions.

@@ Line 31: / Line 31: @@
 * 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.

@@ Line 3: / Line 3: @@
 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 ([http://www.tei-c.org/Activities/Council/Meetings/tcm63.xml#JTEI]). 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:
-# 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. I don't yet know what the .tei file is for.
+# 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.
 # 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.
 # 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.

← Older revision		Revision as of 21:48, 2 March 2015
Line 34:		Line 34:
	* I don't know much about how the Oxygen plugin works.		* 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.		* 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.

← Older revision		Revision as of 21:44, 2 March 2015
Line 29:		Line 29:

	==Unknowns and caveats==		==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 what the .tei files are for in the Exemplars folder.
		+	* 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.

← Older revision		Revision as of 21:37, 2 March 2015
Line 23:		Line 23:

	==Initial decisions==		==Initial decisions==
		+
		+	# What's the minimum we can do with the least effort? (Add the schema, template and .tei file to the P5 source, I think).
		+	# 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.)
		+	# What must we, and what ought we, to add in the way of tests to both P5 and the Stylesheets?

	==Unknowns and caveats==		==Unknowns and caveats==