Map Of London

We've been working on a way of showing initials for people responsible for editorial notes, and I now have it working on the dev version of the site. This is how it works:

• Every person who contributes editorial notes needs to supply their preferred initials. For testing purposes, I've added my own (MDH) and Janelle's (JJ) to PERS1.xml. You add the initials like this:

           <person xml:id="JENS1" sex="2">
               <persName type="cont">
                 <reg>Jenstad, Janelle</reg>
                 <forename>Janelle</forename>
                 <surname>Jenstad</surname>
                 <abbr>JJ</abbr>                <---- THIS LINE
               </persName>
  
              [...]
          </person>

  i.e. in an <abbr> element inside the <persName>.
• You use @resp on <note type="editorial"> like this:

      <note type="editorial" resp="mol:JENS1">

  You can have multiple people if you want:

   <note type="editorial" resp="mol:JENS1 mol:HOLM3">
  

• You get results as shown on e.g. TRAN2 on the dev site.

If the person has no initials, or there is no @resp, then nothing appears. I think we probably want to enforce the presence of @resp, though, for all editorial notes.

KMF and I worked through the output of the consistency checker, fixing everything we could fix, and confirming that the remaining missing ids are queued up in the PERS spreadsheet waiting to be created. I've also implemented a rather messy but effective Schematron rule which checks the structure of local @xml:id attributes, forcing them to begin with the @xml:id of their ancestor TEI element followed by an underscore. Validated the whole collection against the new rule and fixed some more errors before committing it.

KMF and I sat down and worked through the rendering possibilities for note markers. We've arrived at a good solution, now working on dev pending approval, and in the process I've implemented better accessibility by making the note number spans focusable (all you need to do is put @tabindex="0" on an element to make it focusable and put it into the document tab index list in document order). I've also put an onfocus event that shows the footnote, so if you tab through the footnotes you'll see them pop up as they get the focus, rather than having to press another key. This is good progress.

EDIT: Done 2014-10-15

I've carried out most of the changes, and implemented some changes to rendering. These remain to be done:

• Check for internal links which have only their mol: id as link text in editorial notes, and expand them.
• Add any useful Schematron rules to force e.g. the use of @source when @evidence="external".

We're also discussing the fact that footnote numbers in the text look like "supplied" text because they're rendered using square brackets; I propose to change these to small buttons as in Mariage, and see if that's preferred by the team.

Met with JJ and we're going to go ahead with the encoding changes as planned and documented on the earlier post. I've now substantially enhanced the XSLT so that it does things like upper-casing the first letter of a note, and so that informal references to external MoEML ids are turned into links.

I have tested the XSLT and it appears to be working well. I've also made the changes to the ODD file, but I haven't yet regenerated the schema, because that will instantly invalidate all the existing uses of @reason. TODO:

• Generate the new schema.
• Run the XSLT to change all the <supplied> instances.
• Validate and fix the results.
• Check for internal links which have only their mol: id as link text in editorial notes, and expand them.
• Add any useful Schematron rules to force e.g. the use of @source when @evidence="external".
• Final validation and commit.

This document was considerably out of date, so I've updated the earlier parts of it and revised documentation and example code. Hit a problem with including XInclude elements inside <egXML>; they disappear, of course. So what I've done for the moment is include them as escaped text, which has the added benefit that they appear differently in the output. I need to rework the output code to handle these things, but they're going to be fairly rare so it might not be worth it.

I've written the XSLT to convert the current problems with the <supplied> element to something more reasonable, pending agreement of the team with my proposed values for @reason and @evidence. Tested and working. Schema changes would have to be made at the same time, to make it worthwhile, as specified in the preceding post.

This is the current list of distinct values for @reason (used, as it is, incorrectly, on <supplied>):

• corrected against Bergeron
• EEBO transcription gap. Letter distinguishable by context
• gap in inking; missing letter distinguishable by context
• gap in inking. Letter distinguishable by context
• Facsimile unclear. Addition proofed in David Bergeron's critical edition
• letters missing in the EEBO transcription. Proofed against David Bergeron's critical edition
• EEBO Transcription gap. Missing letters proofed from David Bergeron's critical edition
• new page; catchword euer on previous page
• gap in inking; missing letters obvious from context
• piece of type is a broken semi-colon or an italic colon. This piece of type appears on B2r, but also appears twice on the other side of the sheet, on both B2v and B4v. This mystery requires more investigation.
• justifiable by surrounding context and indicated character spacing
• indicated by catchword on previous page
• checked against Bergeron
• chacked against Bergeron
• gap in inking; text proofed against David Bergeron's text
• gap in inking; letter obvious from context
• gap in inking; missing letters distinguishable by context
• letter distinguishable by context
• gap in inking; text proofed against David M. Bergeron's transcription
• gap in inking. Missing letters obvious from context
• faded ink. Missing letters obvious from context
• faded ink; missing letters obvious from context
• faded ink; missing letter obvious from context
• inking error. Missing letters obvious from context
• Imperfectly inked type; letter obvious from context.
• gap in inking: missing letter obvious from context
• gap in inking: proofed against EBBA facsimile
• page cropped
• page cropped; proofed against HEBE1
• uninked type in Folger Shakespeare Library copy filmed for EEBO
• faded ink: proofed against STC 14685.7
• faded ink: missing letter obvious from context
• verified with Strong's Concordance
• verified with Stong's Concordance
• searched through Thomas Adams sermons in Google Books
• misprint; substitute letter obvious from context
• heavy impression on verso onbscuring the recto print--checked verse with online Latin Bible
• from the Apocryphal book of Esdras, but cannot find the direct source
• should be the equivalent of 'trial,' instead of two words. Obvious from the context
• one word: obvious from the context
• missing letter obvious from context
• faded ink; Biblical citation obvious from the context
• faded ink; missing punctuation obvious from context
• gap in inking; Latin term meaning brought forth or uttered
• letter missing; context obvious
• letter missing
• unclear
• underinking
• scan cut off
• scan cut off; context obvious
• unclear; supplied from mol:STOW1
• unclear; context obvious
• underinking; context obvious
• Letter unclear; context obvious
• character missing
• scan unclear
• bleedthrough
• Page cropped; context obvious
• Letter missing; context obvious
• page cropped; context obvious
• scan unclear; context obvious
• letters missing
• letter unclear; context obvious
• gap in inking; context obvious
• gap in the inking
• overinking
• ink bleedthrough
• letter missing; catchword from preceeding page is fortie
• Page cut off
• gap in inking; missing letter obvious from context

