Talk:Best Practices for TEI in Libraries

The following are things to do to the BP before making an official "release". There is a separate list of Future changes to Best Practices for TEI in Libraries.

Review ODDs (HTML documentation and schemas derived from them)
The latest version of the Best Practices for TEI in Libraries document, now derived from source TEI ODD files, is available for review. I have moved all of the content from the wiki page to TEI source files, but there is still a lot of work to be done. Besides just plain copy editing and review of the document and thorough testing of the schemas, the generic TEI stylesheets are not really up to the task of making the documents easily readable. The source is maintained on GitHub. Anyone (in the world) can get a copy of the source files from there at any time. Any one of you that wishes to have write access needs to send Syd your GitHub user name and he’ll add you to the “contributors” list.

For those of you who are not interested in wrestling with command-line `roma`, there is a snapshot of the HTML documentation and schemas (both closed in RELAX NG and open in ISO Schematron) on the web. There is an easy-to-use list of the most important files and the entire list of files. There is a lot of work to be done on these documents. Even after we find & fix errors, we need lots of examples for the tagdocs (examples in the element definitions to override the default ones from P5, many of which aren't valid according to the BP because they contain extra elements, are missing required attributes, etc.).

The process of gathering feedback was formalized and carried out in Spring 2011.

Edits made and to be made based on feedback
Kevin Hawkins and Syd Bauman met on 2011-07-05 to go through the feedback and make changes to the ODDs. Kevin made comments in the feedback changes addressing each point raised. Most errors were fixed, and are also a few things reported which were by design in the BP.

The following issues were reported during the feedback process but remain to be resolved in the ODDs:


 * Syd will post to TEI-L asking how to distinguish "his-tory" and "run-on" when they break across lines. Both would take break="no", but how to allow for searching of "history" and "run-on"?
 * Syd will check whether Schematron rule preventing use of @rend and @rendition within header is working. If so, correct note at Level 3 Schema and Schematron Feedback.

In addition, we need to resolve the following in the stylesheet(s) for creating HTML documentation:


 * Handling of lists within cells: should just run each item together, separated only by " * ".
 * Tables should have borders on cells (or some clear path for indicating in ODD document that you want borders).
 * Omit exemplars from output.

Furthermore, we discovered that Syd had not kept the ODDs in sync with |changes made between 2010-12-19 and when the wiki was frozen. He is working through that list of changes to make.

Syd will write down the command-line code needed in order to generate files from the ODDs and add this to https://github.com/sydb/TEI-in-Libraries/blob/master/README.

Syd is committing changes to his local Subversion repository and will commit to our GitHub repository as well at some point.

After making changes to ODDs and stylesheets

 * 1) Syd will regenerate the schemas and HTML documentation and put the last versions online for sharing with the Google engineers working on generation of TEI from Google Books content.
 * Latest version is now at http://bauman.zapto.org/~syd/temp/TEI-in-Libraries/BestPractices/ . This was shared with Google engineers on 2011-07-16.


 * 1) Kevin will edit main-driver.odd to review metadata for the BP as a whole (in both the teiHeader and front elements): editors (stated more prominently than in the appendix), copyright, version number, etc.  He'll also check in with Michelle on whether we need to revise acknowledgement of DLF support.
 * 2) Kevin will replace the official HTML version with a page akin to http://www.tei-c.org/Guidelines/Customization/Lite/ that explains what the BP is, links to the GitHub repository for the latest, and provides links to documentation and schemas generated according to the instructions Syd adds to the README file.