View source for BPG Feedback on Complete Draft

[http://wiki.tei-c.org/index.php/TEI_in_Libraries:_Guidelines_for_Best_Practices Back to GBP]

The main sections of the BPG are outlined below to facilitate orderly feedback :-).  '''Please provide feedback by Saturday, April 11th''' so Kevin and I have enough time to compile any of the more significant issues for discussion during our upcoming meeting on April 14th.   

Add each new comment as a bullet point and be sure to attribute comments so we know how to follow-up if there's some debate.  For example:

* feedback blah blah, [[User:Mdalmau|Mdalmau]]

==Introduction==
* <strike>Task Force w/c though historically correct may lose context in this new revision.  Consider something more generic like "Working Group" or past tense: "the Task Force attempted to make these ..."</strike> [[User:Mdalmau|Mdalmau]]

==General Recommendations==
* <strike>Conisder moving facsimile page image info here as the final bullet point. [[User:Mdalmau|Mdalmau]]</strike> done

==Structure of a TEI Document==

* Do we need to reference <tt>&lt;facsimile></tt>?  [[User:Mdalmau|Mdalmau]]
** We don't.  We assume Libraries will use METS for that functionality.

==The TEI Header==

* <strike>I changed 'the Open Access Initiative (OAI)" to "the Open Archives Initiative (OAI)". Unless there is another initiative that I do not know about.[[User:Natasha|Natasha]]</strike> okay

* <strike>encodingDesc: Even though Melanie and I wrote most of the header, I don't remember any more why some information about sourceDesc is in encodingDesc/p and other info is in encodingDesc/editorialDecl/p .  Seems like this info should be in one place or the other.  Suggestions?  Note that the P5 schema allows both p and non-p children of encodingDesc, but the prose implies that this isn't allowed.  I've reported to SourceForge ( https://sourceforge.net/tracker/?func=detail&atid=644062&aid=2761884&group_id=106328 ), but maybe we should do it one way or the other.  All the more reason to fix this.</strike> Moved everything to editorialDecl.

* <strike>How to allow for automatic generation of sourceDesc from a MARC record yet not commit tag abuse on author and respStmt elements.</strike> We now use &lt;title type="MARC245c"&gt; instead of respStmt when generating from MARC.

