<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <teiHeader>
    <fileDesc>
      <titleStmt>
        <title type="main">TEI by Example</title>
        <title type="sub">Module 8: Customising TEI, ODD, Roma</title>
        <author xml:id="RvdB">Ron Van den Branden</author>
        <editor xml:id="EV">Edward Vanhoutte</editor>
        <editor xml:id="MT">Melissa Terras</editor>
        <sponsor>Association for Literary and Linguistic Computing (ALLC)</sponsor>
        <sponsor>Centre for Data, Culture and Society, University of Edinburgh, UK</sponsor> 
        <sponsor>Centre for Digital Humanities (CDH), University College London, UK</sponsor>
        <sponsor>Centre for Computing in the Humanities (CCH), King’s College London, UK</sponsor>
        <sponsor>Centre for Scholarly Editing and Document Studies (CTB) , Royal Academy of Dutch Language and Literature, Belgium</sponsor>
        <funder>
          <address>
            <addrLine>Centre for Scholarly Editing and Document Studies (CTB)</addrLine>
            <addrLine>Royal Academy of Dutch Language and Literature</addrLine>
            <addrLine>Koningstraat 18</addrLine>
            <addrLine>9000 Gent</addrLine>
            <addrLine>Belgium</addrLine>
          </address>
          <email>ctb@kantl.be</email>
        </funder>
        <principal>Edward Vanhoutte</principal>
        <principal>Melissa Terras</principal>
      </titleStmt>
      <publicationStmt>
        <publisher>Centre for Scholarly Editing and Document Studies (CTB) , Royal Academy of Dutch Language and Literature, Belgium</publisher>
        <distributor>Centre for Scholarly Editing and Document Studies (CTB) , Royal Academy of Dutch Language and Literature, Belgium</distributor>
        <pubPlace>Gent</pubPlace>
        <address>
          <addrLine>Centre for Scholarly Editing and Document Studies (CTB)</addrLine>
          <addrLine>Royal Academy of Dutch Language and Literature</addrLine>
          <addrLine>Koningstraat 18</addrLine>
          <addrLine>9000 Gent</addrLine>
          <addrLine>Belgium</addrLine>
        </address>
        <availability status="free">
          <p>Licensed under a <ref target="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution ShareAlike 3.0 License</ref>
                    </p>
        </availability>
        <date when="2010-07-09">9 July 2010</date>
      </publicationStmt>
      <seriesStmt>
        <title>TEI By Example.</title>
        <editor>Edward Vanhoutte</editor>
        <editor>Ron Van den Branden</editor>
        <editor>Melissa Terras</editor>
      </seriesStmt>
      <sourceDesc>
        <p>Digitally born</p>
      </sourceDesc>
    </fileDesc>
    <encodingDesc>
      <projectDesc>
        <p>TEI By Example offers a series of freely available online tutorials walking individuals through the different stages in marking up a document in TEI (Text Encoding Initiative). Besides a general introduction to text encoding, step-by-step tutorial modules provide example-based introductions to eight different aspects of electronic text markup for the humanities. Each tutorial module is accompanied with a dedicated examples section, illustrating actual TEI encoding practise with real-life examples. The theory of the tutorial modules can be tested in interactive tests and exercises.</p>
      </projectDesc>
    </encodingDesc>
    <profileDesc>
      <langUsage>
        <language ident="en-GB">en-GB</language>
      </langUsage>
    </profileDesc>
    <revisionDesc>
      <change when="2020-06-15" who="#RvdB">proofing corrections</change>
      <change when="2020-06-11" who="#RvdB">revision</change>
      <change when="2020-04-30" who="#RvdB">updated to Pure ODD + RomaJS</change>
      <change when="2010-07-13" who="#RvdB">
        <list>
          <item>added distinction <gi>gi</gi> — <tag>gi scheme="..."</tag> — <gi>tag</gi>
                    </item>
          <item>final spellcheck</item>
        </list>
      </change>
      <change when="2010-07-09" who="#RvdB">release</change>
      <change when="2008-11-05" who="#RvdB">
        <list>
          <item>updated to TEI P5-1.2.0 + Roma 3.5 (04/11/2008)</item>
          <item>corrected errors + typos</item>
        </list>
      </change>
      <change when="2008-08-21" who="#RvdB">
        <list>
          <item>corrected typos</item>
          <item>elaborated on didactic motivations for some choices in the tutorial</item>
        </list>
      </change>
      <change when="2008-08-19" who="#RvdB">replaced <title level="m">Alice’s Adventures Under Ground</title> example with <title level="m">Alice’s Adventures in Wonderland</title> due to copyright concerns with the images</change>
      <change when="2008-08-01" who="#RvdB">revisions</change>    
      <change when="2008-07-15" who="#RvdB">creation</change>
    </revisionDesc>
  </teiHeader>
  <text xml:id="TBED08v00" type="tutorials">
    <body>
            <head>Module 8: Customising TEI, ODD, Roma</head>
            <div xml:id="intro">
        <head>Introduction</head>
        <p>Throughout its history, TEI has grown into a complex and encompassing system, allowing you to express your view on a text in a very flexible way, ranging from rather general statements on the textual structure to highly specific analyses of all kinds of textual phenomena. Currently (at <ref target="https://tei-c.org/Vault/P5/4.0.0/doc/tei-p5-doc/en/html/">version 4.0.0</ref>), the TEI defines no less than 580 different elements and it is hard to imagine a document that would need them all. On the other hand, it is much easier to imagine a document that would need just <hi>that</hi> element that isn’t present in the current set of elements defined by TEI.</p>
        <p>The TEI community anticipated such concerns and explicitly designed TEI P5 as:
          <list rend="bulleted">
            <item>a highly modular system, allowing users to cherry-pick the parts they need</item>
            <item>an extensible system, allowing users to add new elements and attributes or modify existing ones</item>
          </list>
          Put differently, TEI very much resembles a library of text concepts where you can walk in, stroll through shelves filled with TEI element and attribute definitions, and choose exactly those that suit your document analysis. When you check out at the counter, they will all be collected and put in a nice bag, reading <q>schema for documents of [your name]</q>. What’s more, even if you have brought your own elements and attributes, they will be included in the same schema! You take your receipt, which is a blueprint listing all elements and attributes included in your schema so you can revisit your selection afterwards, walk home and happily start encoding your texts with your very own TEI schema. In the TEI world, this library visit is called <soCalled>TEI customisation</soCalled>. As it is a visit you will have to repeat often in order to fine-tune a tailored schema for your encoding projects, this tutorial will guide you through the most relevant steps for doing so.</p>
        <p>A couple of elements in the above analogy will be the focus of this tutorial, so allow us to elaborate them a bit more: 
          <list rend="bulleted">
            <item>In this tutorial, the general term <term>TEI schema</term> will be used for any formal representation of the elements and attributes you expect in a document. TEI schemas can be expressed as <term>Relax NG</term> schemas, <term>W3C Schema</term>s, or <term>DTD</term>s (don’t worry, you ordered for one of these at check-out). In general, you don’t have to work on these schemas themselves; they are rather meant as auxiliary files for your XML editing / processing software to validate your document(s) and make sure they conform to the rules.</item>
            <item>Even more important than a schema is the <soCalled>receipt</soCalled> for your TEI schema. This will allow you to remember the choices made and facilitate you to share your schemas with others. In the TEI world, such a <soCalled>blueprint</soCalled> is just another TEI document with specific elements, and is called an <term>ODD</term> (One Document Does it all).</item>
            <item>It’s important to know that, as of TEI P5, there is no <soCalled>fixed</soCalled> monolithic one-size-fits-all TEI schema. Instead, you are supposed to create your own before you can start encoding TEI texts. In this sense, customisation is a built-in prerequisite for using TEI. Testimony to this centrality is the fact that TEI maintains a specific tool for easing this customisation process. It is called <soCalled>Roma</soCalled>, and accessible as a user-friendly web form at <ptr target="https://roma.tei-c.org/"/>. Consider it an electronic librarian.</item>
          </list>
          <note>Currently, an update of the Roma tool is in the making. It is available at a separate URL (<ptr target="https://roma.tei-c.org/"/>), until it will replace the current Roma tool. So long, the <soCalled>old</soCalled> Roma page at <ptr target="https://roma.tei-c.org/"/> provides a link to the beta version. As this beta version is meant to replace the current Roma version eventually, we have decided to use it in this tutorial, and to refer to it as <soCalled>Roma</soCalled>.</note>
        </p>
        <p>This tutorial won’t discuss the different TEI schema formats, but instead focus on both the formal ODD vocabulary for expressing TEI customisations, and the process of editing an ODD file with the Roma tool. In doing so, this tutorial will be the odd one out: at the same time slightly more conceptual than the other ones, and more concrete, using and introducing the Roma web tool along the way throughout the examples.</p>
      </div>
            <div xml:id="terminology">
        <head>Some Terminology</head>
        <p>As we have seen in <ptr type="crossref" target="TBED00v00.xml#teimodules"/>, all TEI elements and their attributes are organised thematically in 21 higher-level modules. If we compare the TEI specification to a library, modules are the library shelves holding the elements and attributes. Each of these modules is documented in full in a dedicated chapter of the TEI Guidelines; for an overview of which chapters correspond to which modules, see section <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/ST.html#STMA">1.1 TEI Modules</ref> of the TEI Guidelines. Most TEI modules define attributes and elements. During time, the TEI specification has grown into an ecosystem of hundreds of interrelated elements and attributes. In order to make for easier organisation and maintenance, they have been grouped into <term>classes</term>. Each class is a group of elements and attributes. Therefore, the TEI defines two kinds of classes:
          <list type="gloss">
            <label>Attribute classes</label> 
            <item>A group of attributes that can occur in the same place in a TEI document. The names of attribute classes all start with <code>att.</code>, followed by a name that gives an indication of the group of attributes it contains. For example, the global attributes <att>rend</att>, <att>xml:id</att>, and <att>n</att> (among others) are all defined in the attribute class <ident type="class">att.global</ident>, which name indicates that it defines global attributes, available on all TEI elements.</item>
            <label>Model classes</label> 
            <item>A group of elements that can occur in the same place in a TEI document. The names of model classes all start with <code>model.</code>, followed by a name that gives an indication of the group of elements it contains. For example, <gi>p</gi> and <gi>ab</gi> are being grouped in the model class <ident type="class">model.pLike</ident>, which holds all paragraph-like elements.</item>
          </list>
        </p>
        <p>Classes can refer to other classes, so it becomes possible to develop a fine-grained hierarchy of element and attribute groups that all share some common features, but add their own specific features, depending on the sub-classes they belong to.</p>
        <p>In the organisation of TEI modules, the <ident type="module">tei</ident> module is a bit special, in that it does no more than providing the definitions of the attribute and model classes that are being used in the definitions of elements and attributes in other TEI modules. Besides these classes, the <ident type="module">tei</ident> module defines some other low-level constructs that are being used in the definition of actual elements and attributes: 
          <list type="gloss">
            <label>Macros</label> 
            <item>A kind of <soCalled>shortcut</soCalled>, combining a number of frequently co-occurring model classes into a logical group of elements that can occur in the same hierarchical contexts in a TEI document. The names of macros all start with <code>macro.</code>, followed by a name that gives an indication of the logical organisation of the elements it groups. For example, the macro <ident type="macro">macro.paraContent</ident> groups elements that can occur inside paragraphs and similar elements.</item>
            <label>Datatypes</label> 
            <item>A set of rules for the values of attributes. The names of datatypes all start with <code>teidata.</code>, followed by a name that gives an indication of the datatype. For example, the datatype <ident type="datatype">teidata.count</ident> specifies a rule for attribute values that must be positive integers. When an attribute definition refers to this datatype, its value must be a positive integer.</item>
          </list>
        </p>
        <p>This system of building blocks can then be used to define the core of what the TEI is all about: elements and attributes for marking up information in or about texts. For example: the TEI element <gi>name</gi> defines itself by:
          <list rend="bulleted">
            <item>declaring itself as a member of the <emph>TEI module</emph> <ident type="module">core</ident>. This means that when this module is included in a TEI customisation, the <gi>name</gi> element will be available by default.</item>
            <item>declaring itself as a member of the <emph>attribute classes</emph> <ident type="class">att.global</ident>, <ident type="class">att.personal</ident>, <ident type="class">att.datable</ident>, <ident type="class">att.editLike</ident>, and <ident type="class">att.typed</ident>. This means that <gi>name</gi> will receive the attributes defined in all those classes (at least, those that are included in the TEI customisation).</item>
            <item>declaring itself as a member of the <emph>model class</emph> <ident type="class">model.personPart</ident>. This means that it will be able to occur inside all TEI elements that define the members of this <ident type="class">model.personPart</ident> as its contents.</item>
            <item>declaring its contents as the elements grouped in the <emph>macro</emph> <ident type="macro">macro.phraseSeq</ident>. This means that all elements included in this macro can occur inside <gi>name</gi>.</item>
          </list>
        </p>
        <p>
                    <emph>How</emph> these element and attribute are defined, is explained in this TEI by Example tutorial. It will cover some of the very specific elements that make up the <ident type="module">tagdocs</ident> module that is documented in section <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/TD.html">22: Documentation Elements</ref> of the TEI Guidelines. Yet, instead of a purely theoretical explanation of this rather technical part of the TEI Guidelines, we will illustrate this in a hands-on fashion, building a mini TEI customisation for a small encoding project, with the help of the Roma tool. Let’s dive in!</p>
      </div>
            <div xml:id="customising">
        <head>Customising TEI: Why and How?</head>
        <p>As with all other TBE tutorial modules, we’ll start from a concrete text example. This time, we’ll consider Lewis Carroll’s <title level="m">Alice in Wonderland</title>. Suppose we’re at the start of a project that will encode this text. To get a sense of the structure of the document, here are the first pages: 
          <!-- screenshot settings:
            -window width: 1023px
            -window height: 1022px
            -viewport width: 1015px
            -viewport height: 882px
          -->
          <figure xml:id="figure1">
            <graphic url="../../../images/tutorials/TBED08v00/aliceWL_1866_1.jpg"/>
            <graphic url="../../../images/tutorials/TBED08v00/aliceWL_1866_2.jpg"/>
            <head type="legend">First pages of <title level="m">Alice’s Adventures in Wonderland.</title>
                        </head>
          </figure>
        </p>
        <p>A typical page looks like this: <lb/>
          <figure xml:id="figure2">
            <graphic url="../../../images/tutorials/TBED08v00/aliceWL_1866_3.jpg"/>
            <head type="legend">A typical page of <title level="m">Alice’s Adventures in Wonderland.</title>
                        </head>
          </figure>
        </p>
        <p>As always, the first step in approaching the encoding of a text is a document analysis, considering this is a prose work consisting of chapters.</p>
        <floatingText type="challenge">
          <body>
                        <div xml:id="challenge1" type="challenge.question" corresp="#solution1">
              <p>Make a list of all structural units you can distinguish in the text above and give them a name.</p>
            </div>
                        <div xml:id="solution1" type="challenge.solution">
              <p>Some of the significant structural elements to be distinguished are these:
          <list rend="bulleted">
            <item>The document</item>
            <item>The title page</item>
            <item>Document title</item>
            <item>Chapters</item>
            <item>Headings</item>
            <item>(Sub)Divisions</item>
            <item>Paragraphs</item>
            <item>Quotations</item>
            <item>Citations</item>
            <item>Page breaks</item>
            <item>Figures</item>
            <item>Line groups</item>
          </list>
                            </p>
              </div>
                    </body>
        </floatingText>
        <p>In addition, we are especially interested in the semantic encoding of the names of the different characters and places.</p>
        <p>This document analysis allows us to get an idea of the phenomena we want to encode and how to express them in TEI; for a suggestion of the corresponding TEI elements we refer you to the <ref target="../modules/">other TBE tutorial modules</ref> or the full <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/">TEI Guidelines</ref>.</p>
        <p>However, after completion of this document analysis, we’re not quite ready to start encoding our TEI version of <title level="m">Alice’s Adventures in Wonderland</title>. Unless you know TEI by heart, it will be very hard to produce a valid TEI transcription, without a TEI schema.</p>
        <p>There are two options to get a TEI schema:
          <list rend="ordered">
            <item>Pick one of the sample TEI customisations, available at <ptr target="https://tei-c.org/Guidelines/Customization/"/>, in the format of your choice. TEI provides a number of basic customisations, each with their own focus on different aspects of the TEI model. Depending on your needs, these may provide the elements and attributes you need, or you may want to build on them.</item>
            <item>Create your own schema with the <ref target="https://roma.tei-c.org/">Roma</ref> web tool.</item>
          </list>
          Although the existing TEI customisations in many cases provide all that’s needed for the encoding of common textual phenomena, and the study of these customisations provides an excellent source of information on customising and modifying TEI, in this tutorial we’ll start from scratch. This way, all concepts can be introduced one at a time, and you will get to learn how to actually interpret existing customisations. Alongside the Roma tool itself, the most important concepts of TEI customisation will be treated, split in two strands:
          <list rend="bulleted">
            <item>selection and restriction of existing TEI elements and attributes</item>
            <item>extension of the TEI model with new elements and attributes</item>
          </list>
        </p>
        <note type="summary">Encoding TEI texts with a TEI schema involves customising the TEI. Either you use one of the pre-cooked TEI customisations, or start creating your own with the Roma web tool. Customisation can be roughly divided into selection and restriction of the existing TEI model, and extension of the TEI model.</note>
      </div>
            <div xml:id="minimal">
        <head>Starting from a Minimal Schema</head>
        <p>If you point your browser to <ptr target="https://roma.tei-c.org/"/>, following screen should appear: 
          <figure xml:id="figure3">
            <graphic url="../../../images/tutorials/TBED08v00/romaStart.png"/>
            <head type="legend">The start screen of Roma.</head>
          </figure>
        </p>
        <p>This is the start screen for new customisations, offering you a choice between two options:
          <list rend="bulleted"> 
            <item>
                            <q>Select ODD</q>: start creating a customisation from one of the <soCalled>official</soCalled> TEI customisations</item>
            <item>
                            <q>Upload ODD</q>: start creating a customisation from an existing ODD file on your file system</item>
          </list>
        </p>
        <p>For the purpose of this tutorial, we’ll set out from a minimal customisation. Open the dropdown list and select the <q>TEI Minimal (customize by building TEI up)</q> template. This is a very simple customisation that only selects the TEI elements needed for producing valid TEI documents. Select this template and press the <q>Start</q> button.</p>
        <p>This will produce a configuration screen for your fresh TEI customisation:
          <figure xml:id="figure4">
            <graphic url="../../../images/tutorials/TBED08v00/romaSettings.png"/>
            <head type="legend">ODD configuration screen in Roma.</head>
          </figure>
        </p>
        <p>Here, you can enter details about your customisation file. Let’s just personalise the metadata. Fill in: 
          <list rend="bulleted">
            <item>
                            <q>A TBE Customisation</q> in the <q>Title</q> field;</item>
            <item>
                            <q>TBEcustom</q> in the <q>Filename</q> field; and</item>
            <item>
                            <q>The TBE crew</q> in the <q>Author</q> field.</item>
          </list>
                </p>
        <p>That’s it! We have created a first TEI customisation already, or at least an abstract representation in the Roma web interface. In order to use your TEI customisation in your project, you’ll not only have to derive a schema to tell your XML parser what you consider a valid TEI document for your project, but most likely also human-readable documentation to tell your project team how they should encode the text phenomena they’ll encounter in your project.</p>
        <div xml:id="powerofODD">
          <head>The Power of ODD</head>
          <p>Remember how ODD stands for <soCalled>One Document Does it all</soCalled>? You can derive a number of different schema and documentation output formats from the single ODD file you’re editing! The <q>Download</q> button at the top right of the Roma screen lets you choose between 3 types of output:
            <list rend="bulleted">
              <item>ODD files</item>
              <item>schema files, in a number of flavours</item>
              <item>documentation files, in a number of output formats</item>
            </list>
          </p>
          <p>Since these are frequent operations when customising TEI, they are treated in separate sections below.</p>
          <div xml:id="schemaGen">
            <head>Generating a Schema</head>
            <p>Select the <q>Download</q> button at the top right in the Roma screen, and choose the schema language of your choice (the various schema language output formats are highlighted in yellow):
              <figure xml:id="figure5">
                <graphic url="../../../images/tutorials/TBED08v00/romaDownloadSchema.png"/>
                <head type="legend">Schema download formats in Roma.</head>
              </figure>
            </p>
            <p>Roma can generate schemas in following schema languages: 
              <list rend="bulleted">
                <item>RelaxNG schema: a schema in the more verbose <ref target="https://relaxng.org/spec-20011203.html">XML syntax</ref> of the RelaxNG language</item>
                <item>RelaxNG compact: a schema in the more concise <ref target="https://relaxng.org/compact-20021121.html">compact syntax</ref> of the RelaxNG language</item>
                <item>W3C schema: a schema in the <ref target="https://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/">W3C XSD schema</ref> language</item>
                <item>DTD: a schema in the <ref target="https://www.w3.org/TR/xml/#dt-doctype">DTD</ref> language</item>
                <item>ISO Schematron constraints: a stand-alone file containing all <ref target="http://schematron.com/">ISO Schematron</ref> constraints that are present in the ODD file.</item>
              </list>
            </p>
            <p>Although the schemas generated in these different schema languages are roughly equivalent, some schema languages offer more expressive power than others. The schema languages that offer most complete coverage of TEI features are RelaxNG (XML syntax) and W3C schema.</p>
            <note>We’ll not go into details about the differences between these XML schema languages here. For more information, Wikipedia is your friend: <ptr target="https://en.wikipedia.org/wiki/XML_schema"/>.</note>
            <p>When choosing one of the schema flavours, your browser will download a file named <ident type="file">TBEcustom</ident> (as we had specified earlier for our ODD in the <q>Settings</q> Roma tab). The file’s extension depends on the schema format chosen: <code>.rng</code> (Relax NG XML), <code>.rnc</code> (Relax NG compact), <code>.xsd</code> (W3C schema), <code>.dtd</code> (DTD), or <code>.isosch</code> (ISO Schematron). You can store this file and use it to validate your TEI documents.</p>
          </div>
          <div xml:id="docGen">
            <head>Generating Documentation for a Customisation</head>
            <p>Select the <q>Download</q> button at the top right in the Roma screen, and choose the documentation format of your choice (the various documentation formats are highlighted in yellow):
              <figure xml:id="figure6">
                <graphic url="../../../images/tutorials/TBED08v00/romaDownloadDocumentation.png"/>
                <head type="legend">Documentation download formats in Roma.</head>
              </figure>
            </p>
            <p>Roma can generate documentation in following formats: 
              <list rend="bulleted">
                <item>HTML: a web page containing the documentation of the TEI customisation</item>
                <item>TEI Lite: a TEI Lite file containing the documentation of the TEI customisation</item>
                <item>MS Word: a Word file containing the documentation of the TEI customisation</item>
                <item>LaTeX: a LaTeX file containing the documentation of the TEI customisation</item>
              </list>
            </p>
            <p>Make sure you save the file, and see how this produces a file named <ident type="file">TBEcustom</ident>, either in HTML, TEI XML, DOCX, or LaTeX format. This documentation can serve as your project-specific TEI Guidelines, containing formal references for all elements in the schema, as well as any prose documentation present in the ODD file.</p>
          </div>
          <div xml:id="romaODD">
            <head>Generating an ODD File</head>
            <p>We saved the best for last: without doubt, saving your customisation as an ODD file is <emph>the</emph> most important step of customising TEI with Roma. It will allow you (and others) to upload this customisation again for reuse, fine tune it further, and / or generate both schemas and documentation from this single source file again. Notice that, although all changes you make in the Roma web interface are being recorded automatically, you still have to save your customisation as an ODD file. In order to do so, all you have to do is hit the <q>Download</q> button at the top right in the Roma screen, and choose one of the ODD formats (the ODD formats are highlighted in yellow):
              <figure xml:id="figure7">
                <graphic url="../../../images/tutorials/TBED08v00/romaDownloadODD.png"/>
                <head type="legend">ODD download formats in Roma.</head>
              </figure>
            </p>
            <p>Roma offers following ODD formats:
              <list rend="bulleted">
                <item>Customization as ODD: an ODD file, referencing the various TEI components</item>
                <item>Compiled ODD: an expanded ODD file, containing full documentation and with all references to the TEI components resolved</item>
              </list>
            </p>
            <p>You’ll probably need the first option: <q>Customization as ODD</q>. This will create a file called <ident type="file">TBEcustom.odd</ident>, which is a TEI XML file you can open in any plain text or XML editor. Notice, once again, how the file name corresponds to the one specified for our customisation in the <q>Settings</q> Roma tab.</p>
            <note type="summary">Roma provides a visual interface to create TEI customisations, either from any of the customisation templates provided by the TEI Consortium, or from a previously saved ODD file on your file system. Customisations can be edited in Roma and exported as an ODD (One Document Does it all) file, from which both a TEI schema and accompanying documentation can be derived in a number of output formats. The ODD file is the core of your TEI customisation.</note>
          </div>
        </div>
        <div xml:id="minimalTEI">
          <head>What Does a Minimal TEI Customisation Tell Us?</head>
          <p>Before proceeding, let’s have a closer look at what we’ve done. As mentioned before, the <ident type="file">TBEcustom.odd</ident> file we had stored earlier, is just a TEI XML file. Let’s have a look what’s inside!</p>
          <figure xml:id="example1">
            <egXML xmlns="http://www.tei-c.org/ns/Examples">
              <TEI xmlns:rng="http://relaxng.org/ns/structure/1.0" xml:lang="en">
                <teiHeader>
                  <fileDesc>
                    <titleStmt>
                      <title>A TBE Customisation</title>
                      <author>The TBE crew</author>
                    </titleStmt>
                    <publicationStmt>
                      <publisher>TEI Consortium</publisher>
                      <availability status="free">
                        <licence target="http://creativecommons.org/licenses/by-sa/3.0/"> Distributed under a Creative
                          Commons Attribution-ShareAlike 3.0 Unported License </licence>
                        <!-- ... -->
                      </availability>
                    </publicationStmt>
                    <sourceDesc>
                      <p>Created from scratch by James Cummings, but looking at previous tei_minimal and tei_bare exemplars by SPQR and LR.</p>
                    </sourceDesc>
                  </fileDesc>
                </teiHeader>
                <text>
                  <body>
                    <head>A Minimal TEI Customization</head>
                    <p>This TEI ODD defines a TEI customization that is as minimal as possible and the schema generated from it will validate
                      a document that is minimally valid against the TEI scheme. It includes only the ten required elements:
                      <list rend="numbered">
                        <item>
                                                    <gi>teiHeader</gi> from the header module to store required metadata</item>
                        <item>
                                                    <gi>fileDesc</gi> from the header module to record information about this file</item>
                        <item>
                                                    <gi>titleStmt</gi> from the header module to record information about the title</item>
                        <item>
                                                    <gi>publicationStmt</gi> from the header module to detail how it is published</item>
                        <item>
                                                    <gi>sourceDesc</gi> from the header module to record where it is from</item>
                        <item>
                                                    <gi>p</gi> from the core module for use in the header and the body</item>
                        <item>
                                                    <gi>title</gi> from the core module for use in the titleStmt</item>
                        <item>
                                                    <gi>TEI</gi> from the textstructure module because what is a TEI file without that?</item>
                        <item>
                                                    <gi>text</gi> from the textstructure module to hold some text</item>
                        <item>
                                                    <gi>body</gi> from the textstructure module as a place to put that text</item>
                      </list>
                    </p>
                    <schemaSpec ident="TBEcustom" start="TEI" prefix="tei_" targetLang="en" docLang="en">
                      
                      <!-- required minimal header elements -->
                      <moduleRef key="header" include="teiHeader fileDesc titleStmt publicationStmt sourceDesc"/>
                      
                      <!-- required core elements (p and title for use in titleStmt) -->
                      <moduleRef key="core" include="p title"/>
                      
                      <!-- required textstructure elements (TEI, text, and body) -->
                      <moduleRef key="textstructure" include="TEI text body"/>
                      
                      <!-- required module tei instantiates lots of classes used for further expansion of this odd -->
                      <moduleRef key="tei"/>  
                    </schemaSpec>
                  </body>
                </text>
              </TEI>
            </egXML>
            <head type="legend">A minimal TEI customisation ODD (<ref target="../download/TBEcustom-1-minimal.odd">download</ref>)</head>
          </figure>         
          <p>One immediate observation is that an ODD file is indeed just a regular TEI document, with a <gi>TEI</gi> root element, containing a <gi>teiHeader</gi> element and a <gi>text</gi> element. Remember the metadata you entered in the <q>Settings</q> tab in Roma, and see how it is reflected at the proper places inside the <gi>teiHeader</gi>. However, the most interesting bits are inside the <gi>body</gi> part.</p>
          <p>Apart from regular body content, as illustrated by the <gi>p</gi> contents of our minimal TEI customisation, an ODD file contains a specific <gi>schemaSpec</gi> element. This element indicates a formal definition of a TEI schema. It has a mandatory <att>ident</att> attribute, supplying an identification code for the schema. The language of the documentation can be specified with an optional <att>docLang</att> attribute; when necessary a <att>targetLang</att> attribute can specify what language to use for element and attribute names. The <att>prefix</att> attribute specifies the prefix that will be added to the names of TEI patterns in the customisation. The <att>start</att> attribute identifies the root element(s) of the customisation: in this case, it will produce a schema that only allows the <gi>TEI</gi> element as root element for valid TEI documents.</p>
          <note>Since an ODD file is just a regular TEI file, the formal schema specification in <gi>schemaSpec</gi> can be completed with a detailed prose documentation (and in fact, the concept of an ODD file is <emph>intended</emph> to contain both formal specifications and prose documentation), using the regular TEI elements in the <gi>body</gi> part. Our current example only contains very minimalistic prose documentation; for an excellent example, see the documentation in the <ref target="https://tei-c.org/release/xml/tei/custom/odd/tei_lite.odd">TEI Lite ODD file</ref>, and compare it with the different documentation files offered at <ptr target="https://tei-c.org/guidelines/customization/Lite/"/>.</note>
          <p xml:id="minimalRequirements">The <gi>schemaSpec</gi> element is the core of any ODD file, specifying the formal definition of a TEI schema. A TEI customisation can be constructed by referring to definitions of existing TEI objects (element and attribute classes, datatypes, and macros), or—as will be covered later in this tutorial—by declaring new objects as well. In our example so far, the schema specification only contains references to four of the predefined TEI modules. Each module is being referred to in a separate <gi>moduleRef</gi> element, whose <att>key</att> attribute is pointing to the formal identifier of that module in the TEI source.</p>
          <p>When a module is selected with <gi>moduleRef</gi> in an ODD file, by default all elements and attributes of that module are incorporated in the customisation. In our example, this is the case with the <ident type="module">tei</ident> module. As we have seen, this is a special module, which doesn’t define any elements and attributes itself, but instead a lot of classes, datatypes, and macros that are being used in all other TEI modules. Three of those other modules are being referenced in our current ODD file. Yet, only a very small number of elements they define are being included in our customisation, because the <gi>moduleRef</gi> elements have an <att>include</att> attribute, where only those elements that should be included are enumerated as a white-space separated list. If you count them, our customisation only selects the 10 elements that are required for minimally valid TEI documents.</p>
          <p>Notice, how the <att>include</att> mechanism has a counterpart: it is equally possible to specify which elements <emph>not</emph> to include in a module by enumerating them in an <att>except</att> attribute. This will only exclude those elements, but will include all others. Both mechanisms offer convenient shortcuts to either include or exclude large numbers of elements. It’s important to remember that you can only use either the <att>include</att> or the <att>except</att> attribute on a <gi>moduleRef</gi> element, but not both.</p>
          <note type="summary">TEI groups its different elements and their attributes in 21 modules. When defining a TEI customisation, these modules can be referred to in an ODD file. An ODD file is just a regular TEI document with a specific element for defining a TEI schema: <gi>schemaSpec</gi>. An identification for the schema must be provided in an <att>ident</att> attribute. Inside the schema specification, modules can be referenced with a <gi>moduleRef</gi> element, naming the module in a <att>key</att> attribute. When a TEI module is included in a customisation, by default all of its elements and attributes will be included. In order to include specific elements only, the names of these elements can be enumerated in an <att>include</att> attribute. Likewise, if only some of the elements of a module should be excluded, they can be enumerated in an <att>except</att> attribute on <gi>moduleRef</gi>.</note>            
          
          <!-- [RvdB] remove?          
          <p>Let’s have a closer look at what these <gi>moduleRef</gi> elements tell us:
            <list rend="bulleted">
              <item>All TEI elements and their attributes are organised thematically in 21 higher-level modules. Compare them to the shelves holding the elements and attributes, in the library analogy developed in <ptr target="#intro"/>. If a module is selected, by default all elements and attributes of that module are incorporated in the schema. In our example, all elements of the four modules being selected (with the exception of <gi>teiCorpus</gi>, which is deleted explicitly from the <ident>core</ident> module), will be included in the customisation.</item>
              <item>A minimal TEI customisation isn't empty, but will always refer to the modules <ident>tei</ident>, <ident>header</ident>, <ident>textstructure</ident>, and <ident>core</ident>. This means that if any of these modules is not referenced from an ODD file, it will never be able to define a TEI conformant schema.</item>
            </list>
          </p>
