Difference between revisions of "Talk:Best Practices for TEI in Libraries"

From TEIWiki
Jump to navigation Jump to search
(→‎After making changes to ODDs and stylesheets: need to remove bad examples!)
(→‎Rendering better documentation from the ODDs: noted things that aren't issues any more)
 
(33 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
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]].
 
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) ==
+
== Handling of hyphenation ==
  
−
The latest version of the <cite>Best Practices for TEI in Libraries</cite> document, now derived from source TEI ODD files, is available for review. I have moved all of the content from [[Best Practices for TEI in Libraries|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 [https://github.com/sydb/TEI-in-Libraries 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 [[User:Syd|Syd]] your GitHub user name and he’ll add you to the “contributors” list.
+
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"?
  
−
For those of you who are not interested in wrestling with command-line `roma`<ref>Last I knew, the web `Roma` will not properly process the new ODD constructs, so cannot be used for these files. Using the command-line `roma` is not all that bad, though. And once you get the hang of it, it is ''much'' faster than using the web. For a complete set of instructions for installing command-line `roma` on Mac OS X (or GNU/Linux), see http://www.wwp.brown.edu/outreach/seminars/_current/handouts/roma_CLI_MacOS_X.html . Note that (a) there is a known but small cart-before-the-horse problem in these instructions — I don’t remember what it is at the moment or I’d tell you; and (b) that URL will (hopefully) change later this month, but it will probably get re-directed. ([[User:Syd|Syd]])</ref>, 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 [http://tei.wwp.brown.edu/~syd/temp/TEI-Library-SIG/BP_files.html an easy-to-use list of the most important files] and [http://tei.wwp.brown.edu/~syd/temp/TEI-Library-SIG/BestPractices/ 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.).
+
: Syd re-read P5 and emailed Kevin that he thinks we can handle this without a wider call. Kevin agreed with Syd on a solution and made the revisions to main-driver.odd and level4.odd. Asked Syd to check over the changes to [https://github.com/sydb/TEI-in-Libraries/commit/31a8730b9d0af093099a18ab57078d4b8577c23b#BestPractices/main-driver.odd main-driver.odd] and [https://github.com/sydb/TEI-in-Libraries/commit/9e4f98caeda0446ebb3397f619c83b534ccd1fca#BestPractices/level4.odd level4.odd]. Then will update the SIG on our handling of this issue and on the final work on the BP as a whole. ([[User:Kshawkin|Kshawkin]] 11:28, 13 September 2011 (EDT))
  
−
The process of [[Feedback on the TEI in Libraries Best Practices ODD Documentation and Schemas|gathering feedback was formalized and carried out in Spring 2011]].
+
:: Syd said everything looked fine but made an additional suggestion, which Kevin [https://github.com/sydb/TEI-in-Libraries/commit/8c60fef9dd3b9641b878f16d0370b05d4b838856 just committed].
  
−
== Edits made and to be made based on feedback ==
+
== Bug fixes ==
  
−
Kevin Hawkins and Syd Bauman met on 2011-07-05 to go through [[Feedback on the TEI in Libraries Best Practices ODD Documentation and Schemas|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.
+
* Fix schema bug where list element is not allowed except as a child of p.
 +
: Syd put model.inter back into model.common at Levels 3 and 4.  This fixed the problem.  <b>Syd wonders whether this change will have any side-effect; he will investigate further.</b>
 +
 
 +
== Copyediting ==
 +
 
 +
Change all instances of "must" to "should" and "required" to "recommended", and all existing "recommended" to "optional".  All this is in accordance with RFC 2119 and with the BP's general policy of not requiring anything but simply being "best practices".  Clarify that the ODDs require things just to encourage conformance.
 +
: done ([[User:Kshawkin|Kshawkin]] 20:47, 5 September 2011 (EDT))
 +
 
 +
Move caveats before Level 1 Example to an appropriate place in main-driver.odd.
 +
: done ([[User:Kshawkin|Kshawkin]] 20:47, 5 September 2011 (EDT))
 +
 
 +
Copyedit element recommendations at each level to avoid awkward and misleading syntax.
 +
: Not finding anything in particular to fix.  I think I was just tired when reading these in person with Syd.
 +
 
 +
Remove ODD markup in level specifications that Syd added from P5 so as not to include examples that contradict rest of Guidelines.
 +
: Commented out gloss, desc, exemplum, remarks, and listRef in level1.odd for Syd to check over before I do in other levels. ([[User:Kshawkin|Kshawkin]] 20:47, 5 September 2011 (EDT))
 +
:: Syd said he un-commented out these elements.  He'll review the 79 elements in the various ODDs to check for conflict with the BP prose.  That way we can include them with our release. ([[User:Kshawkin|Kshawkin]] 10:46, 3 October 2011 (EDT))
 +
 
 +
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.  Check with Michelle on whether we should revise acknowledgment of DLF support.
  
−
The following issues were reported during the feedback process but remain to be resolved in the ODDs:
+
: In teiHeader, added Michelle as <editor> and copyedited name of SIG.  Having been in touch with DLF recently, I'm pretty sure our statement of support is sufficient. 
  
−
* 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"?
+
: As last step before releasing, add <code>&lt;editionStmt>&lt;p>Version 3.0 (October 2011)&lt;/p>&lt;/editionStmt></code> [[User:Kshawkin|Kshawkin]] 20:27, 29 September 2011 (EDT)
−
* 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]].
+
:: Done
  
−
In addition, we need to resolve the following in the stylesheet(s) for creating HTML documentation:
+
== Rendering better documentation from the ODDs ==
  
−
* 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).
−
* Tables should have borders on cells (or some clear path for indicating in ODD document that you want borders).
+
: Syd said this can be overriden by giving values for cssFile and/or cssSecondFile parameters to odd2html.xsl.  Not sure how to "send" these through roma2.
−
* Omit exemplars from output.
+
:: Sebastian wrote in an email to use, e.g., <tt>--docflags="cssFile=foo.css"</tt> but warned that this was from memory ([[User:Kshawkin|Kshawkin]] 16:08, 22 August 2011 (EDT))
−
* Figure out why code samples have &lt;span&gt;s in them all over the place. Suppress these.
 
  
−
Furthermore, we discovered that Syd had not kept the ODDs in sync with [http://wiki.tei-c.org/index.php?title=Best_Practices_for_TEI_in_Libraries&diff=8883&oldid=8695|changes made between 2010-12-19 and when the wiki was frozen].  He is working through that list of changes to make.
+
Omit exemplars from output — preferably just those from the P5 source, not the customization ODD file.
 +
: Done. See the [https://github.com/sydb/TEI-in-Libraries/blob/master/BestPractices/odd2odd.xsl.patch stylesheet patch file].
  
−
: Syd has made all of these revisions from the "diff list".
+
<code>&lt;editor></code>s are not showing up in HTML version of ODD: need to figure out how to make this happen.
  
−
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 .
+
: Done
  
−
Late feedback from Google:
+
Check that editionStmt gets rendered in HTML version of ODD.
  
−
* Change "Required if headings are present. This element must be a child of a <div> or <div1>." to "Required if headings are present. This element must be the first child of a textual division."  (In the latter sentence, this is the generic "div" term so that this rule can apply for levels 3, 4, and 5 as well.)
+
: Done
−
: Left this for Level 2 but added to Level 4 with alternate definition.
 
−
* Fix schema bug where list element is not allowed except as a child of p.
 
  
−
Syd is committing changes to his local Subversion repository and will commit to [https://github.com/sydb/TEI-in-Libraries/ our GitHub repository] as well at some point.
+
== Documentation of ODD processing ==
  
−
== After making changes to ODDs and stylesheets ==
+
Syd will write down the command-line code needed in order to generate HTML files from the ODDs and add this to https://github.com/sydb/TEI-in-Libraries/blob/master/README .
 +
: Done
  
−
# Syd will regenerate the schemas and HTML documentation and [http://tei.wwp.brown.edu/~syd/temp/TEI-Library-SIG/BestPractices/ put the last versions online for sharing with the Google engineers working on generation of TEI from Google Books content].
+
== Before release ==
−
: 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.
 
−
# Kevin will copyedit element recommendations at each level to avoid awkward and misleading syntax.
 
−
# Kevin will remove ODD markup in level specifications that Syd added from P5 so as not to include examples that contradict rest of Guidelines.
 
−
# 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.
 
−
# Kevin will replace [http://www.tei-c.org/SIG/Libraries/teiinlibraries/ 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.
 
  
−
== References ==
+
Update [http://www.tei-c.org/SIG/Libraries/teiinlibraries/ the official HTML version] to remove "Expected release October 2011."
  
−
<references/>
+
Update copy of main-driver.html linked from there.

Latest revision as of 02:31, 24 October 2011

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.

Handling of hyphenation

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 re-read P5 and emailed Kevin that he thinks we can handle this without a wider call. Kevin agreed with Syd on a solution and made the revisions to main-driver.odd and level4.odd. Asked Syd to check over the changes to main-driver.odd and level4.odd. Then will update the SIG on our handling of this issue and on the final work on the BP as a whole. (Kshawkin 11:28, 13 September 2011 (EDT))
Syd said everything looked fine but made an additional suggestion, which Kevin just committed.

Bug fixes

  • Fix schema bug where list element is not allowed except as a child of p.
Syd put model.inter back into model.common at Levels 3 and 4. This fixed the problem. Syd wonders whether this change will have any side-effect; he will investigate further.

Copyediting

Change all instances of "must" to "should" and "required" to "recommended", and all existing "recommended" to "optional". All this is in accordance with RFC 2119 and with the BP's general policy of not requiring anything but simply being "best practices". Clarify that the ODDs require things just to encourage conformance.

done (Kshawkin 20:47, 5 September 2011 (EDT))

Move caveats before Level 1 Example to an appropriate place in main-driver.odd.

done (Kshawkin 20:47, 5 September 2011 (EDT))

Copyedit element recommendations at each level to avoid awkward and misleading syntax.

Not finding anything in particular to fix. I think I was just tired when reading these in person with Syd.

Remove ODD markup in level specifications that Syd added from P5 so as not to include examples that contradict rest of Guidelines.

Commented out gloss, desc, exemplum, remarks, and listRef in level1.odd for Syd to check over before I do in other levels. (Kshawkin 20:47, 5 September 2011 (EDT))
Syd said he un-commented out these elements. He'll review the 79 elements in the various ODDs to check for conflict with the BP prose. That way we can include them with our release. (Kshawkin 10:46, 3 October 2011 (EDT))

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. Check with Michelle on whether we should revise acknowledgment of DLF support.

In teiHeader, added Michelle as <editor> and copyedited name of SIG. Having been in touch with DLF recently, I'm pretty sure our statement of support is sufficient.
As last step before releasing, add <editionStmt><p>Version 3.0 (October 2011)</p></editionStmt> Kshawkin 20:27, 29 September 2011 (EDT)
Done

Rendering better documentation from the ODDs

Tables should have borders on cells (or some clear path for indicating in ODD document that you want borders).

Syd said this can be overriden by giving values for cssFile and/or cssSecondFile parameters to odd2html.xsl. Not sure how to "send" these through roma2.
Sebastian wrote in an email to use, e.g., --docflags="cssFile=foo.css" but warned that this was from memory (Kshawkin 16:08, 22 August 2011 (EDT))

Omit exemplars from output — preferably just those from the P5 source, not the customization ODD file.

Done. See the stylesheet patch file.

<editor>s are not showing up in HTML version of ODD: need to figure out how to make this happen.

Done

Check that editionStmt gets rendered in HTML version of ODD.

Done

Documentation of ODD processing

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

Done

Before release

Update the official HTML version to remove "Expected release October 2011."

Update copy of main-driver.html linked from there.

Retrieved from "https://wiki.tei-c.org/index.php?title=Talk:Best_Practices_for_TEI_in_Libraries&oldid=10260"