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

From TEIWiki
Jump to navigation Jump to search
m (→‎Add Tite as Level 3.5: Formatting changes for readability)
(→‎Rendering better documentation from the ODDs: noted things that aren't issues any more)
 
(85 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
The following are revisions to make 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]].
  
−
= Test ODDs and schemas derived from them =
+
== Handling of hyphenation ==
  
−
Test Syd's ODDs and schemas derived from them: http://bauman.zapto.org/~syd/temp/BestPractices/ .  Just go to that URL, download the .rng files, and create a new XML document based on the schema.  So if it allows you to insert all the elements you expect to be able to insert.  Syd has been asked to make the following changes:
+
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"?
  
−
* in header ODD, allow only a structured <publicationStmt>
+
: 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))
−
* lib1.rng: <oXygen/> says "Errors encountered: Probably no start pattern found".
 
−
* The only allowed child of front, body, or back *at any level* should be a div.
 
−
* note should not be allowed at in Level 1 or Level 2
 
−
* ab should be the only child allowed of any div (in both Level 1 and Level 2).  This element seems to be missing from the schema.
 
−
* floatingText is missing in Level 3 or Level 4 schemas.
 
  
−
Possible additional tweaks to the ODDs based on email threads. Need to determine whether to move to [[Future changes to Best Practices for TEI in Libraries]]:
+
:: Syd said everything looked fine but made an additional suggestion, which Kevin [https://github.com/sydb/TEI-in-Libraries/commit/8c60fef9dd3b9641b878f16d0370b05d4b838856 just committed].
  
−
* Use of attribute(s) on sourceDesc/biblStruct/monogr/imprint/date is now required, and with attribute values mapping to the Dates fixed fields (per email sent by Kevin on 1/16/2010)
+
== Bug fixes ==
−
* normalizing AACR2 dates for machine processing, to be shared with Thutmose project  (per email sent by Kevin on 1/16/2010)
 
  
−
= Pending Review: Use of any P5 attributes =
+
* 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>
  
−
We need to figure out how much guidance we will give on use of attributes on elements within the body of a TEI document.
+
== Copyediting ==
  
−
* [[Best_Practices_for_TEI_in_Libraries#General_Guidelines_for_Attribute_Usage|Prose changed]] to reflect recommended/required attributes in the body of a text
+
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.
−
** This text may change again after the list has been generated (it's purposefully vague)
+
: done ([[User:Kshawkin|Kshawkin]] 20:47, 5 September 2011 (EDT))
−
** May add an appendix of all attributes identified
 
−
* Lisa is compiling a list of frequently used attributes, see [[List of attributes suggested to include in BPG, and those excluded]]
 
−
* The group will need to review the list for completeness
 
−
* Syd will constrain the ODDs accordingly
 
  
−
=Resolved: Publication Statement=
+
Move caveats before Level 1 Example to an appropriate place in main-driver.odd.
 +
: done ([[User:Kshawkin|Kshawkin]] 20:47, 5 September 2011 (EDT))
  
−
As of 5/26/2010, allow structured and unstructured publication statements, per Kevin:  "In cataloging, I believe you don't state publication information if something is unpublished rather than saying something like "unpublished", but I don't have AACR2 with me at the moment to verify. However, we've been trying to give people the option of creating TEI headers conforming to the BP by hand (not from MARC source) in case they want to, and I agree that the TEI way to do this is with a &lt;p&gt; element.  So I now favor allowing either the structured or unstructured publicationStmt in the ODD but saying in the prose that people they should only use the unstructured one for a statement such as your example. Does this sound okay to others?"
+
Copyedit element recommendations at each level to avoid awkward and misleading syntax.
−
* '''Irrelevant since we are talking about fileDesc publicationStmt; stick with structred statement'''
+
: Not finding anything in particular to fix.  I think I was just tired when reading these in person with Syd.
  
−
= Resolved: Direction of pointing between note references and notes themselves =
+
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))
  
−
Decide whether to change back to having &lt;ref&gt; point to &lt;note&gt; instead of &lt;note&gt; point to &lt;ref&gt;, as Syd recommended.  See this ticket:
+
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.
  
−
https://sourceforge.net/tracker/?func=detail&aid=2796148&group_id=106328&atid=644062
+
: 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. 
  
−
and this change to the Guidelines:
+
: 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
  
−
http://tei.svn.sourceforge.net/viewvc/tei/trunk/P5/Source/Guidelines/en/CO-CoreElements.xml?r1=6937&r2=6936&pathrev=6937
+
== Rendering better documentation from the ODDs ==
  
−
or, for the full story, see Kevin's email from Nov. 6 and previous quoted messages.
+
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))
  
