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

From TEIWiki
Jump to navigation Jump to search
(→‎Rendering better documentation from the ODDs: noted things that aren't issues any more)
 
(167 intermediate revisions by 7 users not shown)
Line 1: Line 1:
−
==Introduction ==
+
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]].
−
   
 
−
1) Definition of level 5 encoding currently reads:
 
  
−
"The text is generated either through corrected OCR or keyboarding, but the tagging requires substantial human intervention by encoders with subject knowledge. "
+
== Handling of hyphenation ==
  
−
I suggest instead:
+
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"?
  
−
"The text is generated either through corrected OCR or keyboarding, '''and''' the tagging requires substantial human intervention by encoders with subject knowledge, "
+
: 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))
  
−
because corrected OCR, keyboarding, and expert tagging ALL require substantial human intervention (though the first two, of course, don't require subject knowledge, and perhaps that is the point of the original phrasing)
+
:: Syd said everything looked fine but made an additional suggestion, which Kevin [https://github.com/sydb/TEI-in-Libraries/commit/8c60fef9dd3b9641b878f16d0370b05d4b838856 just committed].
  
 +
== Bug fixes ==
  
−
2) "If a library uses TEI Tite to outsource its encoding, it should find conversion of TEI Tite files to be trivial: to Level 3 with some loss of granularity and to Level 4 with the addition of some markup, which amounts to minimal human intervention."
+
* 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>
  
−
Should the colon after "trivial" be there?
+
== 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))
  
−
== 2.9 General Guidelines for Attribute Usage  ==
+
Move caveats before Level 1 Example to an appropriate place in main-driver.odd.
 +
: done ([[User:Kshawkin|Kshawkin]] 20:47, 5 September 2011 (EDT))
  
−
1) Since this isn't a comprehensive list of attributes (I don't think), why bother including the "xml:id" and "target" attributes if specific details about how libraries should use these is not actually included in this document?  Is the documentation for these elements considered important to these guidelines, but too extensive to replicate?  How does this differ from the specific best practices given for other attributes listed here, like "n" or "rend"?
+
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.
  
−
2) Under "key and ref":  
+
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))
  
−
"For example,
+
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.
  
−
<author><persName type="marc100" key="lccn-n78-95332">Shakespeare, William, 1564-1616</persName></author>
+
: 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. 
  
−
gives a project-interal key (lccn-n78-95332) for this name in the Library of Congress Name Authority File. Values of key attributes may be partially explained in a non-machine-readable way through use of a taxonomy element: "
+
: 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)
 +
:: Done
  
−
should "project-interal" be "project-internal?"  Or "project-integral?" Or something else?
+
== Rendering better documentation from the ODDs ==
  
−
3) Under "rend and rendition":  
+
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., <tt>--docflags="cssFile=foo.css"</tt> but warned that this was from memory ([[User:Kshawkin|Kshawkin]] 16:08, 22 August 2011 (EDT))
  
−
"The rend and rendition attributes may be used when it is desirable to record information about how the content object was displayed in the source document. "
+
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].
  
−
Is it meant to read "content object," or just "content," or even just "object?"  Having both sounds strange to me, but perhaps it's TEI terminology with which I'm not familiar.
+
<code>&lt;editor></code>s are not showing up in HTML version of ODD: need to figure out how to make this happen.
  
 +
: Done
  
−
== 4.2 The TEI Header ==
+
Check that editionStmt gets rendered in HTML version of ODD.
  
−
1) Currently reads:  
+
: Done
−
"The TEI header is a metadata record that describes an electronic text encoded according to the TEI specification."
 
  
−
Since there are multiple levels of encoding (does this translate to multiple "specifications?"), should this read either
+
== Documentation of ODD processing ==
  
−
a) "...encoded according to '''a''' TEI specification"
+
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 .
−
or
+
: Done
−
b) "...encoded according to the TEI specification'''s'''" ?
 
  
 +
== Before release ==
  
−
== 4.4 The TEI Header and Other Metadata Schemas ==
+
Update [http://www.tei-c.org/SIG/Libraries/teiinlibraries/ the official HTML version] to remove "Expected release October 2011."
  
−
1) Currently reads:
+
Update copy of main-driver.html linked from there.
−
 
 
−
"Unfortunately, there is currently no mechanism for specifying that the content of an element should be drawn from an outside metadata source or that it should supplement the content of the element"
 
−
 
 
−
To me, the "it" was confusing/ambiguous--I suggest instead:
 
−
 
 
−
"Unfortunately, there is currently no mechanism for specifying that the content of an element should be drawn from an outside metadata source or that '''outside metadata''' should supplement the content of the element"
 
−
 
 
−
This feels a little more redundant/wordy, perhaps, but it is clearer.
 

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"