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

From TEIWiki
Jump to navigation Jump to search
m (→‎Review ODDs and schemas derived from them: wiki markup and cleanup of Syd's notes)
(→‎Rendering better documentation from the ODDs: noted things that aren't issues any more)
 
(53 intermediate revisions by 2 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]].
  
−
== Review ODDs and schemas derived from them ==
+
== Handling of hyphenation ==
  
−
Syd wrote:
+
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"?
  
−
<blockquote>
+
: 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))
−
[T]he ODD files themselves are now in a git repository on GitHub. See http://github.com/sydb/TEI-in-Libraries/tree/master. You can view, download, and even edit the files using that web interface.
 
  
−
However, I strongly recommend *against* editing them directly via the GitHub interface. From years of experience editing XML files in shared repositories, I can tell you it can really mess up others when you inadvertently commit a change that is not well-formed, which is easier to do than most people think when using a non-XML aware editor.
+
:: Syd said everything looked fine but made an additional suggestion, which Kevin [https://github.com/sydb/TEI-in-Libraries/commit/8c60fef9dd3b9641b878f16d0370b05d4b838856 just committed].
  
−
However, if you are even slightly more adventurous, it is not particularly difficult to use the `git` command to mirror the
+
== Bug fixes ==
−
repository on your local drive, edit and test there, and then commit (and apparently push) when you're done.
 
  
−
When you sign up on GitHub, please let me know your user name and whether or not you would like to receive <soCalled>pull requests</>, which let you know there has been an update to [ the repository itself or the website copy of it? idunno, but I think the latter ]. Methods of sending info to you are:
+
* 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>
  
−
* POST to a URL
+
== Copyediting ==
−
* Basecamp
 
−
* CIA
 
−
* Campfire
 
−
* Email
 
−
* FogBugz
 
−
* FriendFeed
 
−
* Irc
 
−
* Jabber
 
−
* Lighthouse
 
−
* Presently
 
−
* Rubyforge
 
−
* Trac
 
−
* Twitter
 
  
−
In general in projects like this, the source code (in this case the ODD) is left in the repository, and interested individuals download the source and generate the derived files from it (in this case schemas and HTML or PDF documentation) on their own. To do this you will need to use one of the following:
+
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))
  
−
* roma: very hard to install; but easiest and fastest to use, especially if you write a front-end script; for command-line use only (to my knowledge that means Mac OS X or GNU/Linux only -- I don't think anyone has ported to CygWin or similar)
+
Move caveats before Level 1 Example to an appropriate place in main-driver.odd.
 +
: done ([[User:Kshawkin|Kshawkin]] 20:47, 5 September 2011 (EDT))
  
−
* [[Roma]]: web interface requires no installation and is reasonably intuitive; but takes quite a few clicks, requires a net connection, and may be quite slow if lots of people are using the server at once (which last I knew was under Sebastian's desk in Oxford)
+
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.
  
−
* [[Vesta]]: very easy to install, pretty intuitive, and runs fast if you have a fast machine; but takes a few clicks, and does not remember your settings between invocations; Mac OS X or GNU/Linux only
+
Remove ODD markup in level specifications that Syd added from P5 so as not to include examples that contradict rest of Guidelines.
−
</blockquote>
+
: 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))
  
−
== Pending Review: Use of any P5 attributes ==
+
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.
  
−
On the June 2 conference call, the group agreed to create a list of all attributes to include for Level 1-4.  
+
: 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. 
  
−
* [[Best_Practices_for_TEI_in_Libraries#General_Guidelines_for_Attribute_Usage|Prose changed]] now reflects that there are recommended/required attributes in the body of a text
+
: 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)
−
** This text will need to be revised again after the attribute list has been generated (2010-09:30: DONE BY KEVIN)
+
:: Done
−
** We will probably add an appendix of all attributes identified (DONE BY MICHELLE IN AUGUST)
 
−
* With the goal of creating an "include" list of attributes, Lisa compiled a list of attributes mentioned in the BP, followed by a list of all the additional attributes include in P5, 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
 
−
* Group will then need to test against real-life files
 
  
−
== Pending Review: Add history of version 3 to Appendix A ==
+
== Rendering better documentation from the ODDs ==
  
−
Text is now in the main prose. Could benefit from group review.
+
Tables should have borders on cells (or some clear path for indicating in ODD document that you want borders).
−
: I reviewed and think it is good -- I was more out of the loop in 2009, so I am not the best of reviewers. But let this count as my approval! --[[User:Emcaulay|Emcaulay]] 13:29, 20 June 2010 (EDT)
+
: 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))
  
−
== Pending Review: Add Tite as Level 3.5 ==
+
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].
  
−
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.
+
<code>&lt;editor></code>s are not showing up in HTML version of ODD: need to figure out how to make this happen.
  
−
'''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.
+
: Done
  
−
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.
+
Check that editionStmt gets rendered in HTML version of ODD.
  
−
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.
+
: Done
  
−
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.
+
== Documentation of ODD processing ==
  
−
: 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?
+
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 .
−
:: 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. (kshawkin)
+
: Done
−
::: Kevin looked over changes made since Perry wrote that text in May 2009.  Don't see any major changes, so it should be fine to link to Appendix A of Tite.  We clarified relation ship between Tite and BP in the prose; adding a Level 3.5 is on hold.
 
  
−
Add Perry trolard to acks? --[[User:Emcaulay|Emcaulay]] 13:32, 20 June 2010 (EDT)
+
== Before release ==
  
−
== Acknowledgments ==
+
Update [http://www.tei-c.org/SIG/Libraries/teiinlibraries/ the official HTML version] to remove "Expected release October 2011."
−
* May need to revise DLF thank you to something more onging if they continue ot provide support (under discussion)
 
  
−
== examples of each encoding level ==
+
Update copy of main-driver.html linked from there.
−
 
 
−
We've got one example of Level 1 and one for Level 2 in the [[Best_Practices_for_TEI_in_Libraries#Introduction|Introduction]].  Kevin has asked Matthew Gibson to provide a Level 3 example.  Could we get Level 4 and Level 5 examples?  We're looking for examples of ''texts delivered online'', not necessarily with XML exposed.  The goal is to show what sort of ''functionality you might offer at each level, not perfect encoding''!
 
−
 
 
−
: done (Sept./Oct. 2010)
 

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"