🐕ODD Chain Tutorial

A tutorial for learning how to customize schemas using the TEI ODD "chain" feature.

What is an ODD Chain

There are two approaches to ODD chains:

1. Inheritance (Vertical Chain)

Uses the source attribute to reference a parent ODD and inherit customizations.

TEI_all → Base ODD → Derived ODD → Further derivations...

2. Combination (Horizontal Chain)

Uses specGrp and specGrpRef to combine multiple ODDs.

Header ODD ──┬──→ Combined schema
Body ODD ────┘

Directory Structure

tutorials/
├── 01-inheritance/     # Inheritance examples
│   ├── base.odd        # Base ODD
│   └── derived.odd     # Derived ODD inheriting from base.odd
├── 02-chain/           # Combination examples
│   ├── header-specs.odd    # Header-related customizations
│   ├── text-specs.odd      # Body text-related customizations
│   ├── main.odd            # Main ODD for integration
│   └── merge-specs.xsl     # XSLT for expanding specGrpRef
├── output/             # Generated files
│   ├── base.rng            # Generated from 01 base ODD
│   ├── base.html           # HTML documentation for the above
│   ├── derived.rng         # Generated from 01 derived ODD
│   ├── derived.html        # HTML documentation for the above
│   ├── combined.rng        # Generated from 02 combined ODD
│   ├── combined.html       # HTML documentation for the above
│   └── intermediate/       # Intermediate files
│       ├── base.compiled.odd
│       ├── derived.compiled.odd
│       ├── combined.merged.odd
│       └── combined.compiled.odd
├── build.sh            # Build script
└── README.md           # This file

Prerequisites

• Saxon (XSLT 2.0 processor)
• TEI Stylesheets (installed at ../scripts/Stylesheets)

Build Instructions

cd tutorials
./build.sh

Generated Files

Source ODD	RNG	HTML
01-inheritance/base.odd	output/base.rng	output/base.html
01-inheritance/derived.odd	output/derived.rng	output/derived.html
02-chain/main.odd (after combination)	output/combined.rng	output/combined.html

File Descriptions

01-inheritance (Inheritance)

base.odd

The base ODD containing minimal modules and basic customizations.

schemaSpec ident="baseSchema" start="TEI" source="tei:4.7.0">
  moduleRef key="tei"/>
  moduleRef key="header"/>
  moduleRef key="core"/>
  moduleRef key="textstructure"/>

schemaSpec>

derived.odd

A derived ODD that inherits from the TEI standard and adds further customizations.

schemaSpec ident="derivedSchema" start="TEI" source="tei:4.7.0">

  elementSpec ident="note" mode="delete"/>


  elementSpec ident="p" mode="change">
    attList>
      attDef ident="rend" mode="change">
        valList type="closed">
          valItem ident="indent"/>
          valItem ident="center"/>
        valList>
      attDef>
    attList>
  elementSpec>
schemaSpec>

02-chain (Combination)

header-specs.odd

Defines header-related customizations using specGrp.

specGrp xml:id="header-customizations">
  elementSpec ident="titleStmt" mode="change">

  elementSpec>
specGrp>

text-specs.odd

Defines body text-related customizations using specGrp.

specGrp xml:id="text-customizations">
  elementSpec ident="p" mode="change">

  elementSpec>
specGrp>

main.odd

Combines multiple ODDs using specGrpRef references.

schemaSpec ident="combinedSchema" start="TEI" source="tei:4.7.0">
  moduleRef key="tei"/>
  moduleRef key="header"/>
  moduleRef key="core"/>
  moduleRef key="textstructure"/>


  specGrpRef target="header-specs.odd#header-customizations"/>
  specGrpRef target="text-specs.odd#text-customizations"/>
schemaSpec>

Processing Flow

Inheritance

base.odd
    ↓ odd2odd.xsl (compile)
intermediate/base.compiled.odd
    ├─→ odd2relax.xsl → base.rng
    └─→ odd2html.xsl  → base.html

derived.odd (source="tei:4.7.0")
    ↓ odd2odd.xsl (compile + resolve inheritance)
intermediate/derived.compiled.odd
    ├─→ odd2relax.xsl → derived.rng
    └─→ odd2html.xsl  → derived.html

Combination

header-specs.odd ─┐
                  │ merge-specs.xsl
text-specs.odd ───┤ (expand specGrpRef)
                  │
main.odd ─────────┘
    ↓
intermediate/combined.merged.odd
    ↓ odd2odd.xsl
intermediate/combined.compiled.odd
    ├─→ odd2relax.xsl → combined.rng
    └─→ odd2html.xsl  → combined.html

XSLT Used

XSLT	Location	Role
odd2odd.xsl	Stylesheets/odds/	ODD compilation (module expansion, inheritance resolution)
odd2relax.xsl	Stylesheets/odds/	RelaxNG schema generation
odd2html.xsl	Stylesheets/odds/	HTML documentation generation
merge-specs.xsl	02-chain/	specGrpRef expansion (custom)

References

• TEI Guidelines - Using Roma
• TEI ODD Customization
• TEI Stylesheets