-->          
        </div>
        <div xml:id="minimalTEIRoma">
          <head>Inspecting a Customisation in Roma</head>
          <p>As we have introduced in <ptr target="#terminology" type="crossref"/>, the TEI is a highly sophisticated library, holding model and attribute classes, macros, and datatypes. Customising TEI requires some knowledge of how they are organised. Full documentation can be found in the TEI Guidelines, but fortunately, Roma is conceived as a convenient online store for selecting the exact TEI components you need, and doing so, it shows you around in the internals of TEI as well. Let’s start editing our current customisation where we have left it by hitting the <q>Customize ODD</q> button at the top right in the Roma screen:
            <figure xml:id="figure8">
              <graphic url="../../../images/tutorials/TBED08v00/romaSettings.png"/>
              <head type="legend">Start customising an ODD file with the <q>Customize ODD</q> button.</head>
            </figure>
          </p>
          <p>This will take you to the main Roma dashboard. You can tell you’re editing the right customisation from the title at the top of the screen, which reads <q>Roma - ODD Customization (A TBE customisation)</q>.
            <figure xml:id="figure9">
              <graphic url="../../../images/tutorials/TBED08v00/romaMain.png"/>
              <head type="legend">Roma main screen.</head>
            </figure>
          </p>
          <p>Below the title, you see 4 different tabs at the top of the screen:
            <list rend="bulleted">
              <item>
                                <q>Elements</q>: an overview of all available TEI elements, allowing you to select and customise those you need</item> 
              <item>
                                <q>Attribute Classes</q>: an overview of all available TEI attribute classes, allowing you to select and customise those you need</item>
              <item>
                                <q>Model Classes</q>: an overview of all available TEI model class definitions, allowing you to select and customise those you need</item>
              <item>
                                <q>Datatypes</q>: an overview of all available TEI datatype definitions, allowing you to select and customise those you need</item>
            </list>
          </p>
          <p>Let’s check how the <gi>moduleRef</gi> elements we’ve seen in our current TEI customisation are being reflected in the Roma interface. When you select the <q>Elements</q> tab, you’ll notice that only a very small number of elements are ticked. Indeed, from the long list of available TEI elements, only 10 have been selected: <gi>body</gi>, <gi>fileDesc</gi>, <gi>p</gi>, <gi>publicationStmt</gi>, <gi>sourceDesc</gi>, <gi>TEI</gi>, <gi>teiHeader</gi>, <gi>text</gi>, <gi>title</gi>, and <gi>titleStmt</gi>. Notice, how the default ordering in Roma is alphabetical; you can also click the <q>by module</q> button at the top right of the Roma screen. This will order the elements (or attribute classes, or model classes, or datatypes) alphabetically: first per module, and next by name. This sorting <soCalled>by module</soCalled> gives you an idea of what TEI components are being defined in each of the modules. This is broader than elements: if you look at the other tabs, you’ll notice that a lot of attribute classes, model classes, and datatypes are being included automatically when a TEI module is included via <gi>moduleRef</gi> in a TEI customisation.</p>
        </div>
      </div>
            <div xml:id="selecting">
        <head>Selecting and Restricting the TEI Model</head>
        <p>Back to <title level="m">Alice</title>! As we have discussed, our minimal TEI customisation now includes 10 TEI elements, just enough to be able to create TEI-conformant documents. But does this suffice for encoding our <title level="m">Alice</title> example? Not really, since we’re still lacking a bunch of TEI elements to encode the textual phenomena we identified during our document analysis:
          <list rend="bulleted">
            <item>The title page: <gi>titlePage</gi>, <gi>docAuthor</gi>, <gi>byline</gi>, <gi>docImprint</gi>, <gi>publisher</gi>, <gi>docDate</gi>.</item>
            <item>Document structure: <gi>div</gi>, <gi>lg</gi>, <gi>l</gi>.</item>
            <item>Text elements: <gi>emph</gi>, <gi>q</gi>, <gi>pb</gi>, <gi>figure</gi>, <gi>graphic</gi>, <gi>figDesc</gi>, <gi>fw</gi>.</item>
            <item>Semantic units: <gi>name</gi>.</item>
          </list>
        </p>
        <p>Back to the drawing board of our TEI customisation, back to Roma!</p>
