Feedback on the Best Practices for TEI in Libraries ODD Documentation and Schemas
Feedback is no longer being collected here. Please see Future changes to Best Practices for TEI in Libraries.
Contents
Overview
The Best Practices for TEI in Libraries are now captured in a series of ODD files that generate both the prose documentation for encoding levels 1-5 and the schemas for encoding levels 1-4 that conform to TEI P5. Before we can officially "release" the Best Practices, we need to undergo a round of systematic testing to make sure nothing was lost in translation from our original TEI wiki documentation to the ODDs. We have established a two-pronged testing approach:
- Review and compare the prose documentation with the original wiki documentation to make sure nothing is amiss.
- Test the RelaxNG and Schematron schemas against content from TEI P5 projects to see whether the expressed constraints match the prose documentation and whether they unduly constrain content that a project thinks conforms to a particular encoding level.
We are soliciting volunteers to help with both endeavors. We especially welcome "fresh eyes" to help us with testing and we would especially like to see multiple people testing the same levels to make sure we receive comprehensive feedback if possible.
Our goal is to have testing complete by May 1, 2011
Prong 1: Review/Compare Prose Documentation
In reviewing and comparing the prose documentation, we ask that you pay special attention to the following:
- Missing or altered prose
- Missing or altered markup examples
- Additional prose or examples not found in the original wiki documentation
We are still wotking on styling/rendering/display issues in the HTML output. However, please do feel free to comment on rendering issues you may encounter. This will make sure we don't take any of it for granted.
Links to Review/Compare Prose Documentation
- Prose Documentation for Level 1
- Prose Documentation for Level 2
- Prose Documentation for Level 3
- Prose Documentation for Level 4
- Prose Documentation for Level 5
- Prose Documentation for Front and Back Matter (e.g., Introduction, Appendices, etc.)
- ODD documentation (sections 1-4 (except 4.2), 5-7)
- Wiki documentation (sections 1-5, 7-10)
Suggested Steps to Follow for Review
- Select a section of the documentation to review and sign-up (see below)
- Read the ODD-generated documentation for the selected section
- Peruse corresponding section in the wiki version of the documentation
- Document any differences or problems encountered on wiki pages linked in table below
Sign-Up for Review of Prose Documentation
Note: We encourage more than one reviewer per level.
| Level | Name | Contact Email | Feedback |
|---|---|---|---|
| Level 1 | Melanie Schlosser, Name 2, etc. | melanie.schlosser@gmail.com, Email 2, etc. | Level 1 Prose Documentation Feedback |
| Level 2 | Melanie Schlosser, Name 2, etc. | melanie.schlosser@gmail.com, Email 2, etc. | Level 2 Prose Documentation Feedback |
| Level 3 | Kevin Hawkins, Melanie Schlosser, etc. | Email 1, melanie.schlosser@gmail.com, etc. | Level 3 Prose Documentation Feedback |
| Level 4 | Kevin Hawkins, Name 2, etc. | Email 1, Email 2, etc. | Level 4 Prose Documentation Feedback |
| Level 5 | Name 1, Name 2, etc. | Email 1, Email 2, etc. | Level 5 Prose Documentation Feedback |
| Front Matter (e.g., Introduction) | Melanie Schlosser, Name 2, etc. | melanieschlosser@gmail.com, Email 2, etc. | Front Matter Documentation Feedback |
| Back Matter (e.g., Appendices) | Melanie Schlosser, Name 2, etc. | melanieschlosser@gmail.com, Email 2, etc. | Back Matter Documentation Feedback |
Prong 2: Test Levels 1-4 Schemas and Schematron
In testing the schemas and schematron for levels 1-4, we ask that you pay special attention to the following:
- Aspects that do not validate and why (perhaps your local project isn't conformant or we overlooked a markup practice that should be reflected in the "Best Practices")
We expect schema and schematron validation to be more experimental. We are more concerned with validation errors than a perfectly valid document, but please do tell us if your project happens to validate.
Please note that these Best Practices and schemas conform to TEI version P5. Please make sure you are testing the right version of the TEI. Thanks!
Download Schemas (RelaxNG) and Schematron
You have the option of downloading the compact (.rnc) or regular (.rng) RelaxNG schema for each of the levels. Testing both is not required, but please do let us know which schema you used.
- Level 1
- Compact Syntax Closed Schema for Level 1 (.rnc)
- XML Syntax Closed Schema for Level 1 (.rng)
- ISO Schematron Level 1 (.isosch)
- Level 2
- Compact Syntax Closed Schema for Level 2 (.rnc)
- XML Syntax Closed Schema for Level 2 (.rng)
- ISO Schematron Level 2 (.isosch)
- Level 3
- Compact Syntax Closed Schema for Level 3 (.rnc)
- XML Syntax Closed Schema for Level 3 (.rng)
- ISO Schematron Level 3 (.isosch)
- Level 4
- Compact Syntax Closed Schema for Level 4 (.rnc)
- XML Syntax Closed Schema for Level 4 (.rng)
- ISO Schematron Level 4 (.isosch)
Schema and Schematron Setup
Since TEI workflows and XML editors vary, we will not provide specific instructions on how to set up schema validation. We assume you will plug in the Best Practices schema into your own workflow/software environments.
We assume the same is true for schematron validation, but will provide a scenario if you use the Oxygen XML editor:
- Make sure the TEI/XML file or files you are checking are open in Oxygen (run the schematron on one file or against multiple files assigned to a project)
- Click on the little downward-pointing error on the Validate icon (the red checkmark)
- Select "Validate with ..."
- Select the "Schematron Schema" tab and browse for the Best Practices schematron (.isosch) file you downloaded for testing
- Select "OK"
The schematron will run against your TEI file and generate a list of errors or warnings in the "Errors" pane of the Oxygen editor (similar to errors generated when validating against the schema).
Sign-Up for Schema/Schematron Testing
Note: We encourage more than one tester per level.
| Level | Name | Contact Email | P5 Project Tested (include URL is possible) | Specify Schema Tested (e.g., rnc or rng) | Schematron Tested (e.g., Yes or No) | Feedback |
|---|---|---|---|---|---|---|
| applies to all levels (included in main-driver.odd) | Name 1, Name 2, etc. | Email 1, Email 2, etc. | Project 1, Project 2, etc. | Schema(s) 1, Schema(s) 2, etc. | Yes/No 1, Yes/No 2, etc. | main-driver Schema and Schematron Feedback |
| Level 1 | Name 1, Name 2, etc. | Email 1, Email 2, etc. | Project 1, Project 2, etc. | Schema(s) 1, Schema(s) 2, etc. | Yes/No 1, Yes/No 2, etc. | Level 1 Schema and Schematron Feedback |
| Level 2 | Name 1, Name 2, etc. | Email 1, Email 2, etc. | Project 1, Project 2, etc. | Schema(s) 1, Schema(s) 2, etc. | Yes/No 1, Yes/No 2, etc. | Level 2 Schema and Schematron Feedback |
| Level 3 | Name 1, Name 2, etc. | Email 1, Email 2, etc. | Project 1, Project 2, etc. | Schema(s) 1, Schema(s) 2, etc. | Yes/No 1, Yes/No 2, etc. | Level 3 Schema and Schematron Feedback |
| Level 4 | Michelle Dalmau, Name 2, etc. | mdalmau@indiana.edu, Email 2, etc. | VWWP, Project 2, etc. | rng, Schema(s) 2, etc. | Yes, Yes/No 2, etc. | Level 4 Schema and Schematron Feedback |
Thank You!
Thanks in advance for your willingness to review both the prose documentation and the schemas/schematron for the Best Practices for TEI in Libraries. This undertaking has been a work in progress for a few years and we look forward to officially releasing it to the public.