<supplied> appears in Stow 1598, the Mayoral Shows, and Other Texts. It appears 207 times.

@reason is available on four distinct elements: <gap>, <supplied>, <surplus> and <unclear>, with slightly different definitions and different suggested values. One thing we should consider is whether we also need to use @reason on the other elements, and create value lists for them. But in the meantime, this is my suggested list of values to cover the above cases. Note that this excludes information about the source of what is supplied; that should be done with @evidence and @source. We're trying to give the reason that something was or had to be supplied.

Notes:

• "EEBO transcription gap" is not a reason for supplying something. We are not doing an edition of an EEBO/TCP text; we're doing our own edition. If TCP encoders missed something, we should silently correct it. We are only starting from the TCP transcription as a convenience; we do not treat them as an authority, nor do we expect them to be correct.
• "letters missing in the EEBO transcription. Proofed against David Bergeron's critical edition" shows two issues; the first is described above, but the second suggests that we did not even consult the facsimile. The process should be: consult the facsimile; if it's not clear, try to supply something (@reason="unclear"), and then explain the source of the correction using @source and/or @evidence.
• "new page; catchword euer on previous page" presumably means that "euer" is missing from the facsimile (@reason="omitted-in-original") and we restored it based on the catchword (@evidence="internal").

Any more detail should be converted into an editorial note. So the fact that, for instance, we restored a missing word based on a catchword on the preceding page should be explained in a note. All the existing @reason values can be converted into notes automatically.

I suggest that external sources for supplied text always be specified using @source pointing through a mol: URI at their <bibl>; that a <bibl> must be created if the document isn't yet in the bibliography; and that we use the three recommended values for @evidence from the Guidelines:

• internal
• external
• conjecture

although of course we may add to these in the future.

SM has raised an important issue where we appear to be following bad practice, and have even documented it in out praxis (http://mapoflondon.uvic.ca/encoding_primary_sources.htm#encoding_primary_sources_supplied_text). The example for <supplied> here looks like this:

<supplied resp="mol:JENS1" reason="gap in inking; missing letter obvious from context">i</supplied>

However, the @reason attribute is not an open text attribute allowing for a prose description like this; it's a sequence of one or more data.word values, each of which must be a standalone item with a meaning and no spaces, like these from the spec:

• overbinding
• faded-ink
• lost-folio
• omitted-in-original

If we are going to use @reason, we should formalize a list of defined values and build them into our schema, along with proper documentation, so that we're all speaking the same language.

We certainly shouldn't use @reason to say where the correction came from. @source and @evidence are what we should use for that: http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-att.editLike.html. @evidence is data.enumerated, with some suggested values, but open for the use of more; I would suggest that we specify the other values we intend to use, and close the list, so again we all stay within bounds. (We can extend the list at any point when necessary.)

@source is one or more data.pointers, so it can be used to point to one of our <bibl> entries using the normal mol: prefix. However, the Guidelines specification contains a remark which I believe to be overly restrictive; it says the value is:

"A space-delimited series of sigla; each sigil should correspond to a witness or witness group and occur as the value of the xml:id attribute on a witness or msDesc element elsewhere in the document."

I think there should be no requirement that @source point at an internal element, and I have raised this as a bug. Meanwhile, I suggest we use it to point to <bibl>s as we wish; the prose description is not enforced by any schema constraint AFAIK.

So I think what we need to do is:

1. Decide on a valList for @reason, based on what we believe we need and all existing uses of the attribute, and implement it in the schema.
2. Fix all existing instances of @reason which don't conform.
3. Decide on a valList for @evidence, based on what we believe we need and all existing uses of the attribute, and implement it in the schema.
4. Fix all existing instances of @evidence which don't conform.
5. Check all existing values of @source to make sure they make sense.
6. Update our Praxis documentation to exemplify our new practice.

We have a few dozen linked names with no entries in the dbs yet, due to vagaries of the workflow, and some of these happen to be in already-published documents. I've tweaked the error message so it's more promissory and less computer-errory.