ODD specification and documentation of the Tido MEI Customization.

git clone https://github.com/tido/mei-customization.git

If you run node and would like to build the schema and/or the documentation or run the tests:

cd mei-customization
npm install

Use the schema files in build/schema/ to validate MEI documents. Refer to the html guidelines in build/guidelines folder for documentation of the customization format.

The Tido ODD customization file is located at src/tido.xml. In addition to the schema specifications, this file contains examples of valid and invalid fragments.

In order to build the schema and guidelines you will need

• a Java Development Kit (JDK)
• ANT

The Tido MEI Customization project contains copies of https://github.com/music-encoding/music-encoding and https://github.com/TEIC/Stylesheets in the vendor folder. In case these dependencies need to be updated, run ./update-git-dependencies.sh and commit the updated project.

In order to build the schema:

ant -lib vendor/stylesheets/lib schema

The output schema will be placed in build/schema

To build the HTML guidelines:

ant -lib vendor/stylesheets/lib html-guidelines

The output of this will be placed in build/guidelines

In addition to providing documentation, the provided examples also serve validation test for the schema. A node test environment based on the odd-tests and mei-validation packages is included in order to make sure that provided examples (or counter-examples) are indeed validated (or invalidated) by the compiled schema.

npm test

In Node you can also run the build scripts through npm scripts:

npm run schema
npm run html-guidelines

And if you want to do all the above at once, that is build the schema, build the documentation and run the tests:

npm run refresh

When modifying the schema it is expected that for each feature there are valid and invalid examples provided. Each of these examples then serve as a test case for the test environment to check whether the examples actually conform to the compiled schemata.

Typically, test cases are appended to <elementSpec>, <classSpec> etc. elements they refer to (as a child of <exemplum>), but <egXML> may appear anywhere in the ODD, for example in the initial prose descriptions of the features. If the content of <egXML> is supposed to be valid against the Tido schema, it will have an attribute @valid="true", if it is supposed to be invalid, it will have @valid="false". Incomplete examples, which are in fact invalid but could be made valid by providing additional attributes are marked with @valid="feasible". In that case, its content will be skipped when running the validation tests.

The test environment uses the preact library to construct complete MEI documents from the MEI fragments in <egXML>. The test/jsx folder contains templates that help to contextualise the provided examples. In order to assign a template to a fragment, the <egXML> elements link to <rendition> declarations in the <teiHeader> which point to the Preact template files in concern.

Here's a full example of a class specification with a single test case:

<classSpec ident="att.startendid" module="MEI.shared" type="atts" mode="change">
  <attList>
    <attDef ident="endid" usage="opt" mode="change">
      <datatype>
        <rng:ref name="data.URI.local"/>
      </datatype>
    </attDef>
  </attList>
  <exemplum>
    <p>A valid <gi>pedal</gi> element with local URI references in
      <att>startid</att> and <att>endid</att></p>
    <egXML xmlns="http://www.tei-c.org/ns/Examples" valid="true" rendition="#afterStaff">
      <pedal dir="down" staff="1" layer="1" startid="#n01" endid="#n02"/>
    </egXML>
  </exemplum>
</classSpec>