<!-- [RvdB] keep this (somewhere)?         
                        <note>In fact, all elements described in this TBE tutorial module belong to the TEI <ident>tagdocs</ident> module, documented in <ref target="http://www.tei-c.org/release/doc/tei-p5-doc/en/html/TD.html">chapter 22</ref> of the TEI Guidelines.</note>
-->                        
        <div xml:id="modulesElements">
          <head>Selecting Modules and Elements</head>
          <p>In order to encode the textual phenomena we’d identified for our example text, a number of TEI elements have to be included in our TEI customisation. This can be done easily in Roma by ticking the corresponding boxes in the <q>Elements</q> tab.
            <figure xml:id="figure10">
              <graphic url="../../../images/tutorials/TBED08v00/romaElements.png"/>
              <head type="legend">The <q>Elements</q> tab in Roma.</head>
            </figure>
          </p>
          <p>Notice how the right-hand column in Roma informs you for any element which module it belongs to. A convenient way to include or exclude all elements from a module at once, is by selecting or de-selecting that module. In order to do so, you can click the module name. For example, let’s select the <ident type="module">figures</ident> module by clicking the plus sign next to that module name: <graphic url="../../../images/tutorials/TBED08v00/romaSelectModule.png"/>
                    </p>
          <p>If we order the elements by module (by clicking the <q>by module</q> button at the top right of the Roma screen) and scroll down to the <ident type="module">figures</ident> module, you’ll see that all of its elements now have been included in your customisation. This includes some elements we didn’t identify in the document analysis for our document; if we are absolutely certain we only have to encode images, but no tables, formulas, or music notations, these elements can quickly be deselected by unticking the element name in the left-hand column:
          <figure xml:id="figure11">
            <graphic url="../../../images/tutorials/TBED08v00/romaDeselectElements.png"/>
            <head type="legend">De/selecting elements in Roma.</head>
          </figure>
          </p>
          <p>Did you notice how the <gi>graphic</gi> element is part of the <ident type="module">core</ident> module, and not of <ident type="module">figures</ident>? If you want to include the images themselves in your transcription of <title level="m">Alice</title>, you’ll have to include the <gi>graphic</gi> element as well. Hint: you can quickly look up an element by entering its name in the search box at the top right of the Roma screen:
            <figure xml:id="figure12">
              <graphic url="../../../images/tutorials/TBED08v00/romaFilter.png"/>
              <head type="legend">Filtering element names in Roma.</head>
            </figure>
          </p>
          <p>That’s all there is to including and excluding existing TEI elements with Roma! You can also remove an entire module at once, with the caveat that this will remove all its members (and possible modifications you’ve made to them) from your customisation. Since you might run the risk of losing work here, Roma issues a warning in order to prevent unwanted mistakes:
            <figure xml:id="figure13">
              <graphic url="../../../images/tutorials/TBED08v00/romaRemoveModule.png"/>
              <head type="legend">Warning when removing an entire module in Roma.</head>
            </figure>
          </p>
          <p>Now, save your customisation as an ODD file (click the <q>Download</q> &gt; <q>Customization as ODD</q> button at the top right of the Roma screen). Its <gi>schemaSpec</gi> element will be updated to:
            <figure xml:id="example2">
              <egXML xmlns="http://www.tei-c.org/ns/Examples">
                <schemaSpec ident="TBEcustom" start="TEI" prefix="tei_" targetLang="en" docLang="en">
                  <moduleRef key="figures" include="figDesc figure"/>
                  <moduleRef key="header" include="teiHeader fileDesc titleStmt publicationStmt sourceDesc"/>
                  <moduleRef key="core" include="p title graphic emph lg l pb pubPlace publisher q quote name"/>
                  <moduleRef key="textstructure" include="TEI text body titlePage docTitle docImprint docDate docAuthor byline"/>
                  <moduleRef key="tei"/>
                </schemaSpec>
              </egXML>
              <head type="legend">A minimal TEI customisation with more TEI elements added (<ref target="../download/TBEcustom-2-selectElements.odd">download</ref>).</head>
            </figure>
          </p>
          <note>Because all further changes to the ODD file in this TBE tutorial module will affect only its <gi>schemaSpec</gi> part, the example fragments will focus on this element.</note>
