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

From TEIWiki
Jump to navigation Jump to search
(→‎The_TEI_Header_and_Other_Metadata_Schemas: notes from May 26 conf call)
(→‎Rendering better documentation from the ODDs: noted things that aren't issues any more)
 
(181 intermediate revisions by 7 users not shown)
Line 1: Line 1:
−
== @type and @key on persName and orgName ==
+
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]].
  
−
In the best practices document, the author element is described as follows:
+
== Handling of hyphenation ==
  
−
One or more author elements (one name per element) are used to encode the name for the personal author or corporate body responsible for the creation of the source document, even if this creator is not the main entry in the catalog record. Use <persName> or <orgName> when applicable. Whenever possible, establish or use the form of the name from a national name authority file.
+
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"?
  
−
Since the forms of names used in name authority files have a rigid form that doesn't look like a name in the TEI sense (strings like "Welles, Gideon, 1802-1878" offend the sensibilities of XML folks), during the Raleigh meeting we decided that name authority records given in the header should have a type attribute, similar to that used on <title>. So on fileDesc/titleStmt/author and fileDesc/sourceDesc/biblStruct/monogr/author the following values of @type would be allowed:
+
: 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))
  
−
<pre>
+
:: Syd said everything looked fine but made an additional suggestion, which Kevin [https://github.com/sydb/TEI-in-Libraries/commit/8c60fef9dd3b9641b878f16d0370b05d4b838856 just committed].
−
marc100
 
−
marc110
 
−
</pre>
 
  
−
We would not allow marc111 or marc130 because these MARC fields, while used for main entries in cataloging, are not authors in the TEI sense.  As explained in the description of the author element, this element should be used for personal authors or corporate bodies, not necessarily main entries.
+
== Bug fixes ==
  
−
We also decided to recommend use of @key, as in the "Level 4 Name Tagging" section, to reference authority file records. In "Level 4 Name Tagging", it says, "the key attribute points to the unique key in the database table or, as with the ref attribute, the key attribute can point to the xml:id value in the external file".
+
* 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>
  
−
However, @key does not take an IDREF data type (as it was called in the old days), and once I tried to create examples, I realized we don't want to be in the business of adding a <taxonomy> for each authority record referenced elsewhere in the header.  So I think what we want is this:
+
== Copyediting ==
  
−
<pre>
+
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.
−
<author><persName type="marc100" key="lccn-n78-95332">Shakespeare, William, 1564-1616</persName></author>
+
: done ([[User:Kshawkin|Kshawkin]] 20:47, 5 September 2011 (EDT))
−
<author><persName>Shakespeare, William</persName></author>
 
−
<author><orgName type="marc110" key="lccn-n50-63455">National Organization for Women</orgName></author>
 
−
<author>unknown</author>
 
−
</pre>
 
  
−
plus this elsewhere in the header:
+
Move caveats before Level 1 Example to an appropriate place in main-driver.odd.
 +
: done ([[User:Kshawkin|Kshawkin]] 20:47, 5 September 2011 (EDT))
  
−
<pre>
+
Copyedit element recommendations at each level to avoid awkward and misleading syntax.
−
<taxonomy xml:id="lccn"><bibl>Library of Congress Control Number</bibl></taxonomy>
+
: Not finding anything in particular to fix.  I think I was just tired when reading these in person with Syd.
−
</pre>
 
  
−
Sound right?
+
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))
  
−
: We decided to explain to people that you need to create your own naming scheme for the value of key/ref attributes and that the taxonomy tat helps in deciphering these but not in a machine-readable way.
+
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_TEI_Header_and_Other_Metadata_Schemas ==
+
: 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. 
  
−
I added a paragraph to the section called [[Best_Practices_for_TEI_in_Libraries#The_TEI_Header_and_Other_Metadata_Schemas|The TEI Header and Other Metadata Schemas]] explaining why you can't link to outside metadata the way you'd like to.  Does it sound right to everyone?
+
: 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
  
−
: Syd noted that the TEI allows metadata from other namespaces to be included.  This section to be revised to discuss how linking to outside metadata is hardly supported in P5 and to say that this will be dealt with in greater depth in a future revision of the Best Practices.
+
== Rendering better documentation from the ODDs ==
  
−
== rendition in header? ==
+
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))
  