−
* Kevin updated this in the Bp: [[Best_Practices_for_TEI_in_Libraries#Notes]]
+
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].
  
−
= Pending Review: meeting element =
+
<code>&lt;editor></code>s are not showing up in HTML version of ODD: need to figure out how to make this happen.
  
−
Decide whether to include &lt;meeting&gt; in sourceDesc/biblStruct/monogr/ and/or in titleStmt.  (Per a change on 2010-01-15 in SourceForge, meeting is now allowed in titleStmt.)  As Kevin discussed in an email sent on Oct. 12, the name of a meeting is usually included in a MARC record, but it's not distinguished from an author or editor in the same way TEI divides up the world.  The essential question is: if you digitize a volume of conference proceedings, is the name of the meeting, as opposed to the title of the volume, really important enough to warrant inclusion in the TEI header?  If so, we need to wrestle with the questions Kevin brought up on Oct. 11.
+
: Done
  
−
* June 2, 2010 call: add meeting element to the header; Kevin will contact Renee about MARC mappings
+
Check that editionStmt gets rendered in HTML version of ODD.
  
−
** I've added meeting to the header in fileDesc and sourceDesc and made it optional because if a conference is not named in the item being cataloged but could still be inferred or assumed, this name would not be included in the catalog record and therefore would not be available for inclusion in meeting.  By making it optional, we won't require human intervention. ([[User:Kshawkin|Kshawkin]])
+
: Done
  
−
= Resolved: appInfo and application =
+
== Documentation of ODD processing ==
  
−
Decide whether to include &lt;appInfo&gt; and &lt;application&gt; in our header recommendations.  In email discussions, Syd saw them as useful, but Lisa didn't think we need them.
+
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
  
−
: There is at least one proposal forthcoming for further work on defining the scope and usage of these elements, which have not yet reached the degree of stability desirable for inclusion in a BP document, imho [[User:LouBurnard|LouBurnard]]
+
== Before release ==
  
−
* June 2, 2010 call:  Due to the instability of these elements, we will table their inclusion for now and revisit after TEI Council determines a ruling :-).
+
Update [http://www.tei-c.org/SIG/Libraries/teiinlibraries/ the official HTML version] to remove "Expected release October 2011."
−
* Should I move this to "Future work" page so we don't lose sight?
 
−
** I've written it up there.  When we clean up this page, this section can be removed.
 
  
−
= Add history of version 3 to Appendix A =
+
Update copy of main-driver.html linked from there.
−
 
 
−
* Text migrating into main prose
 
−
* Could benefit from group review
 
−
 
 
−
= Add Tite as Level 3.5 =
 
−
 
 
−
* Dependent on ongoing Tite revisions; need confirmation from Dan O'Donnell/Perry Trolard
 
−
* Adding level 3.5 on hold
 
−
* Updated clarification between Tite and the BP added to the main prose
 
−
 
 
−
<blockquote>
 
−
This was [[Minutes_from_November_14%2C_2009#Harmonizing_TEI_Tite_with_the_Best_Practices:_Is_it_worth_pursuing.3F|strongly recommended by Daniel Pitti]] in Ann Arbor because he felt certain that administrators and funders would be confused about the difference between TEI Tite and the Best Practices ("don't the libraries already have a TEI customization?"); in fact, Kevin has known this same confusion to arise among TEI Council members.  While we have a section of the BP discussion its relationship to Tite, by having a Level 3.5, we can be more explicit about mapping between the two.
 
−
 
 
−
'''Mapping clarification from Kevin:'''  Instead of actually mapping elements, Daniel wanted us to simply proclaim use of Tite as one of a number of appropriate encoding levels for libraries.
 
−
 
 
−
Naturally we will not be able to describe Tite the way we do other levels -- by simply saying "all the elements in the previous levels, plus the following". Tite uses different element names of all sorts. There's no point in having Syd make an ODD for Tite since one already exists.  So what Kevin envisions here is a sort of "sidebar" about Tite, inserted between Levels 3 and 4 that discusses Tite in a bit more detail than we currently have in the beginning of the BP, with particular discussion of mapping between the two.
 
−
 
 
−
We recently had some discussion about the merits of this, so maybe we won't do it in the end.  But if we do, we'll need a draft of this new sidebar.  Two paragraphs are already written for you (the brief discussion of the relationship between Tite and the BP), and you can pull more information from Tite's discussion of an earlier version of the Best Practices.
 
−
 
 
−
Would someone be willing to write a first draft of all of this?  Two paragraphs are already written for you, and you can pull more information from Tite's discussion of an earlier version of the Best Practices.
 
−
 
 
−
* Can we just use what's written here (rather than link to it) and modify accordingly fpr our level 3.5: http://www.tei-c.org/release/doc/tei-p5-exemplars/html/tei_tite.doc.html#tei-in-lib-bpg.  Didn't Kevin write this anyway?  If not, whose permission do we need?
 
−
** I'm pretty sure Perry Trolard wrote this section.  Shouldn't be a problem to use it.  However, we should carefully check all the assertions since things have likely changed since Tite was last revised.  Another round of Tite revisions is supposed to be forthcoming, so perhaps wait on this.
 
−
</blockquote>
 
−
 
 
−
= Revise section on hyphenation =
 
−
 
 
−
* ediotorialDecl description in Header pending; Kevin will confirm with Perry W.
 
−
 
 
−
= Acknowledgments =
 
−
 
 
−
==Tools Dev==
 
−
Need to add Michael to this list and I think we should especially highlight Syd's ODD work so I propose we add the following section above the copy-editors:
 
−
 
 
−
The individuals who have contributed complementary tools to this document are:
 
−
* Syd Bauman (Brown University): ODD specifications for levels 1-4
 
−
* Michael Sperberg-McQueen (Black Mesa Technologies LLC): Thutmose stylesheets for MARC-to-TEI Header mappings
 
−
 
 
−
: Great idea. ([[User:Kshawkin|Kshawkin]])
 
−
 
 
−
==Editors==
 
−
Do we want to higlight Kevin and Michelle as editors of this document?  Who else?
 
−
 
 
−
: I vote yes, to acknowledge these especially heroic efforts. ([[User:Gworthey|Gworthey]])
 

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"