{"id":1344,"date":"2020-02-24T10:58:00","date_gmt":"2020-02-24T15:58:00","guid":{"rendered":"https:\/\/wwp.northeastern.edu\/blog\/?p=1344"},"modified":"2020-03-02T09:56:57","modified_gmt":"2020-03-02T14:56:57","slug":"tei-release-customization","status":"publish","type":"post","link":"https:\/\/wwp.northeastern.edu\/blog\/tei-release-customization\/","title":{"rendered":"The &#8220;TEI_customization&#8221; for writing TEI customizations"},"content":{"rendered":"<p><strong>By Syd Bauman<\/strong><\/p>\n<p><em><span style=\"font-weight: 400;\">This blog post describes the history behind and recent release of the &#8220;tei_customization&#8221; schema available in the oXygen TEI framework.\u00a0<\/span><\/em><\/p>\n<p><span style=\"font-weight: 400;\">As many readers of this blog already know, the Text Encoding Initiative schema is designed to be customized by its users. The customization process enables individual projects or user communities to alter the TEI\u2019s constraints and make them more restrictive, more permissive, or just plain different. While the strategic value of such customization is a subject of ongoing debate within the TEI (see for instance Bauman <\/span><a href=\"https:\/\/www.balisage.net\/Proceedings\/vol7\/html\/Bauman01\/BalisageVol7-Bauman01.html\" target=\"_blank\" rel=\"noopener\"><span style=\"font-weight: 400;\">Interchange vs. Interoperability<\/span><\/a><span style=\"font-weight: 400;\">), customization itself is central to the TEI data model.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">A TEI customization is expressed using a customization specification, or an &#8220;ODD file&#8221; (One Document Does-it-all), which represents all of the design choices being made in the customization: the TEI modules to be included, the specific elements to be included or excluded, changes to allowable attribute values, and so forth. This information is then used as a kind of blueprint from which a TEI schema can be generated, using a tool like the TEI\u2019s <\/span><a href=\"https:\/\/romabeta.tei-c.org\/\" target=\"_blank\" rel=\"noopener\"><span style=\"font-weight: 400;\">Roma<\/span><\/a><span style=\"font-weight: 400;\"> schema generator. The ODD file is actually written in TEI, using a specialized module that contains elements for things like &#8220;include this module&#8221; (<code>&lt;moduleRef&gt;<\/code>) or &#8220;here\u2019s a list of attributes&#8221; (<code>&lt;attList&gt;<\/code>).\u00a0<\/span><\/p>\n<p><span style=\"font-weight: 400;\">In 2006, the Women Writers Project began teaching workshops and seminars on scholarly text encoding, and in 2010, we decided it was time to include a seminar on TEI customization in the series. When we started planning the workshop curriculum, one challenge we flagged right away was the question of how to help participants focus on the main concepts of schema design, rather than the tiny practical pitfalls in the TEI ODD language. In principle, writing an ODD is straightforward, but in practice, there are numerous details that can be tricky to remember and that aren\u2019t directly constrained by the normal TEI schema. We decided to create a customized TEI schema that would provide extra constraints and guidance for people writing TEI schema customizations. If you\u2019re thinking &#8220;that seems like a challengingly recursive process,&#8221; you\u2019re in good company. We have developed a <\/span><span style=\"font-weight: 400;\">slide<\/span><span style=\"font-weight: 400;\"> to show how all the pieces fit together.<\/span><\/p>\n<p><img loading=\"lazy\" decoding=\"async\" class=\"aligncenter size-full wp-image-1345\" src=\"https:\/\/wwp.northeastern.edu\/blog\/wp-content\/uploads\/2020\/02\/odd_stack_complex.png\" alt=\"\" width=\"1049\" height=\"768\" srcset=\"https:\/\/wwp.northeastern.edu\/blog\/wp-content\/uploads\/2020\/02\/odd_stack_complex.png 1049w, https:\/\/wwp.northeastern.edu\/blog\/wp-content\/uploads\/2020\/02\/odd_stack_complex-300x220.png 300w, https:\/\/wwp.northeastern.edu\/blog\/wp-content\/uploads\/2020\/02\/odd_stack_complex-768x562.png 768w, https:\/\/wwp.northeastern.edu\/blog\/wp-content\/uploads\/2020\/02\/odd_stack_complex-1024x750.png 1024w, https:\/\/wwp.northeastern.edu\/blog\/wp-content\/uploads\/2020\/02\/odd_stack_complex-369x270.png 369w\" sizes=\"auto, (max-width: 1049px) 100vw, 1049px\" \/><\/p>\n<p><span style=\"font-weight: 400;\">Thus what this schema does is limit the available constructs to those that make sense in a customization. Some examples:<\/span><\/p>\n<ul>\n<li style=\"list-style-type: none;\">\n<ul>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">The @key attribute of the aforementioned <code>&lt;moduleRef&gt;<\/code> element is limited to one of the formal names of an existing TEI module. This means when you add a <code>&lt;moduleRef&gt;<\/code> to your customization file, you don\u2019t have to go look up whether it is spelled<\/span> &#8220;namesanddates&#8221; or &#8220;namesDates&#8221; or &#8220;names_and_dates&#8221;, you just select &#8220;namesdates&#8221; from the pop-up list your editor provides.<\/li>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">The @ident attribute of the <code>&lt;elementSpec&gt;<\/code> element is limited to one of the 575 or so formal names of existing TEI elements. On the plus side, this means when you add an <code>&lt;elementSpec&gt;<\/code> to your customization file to modify an existing TEI element (e.g., to change its attributes or add an example), you don\u2019t have to remember whether it is spelled &#8220;noteStatement&#8221;, &#8220;notesStatement&#8221;, or &#8220;noteStmt&#8221;, you just select &#8220;notesStmt&#8221; from the pop-up list your editor provides. On the minus side, this means that if you want to add a new <code>&lt;static&gt;<\/code> element (as syntactic sugar for <code>&lt;gap reason=\"illegible\" agent=\"radio_static\"&gt;<\/code>) in your TEI customization, the <code>&lt;elementSpec mode=\"add\"&gt;<\/code> that defines it will be inappropriately flagged as having an invalid @ident.<\/span><\/li>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">Deleting <code>&lt;publicationStmt&gt;<\/code> from your schema is flagged as a warning \u2014 the resulting documents will, by definition, be non-TEI-conformant.<\/span><\/li>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">An <code>&lt;elementSpec&gt;<\/code> that either adds a new element or replaces an existing one is flagged as an error if it does not have a <code>&lt;content&gt;<\/code> element.<\/span><\/li>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">More than one <code>&lt;elementSpec&gt;<\/code> with the same @ident is not allowed \u2014 although the ODD language technically allows this situation, current ODD software chokes on it.<\/span><\/li>\n<li style=\"font-weight: 400;\"><span style=\"font-weight: 400;\"><span style=\"font-weight: 400;\">If, for instance, you inadvertently try to modify the <code>&lt;stage&gt;<\/code> element with<\/span><\/span> <code> &lt;elementSpec ident=\"stage\" module=\"drama\"&gt;<\/code> the error will be flagged. (<code>&lt;stage&gt;<\/code> is not in the drama module, it is in the core module.)<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">The first version of this customization was &#8220;brown_odds&#8221; (in parallel with &#8220;tei_odds&#8221;), and we used it in the first TEI customization seminar we taught in August 2010. It took some time to settle on the name; &#8220;brown_odds&#8221; was rejected when SyncroSoft (the makers of the oXygen XML editor) wanted to include the customization in oXygen\u2019s TEI framework. We briefly tried &#8220;toctoc&#8221; (&#8220;TEI ODD Customization for TEI ODD Customizations&#8221;), followed by &#8220;odd4odds&#8221; (&#8220;ODD for ODDs&#8221;, charming but precious), and finally, the TEI Council named it &#8220;tei_customization&#8221;, which accurately captures the real function and matches the naming pattern used in TEI Exemplars.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">Because details in TEI change, each release of the TEI <\/span><i><span style=\"font-weight: 400;\">Guidelines<\/span><\/i><span style=\"font-weight: 400;\"> gets its own version of &#8220;tei_customization&#8221;; these can be found at the links below:<\/span><\/p>\n<ul>\n<li style=\"font-weight: 400;\"><a href=\"https:\/\/tei-c.org\/Vault\/P5\/current\/xml\/tei\/custom\/schema\/relaxng\/tei_customization.rnc\" target=\"_blank\" rel=\"noopener\"><span style=\"font-weight: 400;\">RELAX NG (compact syntax)<\/span><\/a><\/li>\n<li style=\"font-weight: 400;\"><a href=\"https:\/\/tei-c.org\/Vault\/P5\/current\/xml\/tei\/Exemplars\/tei_customization.isosch\" target=\"_blank\" rel=\"noopener\"><span style=\"font-weight: 400;\">Schematron<\/span><\/a><span style=\"font-weight: 400;\"> (and <\/span><a href=\"https:\/\/tei-c.org\/Vault\/P5\/current\/xml\/tei\/custom\/odd\/tei_customization.xsl\" target=\"_blank\" rel=\"noopener\"><span style=\"font-weight: 400;\">Schematron constraints expressed in XSLT<\/span><\/a><span style=\"font-weight: 400;\">)<\/span><\/li>\n<\/ul>\n<p><span style=\"font-weight: 400;\">The &#8220;tei_customization&#8221; schema is available in the oXygen TEI framework. This means that when you get oXygen from the <\/span><a href=\"https:\/\/www.oxygenxml.com\/download.html\" target=\"_blank\" rel=\"noopener\"><span style=\"font-weight: 400;\">SyncRO Soft<\/span><\/a><span style=\"font-weight: 400;\"> website, &#8220;tei_customization&#8221; (as well as the rest of the TEI Exemplar schemas) is already available. To access it, choose the File &gt; New\u2026 menu item and then choose the &#8220;TEI for writing TEI customizations&#8221; template. (It does not matter whether you choose from the &#8220;TEI P5&#8221; or &#8220;TEI ODD&#8221; section, it\u2019s the same template.) But that is the version that was current when that version of oXygen was released, which may be several versions behind the current TEI. To automatically get updated versions of the TEI oXygen framework, follow the <\/span><a href=\"https:\/\/faqingperplxd.wordpress.com\/2014\/04\/02\/auto-update-your-tei-framework-in-oxygen\/\" target=\"_blank\" rel=\"noopener\"><span style=\"font-weight: 400;\">helpful instructions<\/span><\/a><span style=\"font-weight: 400;\"> prepared by James Cummings.<\/span><\/p>\n<p><b>WARNING<\/b><span style=\"font-weight: 400;\">: When using the tei_customization RELAX NG schema, DTD compatibility mode <\/span><b>must<\/b><span style=\"font-weight: 400;\"> be turned off. In oXygen, this means unchecking the &#8220;Check ID\/IDREF&#8221; box in the &#8220;XML \/ XML Parser \/ RELAX NG&#8221; preferences pane. When using <code>jing<\/code> on the commandline, it means using the <code>-i<\/code> switch. If you do not turn DTD compatibility mode off, you will get several copies of pretty much the same (useless) error message that starts &#8220;conflicting ID-types for attribute \u2026&#8221;.<\/span><\/p>\n<p><span style=\"font-weight: 400;\">To read more about this customization, see &#8220;<\/span><a href=\"https:\/\/journals.openedition.org\/jtei\/2573\" target=\"_blank\" rel=\"noopener\"><span style=\"font-weight: 400;\">A TEI customization for writing TEI customizations<\/span><\/a>&#8221; by Syd Bauman.<b>\u00a0<\/b><\/p>\n","protected":false},"excerpt":{"rendered":"<p>By Syd Bauman This blog post describes the history behind and recent release of the &#8220;tei_customization&#8221; schema available in the oXygen TEI framework.\u00a0 As many readers of this blog already know, the Text Encoding Initiative schema is designed to be customized by its users. The customization process enables individual projects or user communities to alter the TEI\u2019s constraints and make them more restrictive, more permissive, or just plain different. While the strategic value of such customization is a subject of&#8230;<\/p>\n<p class=\"read-more\"><a class=\"btn btn-default\" href=\"https:\/\/wwp.northeastern.edu\/blog\/tei-release-customization\/\"> Read More<span class=\"screen-reader-text\">  Read More<\/span><\/a><\/p>\n","protected":false},"author":14,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[29],"tags":[],"class_list":["post-1344","post","type-post","status-publish","format-standard","hentry","category-encoding-explorations"],"_links":{"self":[{"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/posts\/1344","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/users\/14"}],"replies":[{"embeddable":true,"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/comments?post=1344"}],"version-history":[{"count":11,"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/posts\/1344\/revisions"}],"predecessor-version":[{"id":1350,"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/posts\/1344\/revisions\/1350"}],"wp:attachment":[{"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/media?parent=1344"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/categories?post=1344"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wwp.northeastern.edu\/blog\/wp-json\/wp\/v2\/tags?post=1344"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}