−
I changed removed mention of rendition ladders and replaced recommendation and examples with CSS.  Should we add rendition element to the header?  P5 talks about using this element to define local styles in terms of CSS, but we want to put CSS right inline. So is there any point in using the rendition element in the header?
+
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].
  
−
== hyphenation ==
+
<code>&lt;editor></code>s are not showing up in HTML version of ODD: need to figure out how to make this happen.
  
−
One of the comments we received on the Best Practices draft was a request to recommend on a specific way for handling end-of-line (and end-of-page) hyphenation within the <tt>body</tt>.  We have not discussed this at all in the Best Practices!
+
: Done
  
−
We should have a new section under "General Recommendations" explaining to do end-of-line hyphens like in Tite (to ensure that texts can be converted to Level 3 automatically).  See http://www.tei-c.org/release/doc/tei-p5-exemplars/html/tei_tite.doc.html#e-o-l .  End-of-page hyphens should be done the same way, with the <tt>pb</tt> tag intervening, e.g., <tt>obfus{U+00AD}&lt;pb n="33" facs="00000037.tif"/&gt;cation</tt> . Likewise for end-of-column hyphens. (Note that we don't give the <tt>cb</tt> element anywhere in the Best Practices!)
+
Check that editionStmt gets rendered in HTML version of ODD.
  
−
P5 offers the <tt>hyphenation</tt> element in the header to document your method.  We could give the following in the header element recommendations:
+
: Done
  
−
<tt>&lt;hyphenation eol="all"&gt;&lt;p&gt;End-of-line hyphenation has been retained, but hard and soft hyphens are distinguished.&lt;/p&gt;&lt;/hyphenation&gt;</tt>
+
== Documentation of ODD processing ==
  
−
However, if we use this element, we would need to find another way to encode all of the prose description that is currently in p elements inside the editorialDecl. What should we do?
+
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
  
−
For the record, if I weren't trying to ensure this compatibility, I would have distinguished three cases:
+
== Before release ==
  
−
* hyphenation that occurs at a line or page break but would never occur normally: use U+00AD
+
Update [http://www.tei-c.org/SIG/Libraries/teiinlibraries/ the official HTML version] to remove "Expected release October 2011."
−
* hyphenation that occurs at a line or page break but might have occurred normally: use U+002D
 
−
* hyphenation that should always be present, such as "re-creation" (to create again, as opposed to leisure activity): use U+2011
 
  
−
: [pw]: two points. 1) I'm not sure I see the distinction between the last two examples--why would you use two different characters? 2) for the first example, particularly for end-of-line in prose where line breaks aren't otherwise recorded, why include this at all? It would mess up searching at least in some systems (eg DLXS). I'm still for letting projects decide their own approach, and documenting it in the header (even if it means that we need to recast editorialDecl).
+
Update copy of main-driver.html linked from there.
−
 
 
−
== profile/langUsage/language as empty element? ==
 
−
 
 
−
I added the language element to the header.  The ident= attribute is required, but the element may be empty (despite no such examples given in P5).  It seems entirely redundant to me to have content for this element.  Should we prescribe having no content for it (and just a value for ident=)?
 
−
 
 
−
== idno in sourceDesc ==
 
−
 
 
−
I substantially rewrote the description of the idno element in sourceDesc.  Does this sound right to everyone?  In Raleigh people said they wanted examples of local identifiers, but I don't see where this adds anything useful.  Thoughts?
 
−
 
 
−
== workflow descriptions and slightly revised rationales ==
 
−
 
 
−
I have created a "Workflow" section after the "Rationale" section for Levels 1-4, expanding on the brief description of workflows that we already had in place.  I also revised some rationales, especially Level 3.  Everything look okay?
 
−
 
 
−
== Level 3 and Tite ==
 
−
 
 
−
I've explained the relationship between the Best Practices and Tite vis-a-vis Level 3 and Level 4.  As [http://www.tei-c.org/release/doc/tei-p5-exemplars/html/tei_tite.doc.html#tei-in-lib-bpg Tite explains], there are a few elements missing from Level 3 which are included in Tite. Should we just include these in Level 3 so that elements in the <tt>body</tt> of each map exactly?
 

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"