<!-- [RvdB] not relevant here, perhaps later?
            <p>A first thing of notice is the addition of our extra module <ident>figures</ident> with a <gi>moduleRef</gi> element, followed by an exclusion of the table and formula related elements from the <ident>figures</ident> module. This is done in an  <gi>elementSpec</gi> element specification for each element, documenting the structure, content, and purpose of a single element.  Each <gi>elementSpec</gi> must identify the element it specifies in an <att>ident</att> attribute. Since all TEI elements are part of TEI modules, this module should be identified in the <gi>module</gi> attribute. A third attribute, <att>mode</att>, describes the operation to be performed. This attribute can occur on other elements in a schema specification, with one of four values:
            <list type="gloss">
              <item><label>add</label> the current specification is added to the schema</item> 
              <item><label>delete</label> the current specification is deleted from the schema</item>
              <item><label>change</label> the current specification changes the declaration of an item with the same name in a schema</item>
              <item><label>replace</label> the current specification replaces the declaration of an item with the same name in a schema</item>
            </list>
          </p>-->
          <p>When we generate a TEI schema from this customisation (via the <q>Download</q> button at the top right of the Roma screen), this allows us to validate a transcription of a typical page of the document (the third image from the <title level="m">Alice</title> scans above) as follows:
            <egXML xmlns="http://www.tei-c.org/ns/Examples">
              <!-- ... -->                                
              <div type="chapter">
                <!-- ... -->
                <pb n="157"/>
                <figure>
                  <graphic url="images/lobster.jpg"/>
                  <figDesc>The lobster sugaring its hair.</figDesc>
                </figure>
                <p>
                  <q who="#alice">"How the creatures order one about, and make one repeat lessons!"</q> thought <name type="person">Alice</name>, <q who="#alice">"I might just as well be at school at once."</q> However, she got up, and began to repeat it, but her head was so full of the <title type="song">
                                        <name type="animal">Lobster</name>-Quadrille</title>, that she hardly knew what she was saying, and the words came very queer indeed:—</p>
                <q rend="blockquote" who="#alice">
                  <lg>
                    <l>"'Tis the voice of the <name type="animal">lobster</name>; I heard him declare,</l>
                    <l>
                                            <q who="#lobster">'You have baked me too brown, I must sugar my hair.'</q>
                                        </l>
                    <l>As a duck with its eyelids, so he with his nose</l>
                    <l>Trims his belt and his buttons, and turns out his toes."</l>
                  </lg>
                </q>
                <p>
                  <q who="#gryphon">"That's different from what <emph>I</emph> used to say when I was a child,"</q> said the <name type="animal">Gryphon</name>.</p>
                <pb n="158"/>
                <p>
                  <q who="#mockTurtle">"Well, I never heard it before,"</q> said the <name type="animal">Mock Turtle</name>; <q who="#mockTurtle">"but it sounds uncommon nonsense."</q>
                                </p>
                <p>
                                    <name type="person">Alice</name> said nothing; she had sat down with her face in her hands, wondering if anything would <emph>ever</emph> happen in a natural way again.</p>
                <p>
                                    <q who="#mockTurtle">"I should like to have it explained,"</q> said the <name type="animal">Mock Turtle</name>.</p>
                <p>
                                    <q who="#gryphon">"She can't explain it,"</q> said the <name type="animal">Gryphon</name> hastily. <q who="#gryphon">"Go on with the next verse."</q>
                                </p>
                <p>
                                    <q who="#mockTurtle">"But about his toes?"</q> the <name type="animal">Mock Turtle</name> persisted. <q who="#mockTurtle">"How <emph>could</emph> he turn them out with his nose, you know?"</q>
                                </p>
                <p>
                                    <q who="#aliceI">"It's the first position in dancing."</q> <name type="person">Alice</name> said; but she was dreadfully puzzled by the whole thing, and longed to change the subject.</p>
                <p>
                                    <q who="#gryphon">"Go on with the next verse,"</q> the <name type="animal">Gryphon</name> repeated impatiently: <q who="#gryphon">"it begins <quote>'I passed by his garden.'</quote>"</q>
                                </p>
                <p>
                                    <name type="person">Alice</name> did not dare to disobey, though she felt sure it would all come wrong, and she went on in a trembling voice:—</p>
                <pb n="159"/>
                <!-- ... -->
              </div>
              <!-- ... -->                                
            </egXML>
          </p>
          <p>So far for selecting modules and elements. The obvious counterpart, adding <emph>new</emph> elements, will be dealt with later in this tutorial (see <ptr target="#extending" type="crossref"/>). First we will focus on attributes.</p>
          <note type="summary">Modules can be selected simply by referencing them with a <gi>moduleRef</gi> element, whose <att>key</att> attribute must be used to identify the desired TEI module. By default, all elements of a module are selected for inclusion in the schema. If an <att>include</att> attribute is present, only those elements that are being enumerated will be included in the customisation, and all others won’t. If you want to exclude only a couple of elements from a module, but include all others, this can conveniently be done by enumerating the ones you don’t want in an <att>except</att> attribute. You can’t use both at the same time. <!--
            
            
            Deleting unneeded elements can be done simply with an <gi>elementSpec</gi> element, with an <att>ident</att> attribute indicating the existing name of the TEI element whose declaration is to be altered. The module to which the element belongs must be named in the <att>module</att> attribute. In order to specify that these elements should be deleted, the <att>mode</att> attribute should state <val>delete</val>.-->
                    </note>
        </div>
        <div xml:id="attributes">
          <head>Changing Attributes</head>
          <div xml:id="singleAttributes">
            <head>Changing Individual Attributes</head>
            <p>As shown in the previous encoding snippet, the <gi>name</gi> element definition (from the <ident type="module">core</ident> module) comes with a <att>type</att> attribute. By providing a keyword for this attribute, we can specify what type of name is being identified with the <gi>name</gi> element. By default, the <att>type</att> attribute can contain any single keyword from an unspecified list: anything goes as long as it conforms to some syntactic rules, specified in the <ident type="datatype">teidata.enumerated</ident> datatype (basically, only a few punctuation marks are allowed, and it should start with a letter). Apart from that, there is no limit on possible values for the <att>type</att> attribute. However, to improve consistency in our <title level="m">Alice</title> encoding project, we would like to trim down these possibilities for the <att>type</att> attribute of <gi>name</gi>. We’re only interested in the categories <val>person</val>, <val>place</val>, and <val>animal</val>. This can be done in Roma, by navigating to the definition of the <gi>name</gi> element. In order to do so: 
              <list rend="ordered">
                <item>load the <ident type="file">TBEcustom</ident> customisation again in Roma if you haven’t done so already, and click the <q>Customize ODD</q> button,</item>
                <item>move to the <q>Elements</q> tab and scroll down to the definition of <gi>name</gi>.</item>
              </list>
            </p>
            <p>In order to edit its attributes, just click the <q>name</q> element in the list (make sure it is selected, before you can click it):
              <figure xml:id="figure14">
                <graphic url="../../../images/tutorials/TBED08v00/romaClickElement.png"/>
                <head type="legend">Navigating to an element definition by clicking its name in Roma.</head>
              </figure>
            </p>
            <p>Clicking an element in Roma opens an <soCalled>edit</soCalled> screen, where some aspects can be changed:
              <list rend="bulleted">
                <item>
                                    <q>Documentation</q> here you can change the description of an element</item>
                <item>
                                    <q>Attributes</q> here you can change the attributes of an element</item>
                <item>
                                    <q>Class Membership &amp; Content Model</q> here you can change the classes an element belongs to, and the elements or element classes it can contain</item>
              </list>
              <figure xml:id="figure15">
                <graphic url="../../../images/tutorials/TBED08v00/romaEditElement.png"/>
                <head type="legend">Element editing screen in Roma.</head>
              </figure>
            </p>
            <p>Since we want to restrict the values allowed for the <att>type</att> attribute of <gi>name</gi>, hit the <q>Attributes</q> button. This produces an overview of all attributes defined for the <gi>name</gi> element, organised per attribute class from which they are inherited: 
              <figure xml:id="figure16">
                <graphic url="../../../images/tutorials/TBED08v00/romaEditElementAttributes.png"/>
                <head type="legend">Display of an element’s attributes in Roma.</head>
              </figure>
            </p>
            <p>Scroll down to the bottom, where you will find the <att>type</att> attribute listed (in the <ident type="class">att.typed</ident> attribute class). Left of each attribute name, you’ll find a pencil icon for editing the attribute, and a cross icon for removing the attribute. Since we want to restrict the values for the <att>type</att> attribute, just click the pencil icon next to it. This will show the current definition of that attribute. There you can determine whether the attribute should be mandatory or optional, what the datatype of its value(s) should be, and what kind of values it allows. The <q>Values</q> section is where we can restrict the possible values for the <att>type</att> attribute for names to a closed list. In order to do so:
              <list rend="ordered">
                <item>Click the drop-down box in the <q>Values</q> field, and change it to <q>Closed</q>.</item>
                <item>For each value we want to allow for this attribute (<val>place</val>, <val>person</val>, and <val>animal</val>), enter the value in the text box below, and click the <q>+</q> sign next to it.</item>
                <item>For each new value, a description can be provided by clicking the <q>+</q> sign next to <q>Description</q>.</item>
              </list>
              <figure xml:id="figure17">
                <graphic url="../../../images/tutorials/TBED08v00/romaEditElementAttributeValues.png"/>
                <head type="legend">Changing the attributes for an element in Roma.</head>
              </figure>
            </p>
            <p>The changes are being recorded immediately in Roma. Clicking the <q>Attributes</q> button in the top menu of the Roma screen brings us back to the attributes list for the <gi>name</gi> element. Now, let’s remove some attributes we don’t need in our encoding project. With Roma, it’s possible to remove entire attribute classes at once by clicking the <q>X</q> sign next to the attribute class names in the list. Let’s do so for <ident type="class">att.datable</ident>, <ident type="class">att.editLike</ident>, <ident type="class">att.global.responsibility</ident>, <ident type="class">att.global.source</ident>, <ident type="class">att.naming</ident>, and <ident type="class">att.personal</ident>. Also, the <att>subtype</att> and <att>nymRef</att> attributes can go, just click the <q>X</q> sign next to the attribute name.              
              <!-- 
              If you scroll down to <att>type</att> again, you'll notice that its description now reads <q>type (changed for this element)</q>, which is what we wanted.</p>
            <p>The list of attributes for <gi>name</gi> still is impressive. Roma makes it easy to trim down this list to only those attributes you want to allow in your customisation. In order to remove them, just click the cross icon next to the attributes, or attribute classes you want to remove for that element. For this customization, we’re only interested in the <gi>name</gi> attributes from the <ident type="class">att.global</ident>, <ident type="class">att.global.rendition</ident>, and <ident type="class">att.type</ident> modules, so you can remove the others. Also, since <att>subtype</att> is not relevant for our encoding of names in <title>Alice</title>, we can remove that attribute, too. -->
            </p>
            <p>If we save the customisation at this stage (by clicking the <q>Download</q> &gt; <q>Customization as ODD</q> button), the ODD file gets updated to:
              <figure xml:id="example3">
                <egXML xmlns="http://www.tei-c.org/ns/Examples">
                  <schemaSpec ident="TBEcustom" start="TEI" prefix="tei_" targetLang="en" docLang="en">
                    <moduleRef key="figures" include="figDesc figure"/>
                    <moduleRef key="header" include="teiHeader fileDesc titleStmt publicationStmt sourceDesc"/>
                    <moduleRef key="core" include="p title emph lg l pb pubPlace publisher q quote name graphic"/>
                    <moduleRef key="textstructure" include="TEI text body titlePage docTitle docImprint docDate docAuthor byline div"/>
                    <moduleRef key="tei"/>
                    <elementSpec ident="name" mode="change">
                      <classes mode="change">
                        <memberOf key="att.datable" mode="delete"/>
                        <memberOf key="att.editLike" mode="delete"/>
                        <memberOf key="att.personal" mode="delete"/>
                      </classes>
                      <attList>
                        <attDef ident="subtype" mode="delete"/>
                        <attDef ident="nymRef" mode="delete"/>
                        <attDef ident="type" mode="change">
                          <valList type="closed" mode="change">
                            <valItem mode="add" ident="place">
                              <desc versionDate="2020-04-23" xml:lang="en">used for place names</desc>
                            </valItem>
                            <valItem mode="add" ident="person">
                              <desc versionDate="2020-04-23" xml:lang="en">used for person names</desc>
                            </valItem>
                            <valItem mode="add" ident="animal">
                              <desc versionDate="2020-04-23" xml:lang="en">used for animal names</desc>
                            </valItem>
                          </valList>
                        </attDef>
                        <attDef ident="cert" mode="delete"/>
                        <attDef ident="resp" mode="delete"/>
                        <attDef ident="source" mode="delete"/>
                      </attList>
                    </elementSpec>
                  </schemaSpec>
                </egXML>
                <head type="legend">Attribute classes removed and attribute values changed for the <gi>name</gi> element (<ref target="../download/TBEcustom-3-editNameAttributes.odd">download</ref>).</head>
              </figure>
            </p>
            <p>Notice how a new element is introduced: <gi>elementSpec</gi>. In a schema specification, this is where elements are being defined. It has a mandatory <att>ident</att> attribute, which names the element. In this case, the <val>name</val> value tells us that this element specification defines a <gi>name</gi> element. Although this could be specified further by adding a <att>module</att> attribute with value <val>core</val>, this is not mandatory, since element names are unique across all TEI modules.</p>
            <p>Defining a TEI element that already exists might seem a bit weird at first sight. Notice, however, the <att>change</att> attribute with the value <val>change</val>, which is expressing that this existing TEI element is being changed in this customisation. This is an important mechanism: via the <att>mode</att> attribute, ODD lets you specify a number of actions on the declaration of elements and attributes (and many of their components):
              <list type="gloss"> 
                <label>
                                    <val>add</val>
                                </label>
                <item>a new declaration is added to the current definitions</item>
                <label>
                                    <val>delete</val>
                                </label>
                <item>an existing declaration is removed</item>
                <label>
                                    <val>change</val>
                                </label>
                <item>an existing declaration is changed partly: only the customised parts are changed; all other parts are copied from their TEI definition</item>
                <label>
                                    <val>replace</val>
                                </label>
                <item>an existing declaration is changed completely: only the customised parts are copied; all existing TEI definitions are ignored</item>
              </list>
            </p>
            <p>In our ODD file, the <tag>elementSpec ident="name" mode="change"</tag> element is telling that the existing declaration of <gi>name</gi> (in the <ident type="module">core</ident> module) should be copied, except for the components that are overridden in this customisation. In this case, there are both class-related changes, that are grouped in a <gi>classes</gi> element, and attribute-related changes, that are grouped in an <gi>attList</gi> element. The <gi>classes</gi> element groups class membership declarations in <gi>memberOf</gi> elements. In this case, three class memberships are deleted: each <gi>memberOf</gi> element refers to the class with the value of a <att>key</att> attribute, and next states that this membership should be removed, by the <val>delete</val> value for the <att>mode</att> attribute. It’s interesting to notice that, even though we removed the <ident type="class">att.canonical</ident> class in Roma, this is not reflected in a separate <tag type="empty">memberOf key="att.canonical" mode="delete</tag> element in the ODD file. This is not strictly needed, since <ident type="class">att.canonical</ident> is a member of <ident type="class">att.personal</ident>, so removal of the latter superclass automatically implies that the subclass(es) are removed as well.</p> 
            <p>Apart from class deletions, the <gi>elementSpec</gi> element with the definition of the customised <gi>name</gi> element groups attribute declaration in an <gi>attList</gi> element. Each attribute is declared in an <gi>attDef</gi> element. Here, too, the attribute is identified with an <att>ident</att> attribute, and the customisation action is given in <att>mode</att>. Four attributes are deleted: <att>subtype</att>, <att>nymRef</att>, <att>cert</att> and <att>resp</att> (from the <ident type="class">att.global.responsibility</ident> attribute class), and <att>source</att> (from the <ident type="class">att.global.source</ident> attribute class). It’s interesting to notice that Roma doesn’t just remove these classes via a <gi>memberOf</gi> element, as with the other attribute classes we had deleted, but instead removes their attributes individually. While both ways of removing attributes in ODD are equivalent, Roma probably opts to remove <soCalled>standalone</soCalled> classes as such, while members of <soCalled>inherited</soCalled> classes are removed individually.</p>
            <p>The definition for the <att>type</att> attribute, has the value <val>change</val> for its <att>mode</att> attribute, meaning that its contents should override the existing definitions. Since we restricted the list of possible values to a closed vocabulary, a <gi>valList</gi> re-defines the value list of this <att>type</att> attribute. Its <att>type</att> attribute with value <val>closed</val>, indicates that the attribute value list is a closed list. In order to indicate that only the parts defined in our customisation should be changed, a <att>mode</att>=<val>change</val> attribute is given on <gi>valList</gi>. The different values of this closed list are defined in a series of <gi>valItem</gi> elements, with the value of the attribute given in an <gi>ident</gi> attribute (in this case: <val>place</val>, <val>person</val>, and <val>animal</val>, respectively). Inside <gi>valItem</gi>, the description of the attribute value is given in a <gi>desc</gi> element. Notice that, since these attribute values are new, the <att>mode</att> attribute on each <gi>valItem</gi> element has the value <val>add</val>, to tell the ODD processor that they should be added to the existing definition of the <att>type</att> attribute. All other parts of the existing TEI definition of the <att>type</att> attribute are being copied when transforming this ODD file to a schema or documentation.<note>Notice, however, that a full attribute definition consists of more fields, like a description, declarations of datatype and occurrence indicators. These are discussed later in this module (<ptr type="crossref" target="#addAttributes"/>).</note>
            </p>
            <note type="summary">Elements are defined in an ODD file with the <gi>elementSpec</gi> element. The element must be identified in an <att>ident</att> attribute, and the processing mode should be stated in a <att>mode</att> attribute. Inside an element declaration, entire attribute classes can be removed by removing their membership of an attribute class. This is done inside a <gi>classes</gi> section, where each class membership is declared in a <gi>memberOf</gi> element. The value <val>delete</val> for the <att>mode</att> attribute indicates that a class membership should be removed. Declarations for individual attributes are grouped in an <gi>attList</gi> element inside <gi>elementSpec</gi>. Each single attribute is given its own definition inside an <gi>attDef</gi> element. This element, too, carries the <att>ident</att> and <att>mode</att> attributes, respectively for identifying the attribute, and specifying the status of the declaration. To delete attributes, indicating the <att>mode</att> as <val>delete</val> suffices. Changing attributes requires a <val>change</val> mode. Value lists for an attribute can be defined in a <gi>valList</gi> element, whose <att>type</att> attribute indicates whether the value list is open-ended (<val>open</val>) or closed (<val>closed</val>). The <att>mode</att> attribute can specify whether a <gi>valList</gi> declaration merely contains some changes to the existing TEI declaration (<val>change</val>), or replaces the original definition (<val>replace</val>). A value list declares each separate value for an attribute in a <gi>valItem</gi> element, with the value given in an <att>ident</att> attribute. The attribute value can be described in a <gi>desc</gi> element.</note>
          </div>
          <div xml:id="attributeClasses">
            <head>Changing Attribute Classes</head>
            <p>As mentioned before, TEI modules group attribute definitions into <term>attribute classes</term>. This facilitates the definition of elements that share the same attributes, by declaring them as members of an attribute class. For example, all TEI elements are declared members of the <ident type="class">att.global</ident> attribute class, which defines the global attributes <att>xml:id</att>, <att>n</att>, <att>xml:lang</att>, <att>rend</att>, <att>rendition</att>, and <att>xml:base</att>.</p>
            <p>As it happens, the <att>nymRef</att> attribute we have deleted from the definition of the <gi>name</gi> element in the previous section, is defined in such an attribute class, namely <ident type="class">att.naming</ident>, of which <gi>name</gi> is declared a member. This information may seem disparate, but is actually easy to find in Roma. Actually, we’ve been there before: 
              <list rend="ordered">
                <item>load the <ident type="file">TBEcustom</ident> customisation again in Roma if you haven’t done so already, and click the <q>Customize ODD</q> button,</item>
                <item>move to the <q>Elements</q> tab and scroll down to the definition of <gi>name</gi>.</item>
              </list>
              Remember how the attributes for <gi>name</gi> were grouped per attribute class? Those attribute class names are clickable in Roma. One way of accessing the <ident type="class">att.naming</ident> attribute class definition in Roma, is by clicking the link with the label <ident type="class">att.naming</ident> in the attributes list:
              <figure xml:id="figure18">
                <graphic url="../../../images/tutorials/TBED08v00/romaElementAttributeClasses.png"/>
                <head type="legend">Accessing the definition of an attribute class via the attributes list of an element in Roma.</head>
              </figure>
            </p>
            <p>Another way of navigating to the attribute classes, is by selecting the <q>Attribute Classes</q> tab at the top left of the Roma screen. As with the <q>Elements</q> tab, you’ll get a list of all attribute classes, with an indication of those that have been included in the current customisation, and an indication of the TEI module that defines them. 
              <figure xml:id="figure19">
                <graphic url="../../../images/tutorials/TBED08v00/romaAttributeClasses.png"/>
                <head type="legend">The <q>Attribute Classes</q> tab in Roma.</head>
              </figure>
            </p>
            <p>Clicking the link with the label <ident type="class">att.naming</ident> attribute class here, will take you to the definition of this attribute class:
              <figure xml:id="figure20">
                <graphic url="../../../images/tutorials/TBED08v00/romaAttributeClass.png"/>
                <head type="legend">Attribute class editing screen in Roma.</head>
              </figure>
            </p>
            <p>The <q>Attributes</q> button will take us to the definition of the attributes inside this class:
              <figure xml:id="figure21">
                <graphic url="../../../images/tutorials/TBED08v00/romaEditAttributeClass.png"/>
                <head type="legend">Display of the attributes in an attribute class in Roma.</head>
              </figure>
            </p>
            <p>The attribute class contains a number of sections: <q>Class Attributes</q> define the attributes of this class, in this case <att>nymRef</att> and <att>role</att>. In <q>Class Membership</q>, a superclass can be given; here, the <ident type="class">att.naming</ident> attribute class is declared as a member of the <ident type="class">att.canonical</ident> attribute class. This means that elements declaring themselves as member of (the subclass) <ident type="class">att.naming</ident>, will also inherit the attributes defined in (the superclass) <ident type="class">att.canonical</ident>, namely <att>key</att> and <att>ref</att>. Finally, the section <q>Member Classes</q> names attribute classes that are defined as subclass of <ident type="class">att.naming</ident>, in this case <ident type="class">att.personal</ident>.</p>
            <p>Now, instead of removing the <att>nymRef</att> attribute only from the <gi>name</gi> element as we did in the previous section, we could as well delete it globally from all elements that are member of the <ident type="class">att.naming</ident> attribute class. This can be done simply by clicking the <q>X</q> sign next to the <att>nymRef</att> attribute name.</p>
            <p>If we save the customisation again (by clicking the <q>Download</q> &gt; <q>Customization as ODD</q> button at the top right of the Roma screen), this produces following ODD file:
              <figure xml:id="example4">
                <egXML xmlns="http://www.tei-c.org/ns/Examples">
                  <schemaSpec ident="TBEcustom" start="TEI" prefix="tei_" targetLang="en" docLang="en">
                    <moduleRef key="figures" include="figDesc figure"/>
                    <moduleRef key="header" include="teiHeader fileDesc titleStmt publicationStmt sourceDesc"/>
                    <moduleRef key="core" include="p title emph lg l pb pubPlace publisher q quote name graphic"/>
                    <moduleRef key="textstructure" include="TEI text body titlePage docTitle docImprint docDate docAuthor byline div"/>
                    <moduleRef key="tei"/>
                    <elementSpec ident="name" mode="change">
                      <classes mode="change">
                        <memberOf key="att.datable" mode="delete"/>
                        <memberOf key="att.editLike" mode="delete"/>
                        <memberOf key="att.personal" mode="delete"/>
                      </classes>
                      <attList>
                        <attDef ident="cert" mode="delete"/>
                        <attDef ident="resp" mode="delete"/>
                        <attDef ident="source" mode="delete"/>
                      </attList>
                    </elementSpec>
                    
                    <elementSpec ident="name" mode="change">
                      <classes mode="change">
                        <memberOf key="att.datable" mode="delete"/>
                        <memberOf key="att.editLike" mode="delete"/>
                        <memberOf key="att.personal" mode="delete"/>
                      </classes>
                      <attList>
                        <attDef ident="subtype" mode="delete"/>
                        <attDef ident="nymRef" mode="delete"/>
                        <attDef ident="type" mode="change">
                          <valList type="closed" mode="change">
                            <valItem mode="add" ident="place">
                              <desc versionDate="2020-04-23" xml:lang="en">used for place names</desc>
                            </valItem>
                            <valItem mode="add" ident="person">
                              <desc versionDate="2020-04-23" xml:lang="en">used for person names</desc>
                            </valItem>
                            <valItem mode="add" ident="animal">
                              <desc versionDate="2020-04-23" xml:lang="en">used for animal names</desc>
                            </valItem>
                          </valList>
                        </attDef>
                        <attDef ident="cert" mode="delete"/>
                        <attDef ident="resp" mode="delete"/>
                        <attDef ident="source" mode="delete"/>
                      </attList>
                    </elementSpec>
                    <classSpec ident="att.naming" type="atts" mode="change">
                      <attList>
                        <attDef ident="nymRef" mode="delete"/>
                      </attList>
                    </classSpec>
                  </schemaSpec>
                </egXML>
                <head type="legend">Changed attribute class (<ref target="../download/TBEcustom-4-editAttNaming.odd">download</ref>).</head>
              </figure>
            </p>
            <p>Now, the <gi>schemaSpec</gi> element in our customisation ODD file contains another element, besides <gi>elementSpec</gi>: <gi>classSpec</gi>. This is where classes are being declared. As with element and attribute definitions, the name of the class is given in an <att>ident</att> attribute, and a <att>mode</att> attribute indicates the processing mode. There is an extra, mandatory, attribute, though: <att>type</att>, which indicates what kind of class is being defined. Possible values are:  
              <list type="gloss">
                <label>
                                    <val>atts</val>
                                </label> 
                <item>for the definition of an attribute class, which defines a number of common attributes</item>
                <label>
                                    <val>model</val>
                                </label> 
                <item>for the definition of a model class, which groups elements that can occur in the same context in a TEI document</item>
              </list>
            </p>
            <p>The content of this class specification looks familiar: an <gi>attList</gi> element groups all attribute declarations defined by the (attribute) class. Since the <ident type="class">att.naming</ident> class is being processed in <val>change</val> mode, it suffices to just redefine the <att>nymRef</att> attribute of this class: all other attributes of the class are being copied unmodified in our customisation. Hence, all it takes to remove <att>nymRef</att> from the <ident type="class">att.naming</ident> class, is an <gi>attDef</gi> element with <att>ident</att>=<val>nymRef</val>, and <att>mode</att>=<val>delete</val>.</p>
            <p>Actually, the deletion of the <att>nymRef</att> attribute from the <ident type="class">att.naming</ident> attribute class obsoletes our earlier deletion of the same attribute from the <gi>name</gi> attribute. However, it does no harm to have this deletion on both <gi>elementSpec</gi> and <gi>classSpec</gi> levels (they don’t contradict each other). The effect of this customisation can be seen by generating a TEI schema (via one of the schema output formats in the <q>Download</q> button at the top right of the Roma screen): this will only validate documents whose name-like elements don’t have a <att>nymRef</att> attribute.</p>
            <note>Be careful, though, when changing class definitions, as this can have wide ranging (and sometimes unforeseen) effects! Always make sure to study the relevant parts of the TEI Guidelines. And make sure you can trace back when anything unexpected happens: save early, save often!</note>
            <note type="summary">Attributes that are defined in an attribute class can be changed globally by changing the class specification in a <gi>classSpec</gi> element. This element must identify the name of the class in an <att>ident</att> attribute, and the type of class in a <att>type</att> attribute. As with other schema specification elements, the mode of operation should be stated in a <att>mode</att> attribute. Inside the <gi>classSpec</gi> declaration of an attribute class, all attribute definitions are grouped in an <gi>attList</gi> element, with an <gi>attDef</gi> declaration for each separate attribute.</note>
          </div>
        </div>
      </div>
            <div xml:id="extending">
        <head>Extending TEI</head>
        <p>So far, all modifications described were reductions of the general TEI model: either by selecting existing modules, elements, or attributes; or reducing the possible values of attributes. These kinds of modifications define true subsets of the TEI model, as long as they don’t remove any mandatory elements or attributes. In other words: TEI documents that are valid according to a schema generated from such reductive TEI customisations (like ours so far), will always be valid against the <ident type="file">tei_all</ident> customisation, which includes all TEI elements and attributes: see <ptr target="https://tei-c.org/release/xml/tei/custom/odd/tei_all.odd"/>.</p>
        <p>Not so for customisations that add things to the maximal TEI schema: these will produce TEI schemas that add new elements and/or attributes, or extend existing TEI definitions in such ways that they are not fully <soCalled>backward compatible</soCalled> with <soCalled>native TEI</soCalled>. In order to facilitate the understanding of TEI customisations, following terms are used:
          <list type="gloss">
            <label>TEI conformant customisation</label> 
            <item>a reductive customisation, that only restricts and constrains existing components of the TEI model (without removing mandatory components). TEI conformant customisations define schemas that are a subset of the maximal TEI schema. Everything documented in a TEI conformant customisation is documented in the TEI Guidelines.</item>
            <label>TEI extension</label> 
            <item>additive customisation, extending the TEI model with new components. TEI extensions produce schemas that aren’t subsets of the maximal TEI schema. TEI extensions define concepts that are not documented in the TEI Guidelines.</item>
          </list>
        </p>
        <p>It is very common to create TEI extensions: often, projects can have specific encoding needs for which no ideal TEI solution exists. In order to avoid <soCalled>tag abuse</soCalled>, where existing TEI elements or attributes are used in a way that more or less stretches their actual definition in the TEI Guidelines, projects can define their own means for encoding such phenomena in a TEI extension. These can be used internally in a project, or—if a proposed encoding solution has broader use—, it can eventually be incorporated in the TEI Guidelines, through the process of <ref target="https://github.com/TEIC/TEI/issues?q=label%3A%22Type%3A+FeatureRequest%22+">Feature Requests</ref> in the TEI source code repository.</p>
        <p>While TEI extensions are a very common way of customising TEI, in order to guarantee maximal interoperability for TEI documents, the TEI Guidelines strongly advise to formally separate elements and attributes added in a TEI extension from the <soCalled>native</soCalled> ones in the standard TEI schema. This can be done by defining them in another namespace than the TEI namespace (<ident type="ns">http://www.tei-c.org/ns/1.0</ident>). You can freely decide on this/these extension namespace/s; for the purpose of this tutorial, we’ll use a dedicated TBE namespace: <ident type="ns">http://teibyexample.org/ns/TBE</ident>. Notice that this namespace URI (Uniform Resource Identifier) doesn’t need to be officially registered, nor lead to an actual web resource. It can indeed be any URI, as long as it provides a unique identification for the non-TEI parts of your TEI customisation (so it must definitely differ from <ident type="ns">http://www.tei-c.org/ns/1.0</ident>). In the context of an encoding project, it is often a good idea to relate the namespace URI to the project’s URI in some way.</p>
        <div xml:id="addElements">
          <head>Adding Elements</head>
          <p>So far, our <ident type="file">TBEcustom</ident> customisation includes a generic <gi>name</gi> element (from the <ident type="module">core</ident> module) for identifying names in our <title level="m">Alice</title> encoding project. Apart from this generic element, TEI defines a set of more specialised elements for encoding names, in the <ident type="module">namesdates</ident> module. These elements add more semantic detail and leave more room for further (sub)typing. Let’s use Roma to have a look at what <ident type="module">namesdates</ident> has to offer:
            <list rend="ordered">
              <item>load the <ident type="file">TBEcustom</ident> customisation again in Roma if you haven’t done so already, and click the <q>Customize ODD</q> button,</item>
              <item>in the <q>Elements</q> tab, click the <q>by module</q> button at the top right of the Roma screen and scroll down to the elements of the <ident type="module">namesdates</ident> class.</item>
            </list>
            <figure xml:id="figure22">
              <graphic url="../../../images/tutorials/TBED08v00/romaNamesdates.png"/>
              <head type="legend">Grouping all elements of a TEI module in Roma.</head>
            </figure>
          </p>
          <p>In this long list of specific elements for names and dates, two look particularly interesting for our purposes: <gi>persName</gi> (as an alternative for <tag>name type="person"</tag>) and <gi>placeName</gi> (as an alternative for <tag>name type="place"</tag>). Let’s include them in our customisation: tick the boxes in Roma, and store the ODD file via the <q>Download</q> &gt; <q>Customization as ODD</q> button at the top right of the Roma screen. As you probably have expected, this will add following instruction to the ODD file:
          <egXML xmlns="http://www.tei-c.org/ns/Examples">
            <moduleRef key="namesdates" include="persName placeName"/>
          </egXML>
          </p>
          <p>If we generated a schema of the <ident type="file">TBEcustom</ident> customisation at this point, we would be able to rephrase the encoding of the different names in our <title level="m">Alice</title> fragment as follows:
            <egXML xmlns="http://www.tei-c.org/ns/Examples">
              <persName>Alice</persName>
              <name type="animal">Lobster</name>
              <name type="animal">Gryphon</name>
              <name type="animal">Mock Turtle</name>
            </egXML>
          </p>
          <p>Of course, this dual approach to name encoding, with the specialised <gi>persName</gi> and <gi>placeName</gi> elements for person and place names respectively, and the general <gi>name</gi> element with <att>type</att>=<val>animal</val> for animals, is undesirable. Therefore, we’ll extend our TEI customisation with a dedicated element for encoding animal names. As before, the remainder of this section first outlines the necessary steps in Roma, and next discusses the resulting ODD file.</p>
          <p>In Roma, new components (elements, classes, datatypes) can be added to a TEI customisation by clicking the <q>NEW</q> button at the bottom right of the screen:
            <figure xml:id="figure24">
              <graphic url="../../../images/tutorials/TBED08v00/romaNewMenu.png"/>
              <head type="legend">The <q>NEW</q> menu for adding new TEI components in Roma.</head>
            </figure>
          </p>
          <p>We’ll be creating a new element for animal names, so click the <q>Element</q> button of the pop-up menu. This opens a form with three fields. Let’s fill them:
            <list rend="bulleted">
              <item>
                                <q>Name</q>: the name of the element. By analogy to <gi>persName</gi> and <gi>placeName</gi>, let’s make this <gi scheme="TBE">animalName</gi>
                            </item>
              <item>
                                <q>Module</q>: the TEI module this new element will belong to. Since this is a specialised naming element, let’s select <ident type="module">namesdates</ident>.</item>
              <item>
                                <q>Namespace</q>: the namespace of the (non-TEI) element. As we’ve mentioned before, let’s make this <ident type="ns">http://teibyexample.org/ns/TBE</ident>
                            </item>
            </list>
            <figure xml:id="figure25">
              <graphic url="../../../images/tutorials/TBED08v00/romaNewElement-1.png"/>
              <head type="legend">
                                <q>Create new element</q> form in Roma.</head>
            </figure>
          </p>
          <p>After clicking the <q>Create</q> button, our new element is born! If an ODD file is generated at this point, it would be expanded with following instructions:
            <egXML xmlns="http://www.tei-c.org/ns/Examples">
              <elementSpec ident="animalName" ns="http://teibyexample.org/ns/TBE" mode="add" module="namesdates">
                <classes/>
                <attList/>
              </elementSpec>
            </egXML>
            This tells that our customisation defines a new element <gi scheme="TBE">animalName</gi> in the <ident type="ns">http://teibyexample.org/ns/TBE</ident> namespace, which will be made available in the <ident type="module">namesdates</ident> module.</p>
          <p>Yet, with empty <gi>classes</gi> and <gi>attList</gi> children, this element definition is still utterly useless. We have to define a number of essential properties:
            <list rend="bulleted">
              <item>the <hi rend="bold">attribute classes</hi> this new element belongs to</item>
              <item>the <hi rend="bold">model classes</hi> this new element belongs to</item>
              <item>the <hi rend="bold">content</hi> of this new element</item>
            </list>
          </p>
          <note type="reference">Exhaustive reference information for the TEI class system can be found in the TEI Guidelines, <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/REF-CLASSES-MODEL.html">Appendix A: Model Classes</ref> and <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/REF-CLASSES-ATTS.html">Appendix B: Attribute Classes</ref>. Datatypes definitions can be accessed from <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/REF-MACROS.html">Appendix E: Datatypes and Other Macros</ref>. For an in-depth prose description of the entire TEI infrastructure, see chapter <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/ST.html">1 The TEI Infrastructure</ref> of the TEI Guidelines.</note>
          <p>These are important decisions to make, which require conscious thought, as well as an understanding of the TEI class system. Fortunately, we can learn by example: since <!--
            
            
            Since we're modelling this new <gi scheme="TBE">animalName</gi> element on the existing <gi>persName</gi> and <gi>placeName</gi> elements, let's inspect how they are defined, with Roma.
            
            An explanation of all options on this page admittedly is too advanced for the purposes of this tutorial. As always, Roma offers a quite intuitive way to gain information by clicking the names of the different classes in the lists, which will provide you with their formal definition.</p>
          <p rend="crosslink">Exhaustive sources of reference information for the TEI class system can be found in the TEI Guidelines, <ref target="http://www.tei-c.org/release/doc/tei-p5-doc/en/html/REF-CLASSES-MODEL.html">Appendix A: Model Classes</ref> and <ref target="http://www.tei-c.org/release/doc/tei-p5-doc/en/html/REF-CLASSES-ATTS.html">Appendix B: Attribute Classes</ref>. Datatypes definitions can be accessed from <ref target="http://www.tei-c.org/release/doc/tei-p5-doc/en/html/REF-MACROS.html">Appendix E: Datatypes and Other Macros</ref>. For an in-depth prose description of the entire TEI infrastructure, see <ref target="http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ST.html">Chapter 1</ref> of the TEI Guidelines.</p>
          <p>It will be clear by now that adding elements requires conscious thought. Of course, the easiest design choice could be to define a new element as freely as possible, for example by declaring it as member of the <ident type="class">model.global</ident> model class of global elements that can occur anywhere, and declaring the broadest possible content definition. However, this would leave judgement on the most sensible use of this element completely to the encoder, which would lead to highly unpredictable encoding results and thus reduce the value of this encoding. Therefore, it is strongly advised to determine the contexts and contents of new elements as precise as possible, in order to ensure that they fit neatly in the TEI semantic model of a text. Consequently, defining new elements requires some insight in the TEI's internals (organisation of modules, model classes, attribute classes, content macros). However, for simple cases like ours we can follow a common sense approach. Since--> we are modelling a new element for animal names to the existing <gi>persName</gi> TEI element, we can use the declaration of the latter as a source of inspiration, or just plainly copy it. Let’s have a look at the definition page for <gi>persName</gi>:
            <list rend="ordered">
              <item>load the <ident type="file">TBEcustom</ident> customisation again in Roma if you haven’t done so already, and click the <q>Customize ODD</q> button,</item>
              <item>move to the <q>Elements</q> tab and scroll down to the definition of <gi>persName</gi>.</item>
            </list>
          </p>
          <p>The <q>Documentation</q> button shows the description for the <gi>persName</gi> element.
            <figure xml:id="figure26">
              <graphic url="../../../images/tutorials/TBED08v00/romaPersNameDocumentation.png"/>
              <head type="legend">Display of the documentation for the <gi>persName</gi> element in Roma.</head>
            </figure>
          </p>
          <p>The <q>Attributes</q> button shows us the attribute classes. If only the top-level attribute classes are considered, that aren’t defined inside other attribute classes, <!-- [RvdB] check this! -->(the others are being included automatically when their superclass is included), this list can be reduced to:
            <list rend="bulleted">
              <item>
                                <ident type="class">att.datable</ident>: groups attributes for normalisation of names or dates</item>
              <item>
                                <ident type="class">att.editLike</ident>: groups attributes for describing the nature of an encoded interpretation</item>
              <item>
                                <ident type="class">att.global</ident>: groups common attributes for all TEI elements</item>
              <item>
                                <ident type="class">att.personal</ident>: groups common attributes for names</item>
              <item>
                                <ident type="class">att.typed</ident>: groups attributes that allow (sub)classification of an element</item>
            </list>
            <figure xml:id="figure27">
              <graphic url="../../../images/tutorials/TBED08v00/romaPersNameAttributes.png"/>
              <head type="legend">Display of the attributes for the <gi>persName</gi> element in Roma.</head>
            </figure>
          </p>
          <p>The <q>Class Membership &amp; Content Model</q> button shows us the model classes of which <gi>persName</gi> is a member:
            <list rend="bulleted">
              <item>
                                <ident type="class">model.nameLike.agent</ident>: groups elements which contain names of individuals or corporate bodies</item>
              <item>
                                <ident type="class">model.persStateLike</ident>: groups elements describing changeable characteristics of a person which have a definite duration, for example occupation, residence, or name</item>
            </list>
            This means that <gi>persName</gi>, and all other members of these model classes, can occur wherever TEI elements specify their contents in terms of these classes.
            <figure xml:id="figure28">
              <graphic url="../../../images/tutorials/TBED08v00/romaPersNameClasses.png"/>
              <head type="legend">Display of the class membership for the <gi>persName</gi> element in Roma.</head>
            </figure>
          </p>
          <p>The content model of the <gi>persName</gi> element is represented graphically in Roma. It refers to the <ident type="macro">macro.phraseSeq</ident> macro, which represents a predefined sequence of character data and phrase-level elements. This means that <gi>persName</gi> can contain text intermixed with a whole range of sub-paragraph level elements (<gi>abbr</gi>, <gi>expan</gi>, <gi>name</gi>, <gi>persName</gi>, ...).</p>
          <p>Let’s copy these same declarations to our new element. Return to the <q>Elements</q> tab and click the <gi scheme="TBE">animalName</gi> element. 
            In the description box, we can enter a prose description for the <gi scheme="TBE">animalName</gi> element, for example: 
            <figure xml:id="figure29">
              <graphic url="../../../images/tutorials/TBED08v00/romaAnimalNameDocumentation.png"/>
              <head type="legend">Editing the documentation for the <gi scheme="TBE">animalName</gi> element in Roma.</head>
            </figure>
          </p>
          <p>Clicking the button labeled <q>
                            <gi scheme="TBE">animalName</gi> &lt;</q> on top left of the Roma screen, gets us back to the overview of the <gi scheme="TBE">animalName</gi> definition. A click on the <q>Attributes</q> button shows us that its attribute list is empty, as we saw already in the generated ODD file. In order to declare its membership of the 5 attribute classes we had identified in the definition of <gi>persName</gi>, start by clicking the plus sign in the <q>Attribute from Classes</q> row. Next, filter or scroll through the list of attribute classes, and click the plus sign next to the ones we want to add.
                <!-- [RvdB] follow up Roma bug https://github.com/TEIC/romajs/issues/101: apparently, model.persStateLike must be added manually (not present on persName either) -->
            <figure xml:id="figure30">
              <graphic url="../../../images/tutorials/TBED08v00/romaAnimalNameAttributes.png"/>
              <head type="legend">Adding the <gi scheme="TBE">animalName</gi> element to attribute classes in Roma.</head>
            </figure>
          </p>
          <p>Finally, return to the overview of the <gi scheme="TBE">animalName</gi> definition, and click the <q>Class Membership &amp; Content Model</q> button. In order to define how our <gi scheme="TBE">animalName</gi> element will behave, click the plus sign in the <q>Model Classes</q> row and select the 2 model classes we had identified by clicking the plus sign next to their name. 
            <figure xml:id="figure31">
              <graphic url="../../../images/tutorials/TBED08v00/romaAnimalNameModelClass.png"/>
              <head type="legend">Editing the class membership of the <gi scheme="TBE">animalName</gi> element in Roma.</head>
            </figure>
            Next, its content can be defined by first clicking one of the <q>Groups</q>, <q>References</q>, or <q>Nodes</q> blocks. This will produce an overlay menu, with a graphical indication of the different types of ODD constructs that can be used for selecting individual nodes or combining them in groups, or referencing one of the predefined TEI macros or classes. We’ll be inserting a reference to the <ident type="macro">macro.phraseSeq</ident> macro, so we’ll click the <q>References</q> block.
            <figure xml:id="figure32">
              <graphic url="../../../images/tutorials/TBED08v00/romaAnimalNameContentReferences.png"/>
              <head type="legend">Selecting a macro for the content model of the <gi scheme="TBE">animalName</gi> element in Roma.</head>
            </figure>
            We want to include a reference to a macro, so <q>macroRef</q> is the block we’ll want to add. This is done by <emph>dragging</emph> that block into the graphical editor screen of Roma. Next, clicking the arrow in that <q>macroRef</q> block calls a dialog window where the <ident type="macro">macro.phraseSeq</ident> macro can be selected via the plus sign next to it. Finally, make sure to drag this populated <q>macroRef</q> block <emph>into</emph> the empty space of the blue <q>content</q> block in the graphical editor (you’ll hear a little <soCalled>click</soCalled> sound if it succeeds):
            <figure xml:id="figure33">
              <graphic url="../../../images/tutorials/TBED08v00/romaAnimalNameContent.png"/>
              <head type="legend">Adding a macro to the content model of the <gi scheme="TBE">animalName</gi> element in Roma.</head>
            </figure>
          </p>
          <p>Now it’s time to inspect our ODD customization: store the ODD file via the <q>Download</q> &gt; <q>Customization as ODD</q> button at the top right of the Roma screen. The resulting ODD file looks as follows:
            <!-- [RvdB] Roma bug https://github.com/TEIC/romajs/issues/108: <content> is not created -->
            <figure xml:id="example5">
              <egXML xmlns="http://www.tei-c.org/ns/Examples">
                <schemaSpec ident="TBEcustom" start="TEI" prefix="tei_" targetLang="en" docLang="en">
                  <moduleRef key="figures" include="figDesc figure"/>
                  <moduleRef key="header" include="teiHeader fileDesc titleStmt publicationStmt sourceDesc"/>
                  <moduleRef key="core" include="p title emph lg l pb pubPlace publisher q quote name graphic"/>
                  <moduleRef key="textstructure" include="TEI text body titlePage docTitle docImprint docDate docAuthor byline div"/>
                  <moduleRef key="tei"/>
                  <moduleRef key="namesdates" include="persName placeName"/>
                  <elementSpec ident="name" mode="change">
                    <classes mode="change">
                      <memberOf key="att.datable" mode="delete"/>
                      <memberOf key="att.editLike" mode="delete"/>
                      <memberOf key="att.personal" mode="delete"/>
                    </classes>
                    <attList>
                      <attDef ident="subtype" mode="delete"/>
                      <attDef ident="nymRef" mode="delete"/>
                      <attDef ident="type" mode="change">
                        <valList type="closed" mode="change">
                          <valItem mode="add" ident="place">
                            <desc versionDate="2020-04-23" xml:lang="en">used for place names</desc>
                          </valItem>
                          <valItem mode="add" ident="person">
                            <desc versionDate="2020-04-23" xml:lang="en">used for person names</desc>
                          </valItem>
                          <valItem mode="add" ident="animal">
                            <desc versionDate="2020-04-23" xml:lang="en">used for animal names</desc>
                          </valItem>
                        </valList>
                      </attDef>
                      <attDef ident="cert" mode="delete"/>
                      <attDef ident="resp" mode="delete"/>
                      <attDef ident="source" mode="delete"/>
                    </attList>
                  </elementSpec>
                  <classSpec ident="att.naming" type="atts" mode="change">
                    <attList>
                      <attDef ident="nymRef" mode="delete"/>
                    </attList>
                  </classSpec>
                  <elementSpec ident="animalName" ns="http://teibyexample.org/ns/TBE" mode="add" module="namesdates">
                    <desc>contains a proper noun referring to an animal</desc>
                    <classes>
                      <memberOf key="att.datable"/>
                      <memberOf key="att.editLike"/>
                      <memberOf key="att.global"/>
                      <memberOf key="att.personal"/>
                      <memberOf key="att.typed"/>
                      <memberOf key="model.nameLike.agent"/>
                      <memberOf key="model.persStateLike"/>
                    </classes>
                    <content>
                      <macroRef key="macro.phraseSeq"/>
                    </content>
                  </elementSpec>
                </schemaSpec>
              </egXML>
              <head type="legend">ODD definition of a new (non-TEI) element (<ref target="../download/TBEcustom-5-animalName.odd">download</ref>).</head>
            </figure>
          </p>
          <p>We see how an extra <gi>elementSpec</gi> element is added to the ODD file, with the definition for our newly added <gi scheme="TBE">animalName</gi> element. Its name is given in the <att>ident</att> attribute, and <att>mode</att>=<val>add</val> indicates that this is a new element. The <att>ns</att> attribute contains the namespace URI we specified for this element.</p>
          <p>The description of our brand new <gi scheme="TBE">animalName</gi> element is provided in a <gi>desc</gi> element. Its class membership is declared in a <gi>classes</gi> element; each of the attribute and model classes we had selected, is listed in a separate <gi>memberOf</gi> element, whose <att>key</att> attribute identifies the relevant class. The content of the element is declared within a <gi>content</gi> element. Since we included the shortcut to the <ident type="macro">macro.phraseSeq</ident> macro, this is recorded in a <gi>macroRef</gi> element, whose <att>key</att> attribute identifies the macro.</p>
          <p>In order to give an impression of the convenience of macros, let’s see what this <ident type="macro">macro.phraseSeq</ident> macro resolves to when the ODD file is being processed:
            <egXML xmlns="http://www.tei-c.org/ns/Examples">
              <alternate minOccurs="0" maxOccurs="unbounded">
                <textNode/>
                <classRef key="model.gLike"/>
                <classRef key="model.qLike"/>
                <classRef key="model.phrase"/>
                <classRef key="model.global"/>
              </alternate>
            </egXML>
          </p>
          <p>We’ll not go into full details here, but you’ll be able to understand that this macro defines a sequence with zero (<att>minOccurs</att>=<val>0</val>) or more (<att>maxOccurs</att>=<val>unbounded</val>) combinations of plain text nodes (<tag type="empty">textNode</tag>), or the elements from the 4 model classes identified in <gi>classRef</gi>. For full coverage of the definition of content models: see section <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/TD.html#DEFCONTEI">22.5.1.1 Defining Content Models: TEI</ref> of the TEI Guidelines.</p>
          <note type="summary">Elements can be added to the existing TEI model by declaring them with an <gi>elementSpec</gi> element, with the value <val>add</val> for its <att>mode</att> attribute. The <att>ident</att> attribute must give the name of the element. Specific to added elements is the use of the <att>ns</att> attribute, whose value should provide a unique namespace URI for this element, different from the default TEI namespace (<ident type="ns">http://www.tei-c.org/ns/1.0</ident>). A prose description of the element can be given in a <gi>desc</gi> element. The structural behaviour and attributes of an element are defined in the <gi>classes</gi> element, containing <gi>memberOf</gi> declarations for each model or attribute class to which the element is added, identified with the <att>key</att> attribute. The content of the element is declared in the <gi>content</gi> element, containing either references to TEI macros, or hand-crafted sequences of nodes, elements, or element classes.</note>
        </div>
        <div xml:id="addAttributes">
          <head>Adding Attributes</head>
          <p>So far, we have customised our schema for the transcription of the <title level="m">Alice</title> text in such a way that we can distinguish between person, place, and animal names, either with specific <att>type</att> values of the generic <gi>name</gi> element (namely <val>person</val>, <val>place</val>, or <val>animal</val>), or by means of the TEI elements <gi>persName</gi> and <gi>placeName</gi>, and the non-TEI element <gi scheme="TBE">animalName</gi>. We fine-tuned all elements belonging to the <ident type="class">att.naming</ident> class by deleting the unneeded <att>nymRef</att> attribute from this class.</p>
          <p>For our specific analysis of <title level="m">Alice’s Adventures in Wonderland</title> we would like to experiment with a basic way of adding further information on the ontological status of the referents of the names in this fictitious story: it could be interesting to analyse the characters in terms of the kind of reality they exist in. A possible place for such information could be the <att>type</att> and <att>subtype</att> attributes of the <ident type="class">att.typed</ident> class. However, we would prefer a more specific label for this kind of information, and reserve these TEI attributes for possible different categorisations in the future. Therefore, we want to add a new attribute to our customisation. Similar to deleting attributes, adding new ones can happen on two levels:
            <list rend="bulleted">
              <item>element level: attributes may be added to an individual element, which will apply to this element only <lb/>→ This is accessible in Roma via the <q>Attributes</q> button in an element’s definition (via the <q>Elements</q> tab), where you can click the plus sign in the <q>Element attributes</q> row. In ODD, it will affect the attribute definition inside an <gi>elementSpec</gi> element.</item>
              <item>class level: attributes may be added to an attribute class, which will apply to all elements that are member of this class <lb/>→ This is accessible in Roma from the attribute class’s definition (via the <q>Attribute Classes</q> tab), where you can click the desired class name, click the <q>Attributes</q> button, and add additional attributes to the class. In ODD, it will affect the attribute definition inside a <gi>classSpec</gi> element.</item>
            </list>
          </p>
          <p>In this case, information on the ontological status of names’ referents not only applies to personal and place names, but also to our recently added animal names, names in general, and by extension all kinds of referring strings. This suggests the <ident type="class">att.naming</ident> attribute class as a good place to add this attribute.</p>
          <p>Let’s head over to Roma! Click the <q>Attribute Classes</q> tab for our TEI customisation, click the <ident type="class">att.naming</ident> class, and next hit the <q>Attributes</q> button. 
            <figure xml:id="figure34">
              <graphic url="../../../images/tutorials/TBED08v00/romaAttNaming.png"/>
              <head type="legend">Editing an attribute class for a TEI customisation in Roma.</head>
            </figure>
          </p>
          <p>This calls an overview of the attributes in this class (notice how the <att>nymRef</att> attribute still is excluded from our modification). Adding a new attribute to an attribute class can be done by clicking the plus sign in the <q>Class attributes</q> row. This produces a dialog window:
            <figure xml:id="figure35">
              <graphic url="../../../images/tutorials/TBED08v00/romaAttNamingNewAttribute.png"/>
              <head type="legend">Creating a new attribute in Roma.</head>
            </figure>
          </p>
          <p>This form asks us first for the name of this new attribute. Before we start defining the attribute, some thought is needed on its design. Following examples could illustrate different possibilities:
            <egXML xmlns="http://www.tei-c.org/ns/Examples">
              <persName fantastic="no">Alice</persName>
              <animalName realistic="0.5">Mock Turtle</animalName>
              <animalName ontStatus="mythological">Gryphon</animalName>
            </egXML>
          </p>
          <p>Attributes could be designed as binary choices taking some form of truth value, as categories taking some kind of degrees on a scale, as neutral labels taking a list of keywords, or many more. As we are in the early stages of the encoding project, and feel this ontological classification is still experimental, we can anticipate that categories are likely to pop up, merge, or be adapted along the way. Therefore, it makes most sense to design it as a general semantic field, allowing for an open-ended list of keywords. Considering these requirements, a sensible name for this attribute could be <soCalled>ontStatus</soCalled>. Let’s fill that name, and click the <q>Create</q> button. Now, this (empty) attribute definition is added to the list of <q>Class attributes</q>. In order to define this attribute, click the pencil icon next to its name. This will produce a page similar to the one we’ve seen before (when restricting the values of the <att>type</att> attribute for <gi>name</gi>). We’ll define this <att scheme="TBE">ontStatus</att> attribute as an <val>optional</val> attribute, by selecting this in the dropdown box next to <q>Usage</q>. In the <q>Description</q> field, we can provide a description, such as: 
            <eg>describes the ontological status of a name’s referent</eg>
            <figure xml:id="figure36">
              <graphic url="../../../images/tutorials/TBED08v00/romaOntStatusUsageDescription.png"/>
              <head type="legend">Editing documentation for a new attribute in Roma.</head>
            </figure>
          </p>
          <p>The other fields define the actual content of the attribute. For this example, suppose that an initial (experimental) categorisation for the ontological status of the people, places and animals in the <title level="m">Alice</title> story could look like this:
            <list rend="bulleted">
              <item>
                                <val>realistic</val>: the referent can / could occur in the extra-textual reality</item>
              <item>
                                <val>mythological</val>: the referent does not exist in real life, but belongs to a major mythology</item>
              <item>
                                <val>fantastic</val>: the referent belongs to an idiosyncratic fantasy universe</item>
            </list>
            However, it is prone to be extended with other categories, and would probably allow more categories to be applied simultaneously, for names referring to ambiguous creatures or places.</p>
          <p>This analysis obviously translates into a <q>semi-open</q> list: choose that option for the <q>Values</q> field. Attribute lists in ODD can have three types:
            <list type="gloss">
              <label>
                                <val>closed</val>
                            </label>
              <item>only the values defined in <gi>valList</gi> are permitted</item>
              <label>
                                <val>semi</val>
                            </label>
              <item>the values defined in <gi>valList</gi> are treated as suggested values, but others are allowed</item>
              <label>
                                <val>open</val>
                            </label>
              <item>any value is allowed (as long as it complies with the datatype); values in <gi>valList</gi> are treated as mere examples</item>
            </list>
          </p>
          <p>Suggested values can be entered in the text field of the <q>Values</q> field, and next pressing the plus sign next to the value. Let’s add the values mentioned above, as well as their description.
            <figure xml:id="figure37">
              <graphic url="../../../images/tutorials/TBED08v00/romaOntStatusValues.png"/>
              <head type="legend">Defining attribute values for a new attribute in Roma.</head>
            </figure>
          </p>
          <!-- [RvdB] follow up Roma bug https://github.com/TEIC/romajs/issues/109: currently, there's no way to specify @minOccurs and@maxOccurs for <datatype> in Roma -->
          <p>Finally, the datatype <!--and occurrence -->for the attribute’s value can be declared in the <q>Datatype</q> field. The TEI datatype <ident type="datatype">teidata.enumerated</ident>, which is explicitly designed to define a single word from a list of possibilities, seems the best fit. <!-- [RvdB] follow up Roma bug https://github.com/TEIC/romajs/issues/109: currently, there's no way to specify @minOccurs and@maxOccurs for <datatype> in Roma --><!--Although we defined the attribute as optional, we wouldn't like it to be empty when used on an element. Therefore, we can specify the value '1' after the <code>&gt;=</code> sign, specifying that at least one value is expected for this attribute. To allow for an unlimited combination of values from the list in the attribute, the value 'unbounded' can be selected after the <code>&lt;=</code> sign.-->
            <!-- [RvdB] follow up Roma bug https://github.com/TEIC/romajs/issues/109: currently, there's no way to specify @minOccurs and@maxOccurs for <datatype> in Roma -->
            <figure xml:id="figure38">
              <graphic url="../../../images/tutorials/TBED08v00/romaOntStatusDatatype.png"/>
              <head type="legend">Defining the datatype for a new attribute in Roma.</head>
            </figure>
          </p>
          <p>In the introduction to this section we stated that extending the TEI always leads to TEI document models that are broader than and hence possibly incompatible with the standard TEI model. For maximal separation of extension features from the standard TEI model, the TEI Guidelines therefore advice to define extensions in their own namespace. We already did so when adding new elements in the previous section. Let’s declare the same namespace <ident type="ns">http://teibyexample.org/ns/TBE</ident> in the <q>Namespace</q> field for our <att scheme="TBE">ontStatus</att> attribute:
            <figure xml:id="figure39">
              <graphic url="../../../images/tutorials/TBED08v00/romaOntStatusNamespace.png"/>
              <head type="legend">Defining a namespace for a new attribute in Roma.</head>
            </figure>
          </p>
          <p>To save these changes as an ODD file, click the <q>Download</q> &gt; <q>Customization as ODD</q> button at the top right of the Roma screen. We’ll notice how a defintition of the new <att scheme="TBE">ontStatus</att> attribute now is added to the <gi>classSpec</gi> declaration for the <ident type="class">att.naming</ident> attribute class:
            <!-- [RvdB] roma questions:
              -shouldn't ontStatus have mode="add"?
              -<datatype> was placed after <valList>, which is not allowed
              -->
            <!-- [RvdB] follow up Roma bug https://github.com/TEIC/romajs/issues/109: currently, there's no way to specify @minOccurs and@maxOccurs for <datatype> in Roma -->
            <figure xml:id="example6">
              <egXML xmlns="http://www.tei-c.org/ns/Examples">
                <classSpec ident="att.naming" type="atts" mode="change">
                  <attList>
                    <attDef ident="nymRef" mode="delete"/>
                    <attDef ident="ontStatus" mode="change" usage="opt" ns="http://teibyexample.org/ns/TBE">
                      <desc versionDate="2020-04-28" xml:lang="en">describes the ontological status of a name's referent</desc>
                      <datatype maxOccurs="unbounded">
                        <dataRef key="teidata.enumerated"/>
                      </datatype>
                      <valList mode="change" type="semi">
                        <valItem mode="add" ident="realistic">
                          <desc versionDate="2020-04-28" xml:lang="en">the referent can / could occur in the extra-textual reality</desc>
                        </valItem>
                        <valItem mode="add" ident="mythological">
                          <desc versionDate="2020-04-28" xml:lang="en">the referent does not exist in real life, but belongs to a major mythology</desc>
                        </valItem>
                        <valItem mode="add" ident="fantastic">
                          <desc versionDate="2020-04-28" xml:lang="en">the referent can / could occur in the extra-textual reality</desc>
                        </valItem>
                      </valList>
                    </attDef>
                  </attList>
                </classSpec>
              </egXML>
              <head type="legend">ODD definition of a new (non-TEI) attribute in an attribute class (<ref target="../download/TBEcustom-6-ontStatus.odd">download</ref>).</head>
            </figure>
          </p>
          <p>Since we added the <att scheme="TBE">ontStatus</att> attribute to the <ident type="class">att.naming</ident> attribute class, the corresponding <gi>attDef</gi> declaration is added to the list of attribute declarations of the corresponding <gi>classSpec</gi> element. As before, the class specification’s <att>mode</att> attribute is set to <val>change</val>, indicating that only the declarations present in this ODD file will update the existing TEI definitions. Inside the <gi>attList</gi> section, the <att>nymRef</att> attribute still is deleted, in accordance with our previous changes.</p>
          <p>However, there’s a new <gi>attDef</gi> element for our <att scheme="TBE">ontStatus</att> attribute (identified in the <att>ident</att> attribute), this time with the value <!-- [RvdB] check with Roma: output is "change" -->
                        <val>change</val> for its <att>mode</att> attribute (since there was no existing definition for this element, this has the same effect as <att>mode</att>=<val>add</val>). The <val>opt</val> value for the <att>usage</att> attribute indicates that the <att scheme="TBE">ontStatus</att> attribute will be optional in our customisation (required attributes would have <val>req</val>).</p>
          <p>Inside the attribute definition, the <gi>desc</gi> element contains the prose description of the attribute. <!-- [RvdB] no longer / not yet supported in Roma? --><!--The <gi>datatype</gi> section declares that the <att scheme="TBE">ontStatus</att> attribute should have minimally one value (<att>minOccurs</att> = <val>1</val>), while there's no limit on the frequency of its values (<att>maxOccurs</att> = <val>unbounded</val>).--> The datatype of the attribute is defined in <gi>datatype</gi>. By means of a <gi>dataRef</gi> element, it is referring to the existing TEI datatype definition <val>teidata.enumerated</val> (which is given as the value for its <att>key</att> attribute). This datatype basically restricts the possible values to strings consisting of words or a limited range of punctuation marks. <!-- [RvdB] Roma bug https://github.com/TEIC/romajs/issues/109: currently, there's no way to specify @minOccurs and@maxOccurs for <datatype> in Roma -->Combined with the declarations in <!--<att>minOccurs</att> and--> <att>maxOccurs</att>, this means that the <att scheme="TBE">ontStatus</att> attribute for <gi scheme="TBE">animalName</gi> can contain a white space separated list of word characters and some punctuation marks.</p>
          <note type="reference">This introductory tutorial doesn’t cover the advanced inner mechanisms of TEI in full; for more information you can read section <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/ST.html#DTYPES">1.4.2 Datatype Specifications</ref> of the TEI Guidelines, or the reference section in <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/REF-MACROS.html">Appendix E: Datatypes and Other Macros</ref>.</note>
          <p>Finally, the list of possible values is given inside <gi>valList</gi>, which is declared as a semi-open list. Each of these values is given in its own <gi>valItem</gi> element, with a description of that value in <gi>desc</gi>.</p>
          <note type="summary">Adding attributes is done within an <gi>attDef</gi> declaration inside the <gi>attList</gi> declaration, either in the definition of a single element (<gi>elementSpec</gi>) or an attribute class (<gi>classSpec</gi>). The addition is specified in the <!-- [RvdB] check with Roma: output is "change" -->
                        <val>add</val> value for the <att>mode</att> attribute of the attribute definition; the name of the attribute is given in the <att>ident</att> attribute. Additionally, <gi>attDef</gi> specifies the usage of the attribute within <att>usage</att> (<val>opt</val> for optional attributes, <val>req</val> for mandatory ones). In order to distinguish added attributes from standard TEI ones, it is highly recommended to declare a dedicated namespace in the <att>ns</att> attribute. An attribute definition typically contains a prose description in <gi>desc</gi>, an indication of the attribute’s datatype in <gi>datatype</gi> (referring to one or more of the predefined TEI datatypes), and a list of possible values in <gi>valList</gi>. Such lists may be specified as <val>closed</val>, <val>semi</val>, or <val>closed</val> in the <att>type</att> attribute. Each predefined attribute value is declared in the <att>ident</att> attribute of a separate <gi>valItem</gi> element.</note>
        </div>
        <div xml:id="otherExtensions">
          <head>Other Types of Extension</head>
          <p>Besides these common cases of TEI extension, involving the addition and deletion of elements and attributes, TEI can be extended in both more subtle and complex ways:
            <list rend="bulleted">
              <item>existing TEI elements can be renamed</item>
              <item>content models of existing TEI elements can be broadened</item>
              <item>datatypes and occurrence indicators of attributes can be broadened</item>
              <item>existing TEI elements can be redefined to different model classes</item>
            </list>
          </p>
          <p>Most of these types of customisations make use of the mechanisms covered in this tutorial. However, these kinds of modifications are considered advanced topics and are not treated in this introductory tutorial. For more information, you are referred to chapters <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/TD.html">22. Documentation Elements</ref> and <ref target="https://tei-c.org/release/doc/tei-p5-doc/en/html/USE.html">23. Using the TEI</ref> of the TEI Guidelines. <!-- [RvdB] obsolete--><!--, or one of these tutorials:
            <list>
              <item><ref target="http://www.tei-c.org/Guidelines/Customization/odds.xml">TEI: Getting Started with ODDs</ref></item>
              <item><ref target="http://www.tei-c.org/Guidelines/Customization/use_roma.xml">TEI: Using Roma</ref></item>
            </list>-->
          </p>
        </div>
      </div>
            <div xml:id="summary">
        <head>Summary</head>
        <p>This tutorial started from a sample encoding project: the encoding of Lewis Carroll’s novel <title level="m">Alice’s Adventures in Wonderland</title>. An analysis of this mini-project’s needs identified following encoding goals:
          <list rend="bulleted">
            <item>Encoding of structural elements: the document, title page, document title, chapters, headings, (sub)divisions, paragraphs, quotations, citations, page breaks, figures, line groups.</item>
            <item>Encoding of names for persons, places and animals in the story, with an additional requirement for an experimental analysis of the ontological status of their referents.</item>
          </list>
        </p>
        <p>Throughout this tutorial, a TEI customisation was developed step-by-step from which TEI schemas can be generated that fit these needs. After selection of relevant TEI modules and elements, selection of element-specific and attribute class attributes, and the addition of new elements and attributes, this is the final version of the ODD file for our <ident type="file">TBEcustom</ident> customisation:
          <egXML xmlns="http://www.tei-c.org/ns/Examples">
            <TEI>
              <teiHeader>
                <fileDesc>
                  <titleStmt>
                    <title>A TBE Customisation</title>
                    <author>The TBE crew</author>
                  </titleStmt>
                  <publicationStmt>
                    <publisher>TEI Consortium</publisher>
                    <availability status="free">
                      <licence target="http://creativecommons.org/licenses/by-sa/3.0/"> Distributed under a
                        Creative Commons Attribution-ShareAlike 3.0 Unported License </licence>
                      <licence target="http://www.opensource.org/licenses/BSD-2-Clause">
                        <p>Copyright 2013 TEI Consortium.</p>
                        <p>All rights reserved.</p>
                        <p>Redistribution and use in source and binary forms, with or without modification, are
                          permitted provided that the following conditions are met:</p>
                        <list>
                          <item>Redistributions of source code must retain the above copyright notice, this list
                            of conditions and the following disclaimer.</item>
                          <item>Redistributions in binary form must reproduce the above copyright notice, this
                            list of conditions and the following disclaimer in the documentation and/or other
                            materials provided with the distribution.</item>
                        </list>
                        <p>This software is provided by the copyright holders and contributors "as is" and any
                          express or implied warranties, including, but not limited to, the implied warranties
                          of merchantability and fitness for a particular purpose are disclaimed. In no event
                          shall the copyright holder or contributors be liable for any direct, indirect,
                          incidental, special, exemplary, or consequential damages (including, but not limited
                          to, procurement of substitute goods or services; loss of use, data, or profits; or
                          business interruption) however caused and on any theory of liability, whether in
                          contract, strict liability, or tort (including negligence or otherwise) arising in any
                          way out of the use of this software, even if advised of the possibility of such
                          damage.</p>
                      </licence>
                      <p>TEI material can be licensed differently depending on the use you intend to make of it.
                        Hence it is made available under both the CC+BY and BSD-2 licences. The CC+BY licence is
                        generally appropriate for usages which treat TEI content as data or documentation. The
                        BSD-2 licence is generally appropriate for usage of TEI content in a software
                        environment. For further information or clarification, please contact the <ref target="mailto:info@tei-c.org">TEI Consortium</ref>. </p>
                    </availability>
                  </publicationStmt>
                  <sourceDesc>
                    <p>Created from scratch by James Cummings, but looking at previous tei_minimal and tei_bare
                      exemplars by SPQR and LR.</p>
                  </sourceDesc>
                </fileDesc>
              </teiHeader>
              <text>
                <body>
                  <head>A Minimal TEI Customization</head>
                  
                  <p>This TEI ODD defines a TEI customization that is as minimal as possible and the schema
                    generated from it will validate a document that is minimally valid against the TEI scheme.
                    It includes only the ten required elements: <list rend="numbered">
                      <item>
                                                <gi>teiHeader</gi> from the header module to store required metadata</item>
                      <item>
                                                <gi>fileDesc</gi> from the header module to record information about this
                        file</item>
                      <item>
                                                <gi>titleStmt</gi> from the header module to record information about the
                        title</item>
                      <item>
                                                <gi>publicationStmt</gi> from the header module to detail how it is published</item>
                      <item>
                                                <gi>sourceDesc</gi> from the header module to record where it is from</item>
                      <item>
                                                <gi>p</gi> from the core module for use in the header and the body</item>
                      <item>
                                                <gi>title</gi> from the core module for use in the titleStmt</item>
                      <item>
                                                <gi>TEI</gi> from the textstructure module because what is a TEI file without
                        that?</item>
                      <item>
                                                <gi>text</gi> from the textstructure module to hold some text</item>
                      <item>
                                                <gi>body</gi> from the textstructure module as a place to put that text</item>
                    </list>
                  </p>
                  <schemaSpec ident="TBEcustom" start="TEI" prefix="tei_" targetLang="en" docLang="en">
                    <moduleRef key="figures" include="figDesc figure"/>
                    <moduleRef key="header" include="teiHeader fileDesc titleStmt publicationStmt sourceDesc"/>
                    <moduleRef key="core" include="p title emph lg l pb pubPlace publisher q quote name graphic"/>
                    <moduleRef key="textstructure" include="TEI text body titlePage docTitle docImprint docDate docAuthor byline div"/>
                    <moduleRef key="tei"/>
                    <moduleRef key="namesdates" include="persName placeName"/>
                    <elementSpec ident="name" mode="change">
                      <attList>
                        <attDef ident="type" mode="change">
                          <valList type="closed" mode="change">
                            <valItem mode="add" ident="place">
                              <desc versionDate="2020-04-23" xml:lang="en">used for place names</desc>
                            </valItem>
                            <valItem mode="add" ident="person">
                              <desc versionDate="2020-04-23" xml:lang="en">used for person names</desc>
                            </valItem>
                            <valItem mode="add" ident="animal">
                              <desc versionDate="2020-04-23" xml:lang="en">used for animal names</desc>
                            </valItem>
                          </valList>
                        </attDef>
                        <attDef ident="subtype" mode="delete"/>
                        <attDef ident="calendar" mode="delete"/>
                        <attDef ident="cert" mode="delete"/>
                        <attDef ident="evidence" mode="delete"/>
                        <attDef ident="from" mode="delete"/>
                        <attDef ident="full" mode="delete"/>
                        <attDef ident="instant" mode="delete"/>
                        <attDef ident="notAfter" mode="delete"/>
                        <attDef ident="notBefore" mode="delete"/>
                        <attDef ident="period" mode="delete"/>
                        <attDef ident="resp" mode="delete"/>
                        <attDef ident="sort" mode="delete"/>
                        <attDef ident="source" mode="delete"/>
                        <attDef ident="to" mode="delete"/>
                        <attDef ident="when" mode="delete"/>
                        <attDef ident="nymRef" mode="delete"/>
                        <attDef ident="role" mode="delete"/>
                      </attList>
                    </elementSpec>
                    <classSpec ident="att.naming" type="atts" mode="change">
                      <attList>
                        <attDef ident="nymRef" mode="delete"/>
                        <attDef ident="ontStatus" mode="change" usage="opt" ns="http://teibyexample.org/ns/TBE">
                          <desc versionDate="2020-04-28" xml:lang="en">describes the ontological status of a name's referent</desc>
                          <datatype>
                            <dataRef key="teidata.enumerated"/>
                          </datatype>
                          <valList mode="change">
                            <valItem mode="add" ident="realistic">
                              <desc versionDate="2020-04-28" xml:lang="en">the referent can / could occur in the extra-textual reality</desc>
                            </valItem>
                            <valItem mode="add" ident="mythological">
                              <desc versionDate="2020-04-28" xml:lang="en">the referent does not exist in real life, but belongs to a major mythology</desc>
                            </valItem>
                            <valItem mode="add" ident="fantastic">
                              <desc versionDate="2020-04-28" xml:lang="en">the referent can / could occur in the extra-textual reality</desc>
                            </valItem>
                          </valList>
                        </attDef>
                      </attList>
                    </classSpec>
                    <elementSpec ident="animalName" ns="http://teibyexample.org/ns/TBE" mode="add" module="namesdates">
                      <desc>contains a proper noun referring to an animal</desc>
                      <classes>
                        <memberOf key="att.global"/>
                        <memberOf key="model.persStateLike"/>
                        <memberOf key="model.nameLike.agent"/>
                        <memberOf key="att.datable"/>
                        <memberOf key="att.editLike"/>
                        <memberOf key="att.personal"/>
                        <memberOf key="att.typed"/>
                      </classes>
                      <content>
                        <macroRef key="macro.phraseSeq"/>
                      </content>
                    </elementSpec>
                  </schemaSpec>
                </body>
              </text>
            </TEI>
          </egXML>                    
        </p>
        <p>This ODD file allows the generation of a TEI schema for the encoding of the document. The following example illustrates how the encoding could make use of the features defined in the ODD file (notice how the <ident type="ns">http://teibyexample.org/ns/TBE</ident> namespace is used to distinguish the added elements and attributes, and bound to the namespace prefix <soCalled>TBE</soCalled>):
          <egXML xmlns="http://www.tei-c.org/ns/Examples">
            <TEI xmlns:tbe="http://teibyexample.org/ns/TBE">
              <teiHeader>
                <!-- ... -->
              </teiHeader>
              <text>
                <body>
                  <!-- ... -->
                  <div type="chapter">
                    <!-- ... -->
                    <pb n="157"/>
                    <figure>
                      <graphic url="images/lobster.jpg"/>
                      <figDesc>The lobster sugaring its hair.</figDesc>
                    </figure>
                    <p>
                      <q who="#alice">"How the creatures order one about, and make one repeat lessons!"</q> thought <persName tbe:ontStatus="realistic">Alice</persName>, <q who="#alice">"I might just as well be at school at once."</q> However, she got up, and began to repeat it, but her head was so full of the <title type="song">
                                                <tbe:animalName tbe:ontStatus="realistic">Lobster</tbe:animalName>-Quadrille</title>, that she hardly knew what she was saying, and the words came very queer indeed:—</p>
                    <q rend="blockquote" who="#alice">
                      <lg>
                        <l>"'Tis the voice of the <tbe:animalName tbe:ontStatus="realistic">lobster</tbe:animalName>; I heard him declare,</l>
                        <l>
                                                    <q who="#lobster">'You have baked me too brown, I must sugar my hair.'</q>
                                                </l>
                        <l>As a duck with its eyelids, so he with his nose</l>
                        <l>Trims his belt and his buttons, and turns out his toes."</l>
                      </lg>
                    </q>
                    <p>
                      <q who="#gryphon">"That's different from what <emph>I</emph> used to say when I was a child,"</q> said the <tbe:animalName tbe:ontStatus="mythological">Gryphon</tbe:animalName>.</p>
                    <pb n="158"/>
                    <p>
                      <q who="#mockTurtle">"Well, I never heard it before,"</q> said the <tbe:animalName tbe:ontStatus="fantastic">Mock Turtle</tbe:animalName>; <q who="#mockTurtle">"but it sounds uncommon nonsense."</q>
                                        </p>
                    <p>
                                            <persName tbe:ontStatus="realistic">Alice</persName> said nothing; she had sat down with her face in her hands, wondering if anything would <emph>ever</emph> happen in a natural way again.</p>
                    <p>
                                            <q who="#mockTurtle">"I should like to have it explained,"</q> said the <tbe:animalName tbe:ontStatus="fantastic">Mock Turtle</tbe:animalName>.</p>
                    <p>
                                            <q who="#gryphon">"She can't explain it,"</q> said the <tbe:animalName tbe:ontStatus="mythological">Gryphon</tbe:animalName> hastily. <q who="#gryphon">"Go on with the next verse."</q>
                                        </p>
                    <p>
                                            <q who="#mockTurtle">"But about his toes?"</q> the <tbe:animalName tbe:ontStatus="fantastic">Mock Turtle</tbe:animalName> persisted. <q who="#mockTurtle">"How <emph>could</emph> he turn them out with his nose, you know?"</q>
                                        </p>
                    <p>
                                            <q who="#aliceI">"It's the first position in dancing."</q> <persName tbe:ontStatus="realistic">Alice</persName> said; but she was dreadfully puzzled by the whole thing, and longed to change the subject.</p>
                    <p>
                                            <q who="#gryphon">"Go on with the next verse,"</q> the <tbe:animalName tbe:ontStatus="mythological">Gryphon</tbe:animalName> repeated impatiently: <q who="#gryphon">"it begins <quote>'I passed by his garden.'</quote>"</q>
                                        </p>
                    <p>
                                            <persName tbe:ontStatus="realistic">Alice</persName> did not dare to disobey, though she felt sure it would all come wrong, and she went on in a trembling voice:—</p>
                    <pb n="159"/>
                    <!-- ... -->
                  </div>
                  <!-- ... -->
                </body>
              </text>
            </TEI>                        
          </egXML>
        </p>
      </div>
            <div xml:id="ODD.further">
        <head>What’s Next?</head>
        <p>You have reached the end of this tutorial module covering TEI customisations and Roma. You can now either 
          <list rend="bulleted">
            <item>proceed with <ref target="../tutorials/">other TEI by Example modules</ref>
                        </item>
            <item>have a look at the <ref target="../examples/TBED08v00.htm">examples section</ref> for the Customising TEI, ODD, Roma module.</item>
            <item>take an interactive test. This comes in the form of a set of multiple choice questions, each providing a number of possible answers. Throughout the quiz, your score is recorded and feedback is offered about right <hi rend="italic">and</hi> wrong choices. Can you score 100%? Test it <ref target="../tests/TBED08v00.htm">here</ref>!</item>
          </list>
        </p>
      </div>
        </body>
  </text>
  <!-- 
      $Date$
      $Id$  -->
</TEI>