==Linking between encoded text and images of source documents==
* <strike>Consider moving this text up under the General Rec. section. [[User:Mdalmau|Mdalmau]]</strike> done
* <strike>Do we need to say this: "The examples below use the former method."  And do we want all examples to use @facs? I think we should mix it up since we are recommending both options.</strike> [[User:Mdalmau|Mdalmau]]
** <strike>Kevin suggested that we need more info for how to use xml:id with METS.  I am not quite sure how to do this at-a-glance and any attempt at detail will lead us into a significant discussion about METS.  Here are some things we can say, but may not all of them (and hopefully Chris P. can provide some guidance):</strike>
*** <strike>Use xml:id used as a "conceptual" identifier for content but not explicit representation of content (it doesn't "point to" content)</strike>
*** <strike>fileSec used to explicitly list all the images (master, jpg, pdf)</strike>
*** <strike>structMap orders the pages by page break and references each image defined in fileSec</strike> [[User:Mdalmau|Mdalmau]]

==LEVEL 1: Fully Automated Conversion and Encoding==

* <strike>Should an automated workflow be described?  ([[User:Kshawkin|Kshawkin]])</strike> done

==LEVEL 2: Minimal Encoding==

* <strike>Should an automated workflow be described?  How does everyone feel about the one Kevin described by email on 2009-04-08? ([[User:Kshawkin|Kshawkin]])</strike>

<strike>Second paragraph of rationale: why "earlier than 1900"?  Restate to explain what it is about certain older source documents that makes it difficult to use automated methods on them.</strike> Rephrased to "older materials", then removed anyway in description of automated workflow.

I think the last paragraph of "Rationale" in essence repeats what has been stated in the first para.
Suggestions - combine them and edit to avoid repetition. [[User:Natasha|Natasha]]

Consider revision? "Level 2 texts do not require any special knowledge or manual intervention below the section level." [[User:Natasha|Natasha]]

<strike>In "Linking between encoded text and images of source documents", we say that "The examples below use the former method", i.e. "Use the @facs attribute on each <pb> element to point to the corresponding page image using a URI." Indeed that's what we use in the Level 1 example:
<pb n="114" facs="00000002.tif"/>

However, here is the level 2 example:
<pb xml:id="p21198-zz0002mpqr" n="1"/>
[[User:Natasha|Natasha]]

maybe to keep one - Alger Hiss document - example?[[User:Natasha|Natasha]]</strike> No longer says "The examples below use the former method".

==LEVEL 3: Simple Analysis==

=== General Level 3 Recommendations ===
* <strike>need to check for consistency: sometimes it's <tt>pb</tt>, sometimes it's <tt>&lt;pb&gt;</tt> [[User:Natasha|Natasha]]</strike> This will be dealt with in copyediting.

* <strike>sorry, but what does "Forme Works" mean? [[User:Natasha|Natasha]]</strike> clarified this TEI term

* <strike>Need to explain more about how to encode end-of-division notes.  They need an n= attribute, but they also need a <tt>ptr</tt> in the text.</strike>
** <strike>Do we handle with: &lt;ref target="#note01">1</ref> that points to end of division [1] <note xml:id="note01">blah</note>?</strike>
** <strike>Do we need to support bi-directional linking: &lt;ref target="#note01" xml:id="ref01">1</ref> and <note xml:id="note01">&lt;ref target="#ref01">[1]</ref>blah</note>? [[User:Mdalmau|Mdalmau]]</strike>
*** <strike>See email from Kevin sent on 2009-04-14.</strike> Since no feedback from Syd, we went with option b from Kevin's email even though this doesn't agree with the TOC markup, based on P5, which uses <tt>ptr</tt> instead of <tt>ref</tt> when it might be expected.
* <strike>Use of the "n" attribute for <l> should be optional.  Remove from example? Or add optional "n" usage to the table? [[User:Mdalmau|Mdalmau]] (reported by Rich)</strike> We decided to remove n= from l element in Level 3.

* <strike>Check: "Add the "target" attribute (@target) to reference the <pb> identifier to generate links from the index into the text proper." And in general the consistency with how we list attributes, i.e. "target" attribute or target= attribute; or @target, etc. [[User:Natasha|Natasha]]</strike>
** <strike>I revised this to make it somewhat clearer, but I think it should be rewritten and an example (even a fake one) included.  It would be good to give guidance on what to do with things like page ranges in an index and errors in the index. ([[User:Kshawkin|Kshawkin]])</strike> No full example yet provided, but ext revised to make it clearer. People can decide on their own what to do about page ranges and errors.

=== Level 3 Examples ===
==== Basic Structure: Verse ====
<strike>I am afraid that our examples for level 3 and level 4 verse are not that different. Level 3 verse has n= attribute for <l> element, while level 4 verse does not. Thoughts? [[User:Natasha|Natasha]]</strike> Level 3 now has no n=, and Level 4 does.

==LEVEL 4: Basic Content Analysis==
* <strike>For name tagging, recommend the use of @ref when the target is web accessible and @key when not.</strike> [[User:Mdalmau|Mdalmau]]
* <strike>Matt has provided an @key example; some possible debate about where the explanation appears in the Header</strike> [[User:Mdalmau|Mdalmau]]
* Moved Name Tagging recommendations from bullet point under General Recommendations to its own section.  The explanation and examples are too dense for a bullet point.  We may need to find a better place for this. [[User:Mdalmau|Mdalmau]]
** Not contested.
* <strike>Natasha to incorporate index "tip" originally in level 3 in level 4:

<p>'''Back Matter'''</p>

     <p>'''&lt;div type="index"&gt;''': Use [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/CO.html#CONOIX lists] to mark up index entries, with the <tt>&lt;ref&gt;</tt> element used to mark up page numbers given in the index entry.  Add the "target" attribute (@target) to reference the n= attribute of the <tt>&lt;pb&gt;</tt> of the referenced page.</p></strike> Kevin just did this.


=== Level 4 Letters ===

* <strike>This text conflates personal letters (epistles) with situations where one text is embedded within another.  These topics should be dealt with separately since there are encoding projects that encode personal correspondence only (where letters are not embedded within other texts), and there are cases of non-epistles included within frame texts. ([[User:Kshawkin|Kshawkin]])</strike>
** <strike>I see your point, Kevin. I will try to find a more clear-cut example, but, honestly, I would stay with the one we have :-) [[User:Natasha|Natasha]]</strike> Kevin clarified the text of the GBP.

=== Level 4 Drama ===

* <strike>It says, "Stage directions are encoded as &lt;stage&gt; and enclose block level content describing scenery, etc."  This is unclear: should block-level content describing the scenery etc. be "enclosed" in &lt;stage&gt; tags?</strike>

** <strike>I just changed this to read: "Stage directions are encoded as &lt;stage&gt; and enclose content describing scenery, stage directions, etc." However, this may miss the point that Kevin indicated above, that basically elements such as &lt;p&gt; are allowed inside of &lt;stage&gt; ([[User:Drsweeg|Drsweeg]])</strike> done

=== Level 4 Verse ===

* <strike>&lt;l rend=""&gt;: Matt added a note in the GBP, which I've moved here: "note: I really don't think we want to keep something like this in here; what do others recommend as far as methods for encoding typographically explicit verse breaks, etc.?"</strike>

** <strike>Also, what sorts of values should be used on rend=? ([[User:Kshawkin|Kshawkin]])</strike> We decided that use of rend= to mark indents is okay.  Discussion of milestones broken out into a new section.

==LEVEL 5: Scholarly Encoding Projects==

* Need examples.  Syd was going to make scholarly the level 4 examples.  Any updates? [[User:Mdalmau|Mdalmau]]
Syd, what do you think about my comments re your WWP example? It can be considered level 5. [[User:Natasha|Natasha]]

* I've added two verse examples, neither of which inspires much confidence.  I wouldn't be hurt if someone were to replace these with other better (e.g. WWP) examples.  [[User:Gworthey|Gworthey]]

==General Guidelines for Attribute Usage==

* <strike>It says, "For instance, if all text is encoded as <tt>&lt;hi&gt;</tt> is defined as being rendered in italics, there is no reason to encode text as <tt>&lt;hi rend="slant(italics)"&gt;</tt>" .  We need to say where this would be defined, and by whom.  But we should also discuss the question of normalization in rendering. If a project wants to encode all monograph titles as italics regardless of how they were displayed in the source document, then there's no need to use rend=.  But if the project wants to transcribe the source document faithfully, including all inconsistencies, then rend= should always be used. ([[User:Kshawkin|Kshawkin]])</strike> done

* Why aren't we using the new rendition feature in P5? [[User:Mdalmau|Mdalmau]]
** Syd said he doesn't know of any successful implementations. Michelle said she's seen mention of it on TEI-L.  People reviewing our draft may ask about this, so we'll need to be prepared to respond. ([[User:Kshawkin|Kshawkin]])

* <strike>Can we move this section up as a subsection to the "General Recommendations"? [[User:Gworthey|Gworthey]]</strike> done

==Acknowledgements==

==Appendix A: History of this Document==



[[Category:SIG:Libraries]]