[tei-council] Bug 3064182

[James Cummings]

In looking at Bug 3064182 where I promised to go through all those 
attributes who use xsd:anyURI to see where we unnecessarily say that the 
attribute needs to point 'in the document' and similar prose restrictions.

I've started with those that are data.pointer (After putting in another 
bug that data.code really shouldn't be xsd:anyURI). The change to 
xsd:anyURI means they can easily point externally to the document, but 
often for legacy reasons we specify in the document, or a specific 
element.  This might not be desired in all cases, but in many cases one 
could make a use-case argument for storing whatever information is being 
pointed at in an external document.

In some cases the Guidelines specify that the element pointed at *must* 
be X. I'd like to suggest that it is more flexible if in some of these 
cases we introduce the possibility of pointing elsewhere.  In many cases 
in the guidelines we say that an attribute 'typically' points somewhere 
as a way to not limit ourselves so closely.  If we look at locus/@scheme 
it says "A pointer to some foliation element which defines the foliation 
scheme used, or an external link to some equivalent resource." and that 
seems like a good degree of flexibility in 'some equivalent resource' 
that we can use elsewhere.

Below I ask some questions of specific instances where there are changes 
in the specification of class and element provision of data.pointer. 
After I get some input on these I'll go through every single element 
that is a member of these classes and check the prose of the Guidelines 
where they are described as well.

Classes:

att.ascribed/@who
Value note says "For transcribed speech, this will typically identify a 
participant or participant group; in other contexts, it will point to 
any identified person element."
- Query: While a person element is preferred surely we should allow 
pointing to other non-person-element sources of information. (e.g. a 
controlled vocabulary URI, a linked data URI, a wikipedia article)?
Recommendation: Add 'typically' before 'it will point to'

att.canonical/@ref
Value note says: "The value must point directly to one or more XML 
elements by means of one or more URIs, separated by whitespace. If more 
than one is supplied, the implication is that the name identifies 
several distinct entities."
- Query: Is it a requirement that this point to an XML element? Again, 
author/@ref might point to all sorts of URIs? Like, for example, name 
authority files, wikipedia, etc.


att.damaged/@hand
Value note says: "must be one of the hand identifiers declared in the 
document header"
- Query: Could be a hand identifier in another document, or other remote 
information documenting this hand.
Recommendation: Add 'typically' before 'declared'

att.editLike/@source
Value note says: "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."
- Query: Like hands, witnesses could profitably be documented in 
separate files.
Recommendation: Rephrase to say "A space-delimited series of URIs 
pointing to a description of the source, typically the @xml:id of a 
witness or msDesc element"

att.global/@rendition
Desc note says: "Each URI provided should indicate a rendition element 
defining the intended rendition in terms of some appropriate style 
language, as indicated by the scheme attribute."
- Query: is it a requirement that this attribute only point to rendition 
elements rather than potentially other web resources that provide 
rendition information?

att.lexicographic/@location
Desc and value notes say: 'elsewhere in the document' and 'elsewhere in 
the current document'
Recommendation: add 'or an external file'

att.naming/@nymRef
Notes specify: "The value must point directly to one or more XML 
elements by means of one or more URIs, separated by whitespace. "
- Query: Should this only be limited to XML elements? I.e. What about 
other URI-based resources that document the canonical format of the name.
Recommendation: rephrase as 'point directly to one or more records of 
canonical format of names, typically a nym element in this document or 
an external file.'

att.rdgPart/@wit
Spec says: "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 element elsewhere in the document."
Recommendation: rephrase as att.editLike/@source above.

att.responsibility/@resp
Spec says: "A pointer to an element in the document header that is 
associated with a person asserted as responsible for some aspect of the 
text's creation, transcription, editing, or encoding."
Recommendation: rephrase start as "A pointer to a description of the 
person asserted as responsible for [...] encoding, typically in the 
document header".

att.textCritical/@wit
Spec says: "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 element elsewhere in the document."
Recommendation: rephrase in line with att.rdgPart/@wit and 
att.editLike/@source above.  (And one day find a solution to make these 
all part of the same class...)

att.textCritical/@hand
Spec says: "must be one of the hand identifiers declared in the document 
header"
Recommendation: Rephrase as "Points to documentation of the hand 
responsible, typically a <handNote> in the document header.

att.transcriptional/@hand
Spec says: "must refer to a handNote element, typically declared in the 
document header"
Recommendation  rephrase as att.textCritical/@hand above to remove the 
requirement that this necessarily be a handNote element.

alt/@targets (deprecated)
Spec says: "Each value specified must be the same as that specified as 
value for an xml:id attribute for some other element in the current 
document."
Recommendation: add 'or an external resource'

Elements:
app/@to
Spec says: "This attribute is only used when the double-end point method 
of apparatus markup is used, with the encoded apparatus held in a 
separate file rather than being embedded in-line in the base-text file."
- Query: In the reverse of what I'm saying elsewhere this presumably 
could be in a separate location but in the same file?
Recommendation: rephrase to 'typically held'

event/@place
Spec says: "indicates the location of an event by pointing to a place 
element"
- Query: Only a place element? Other use-cases might be to point to 
other URI-based resources which aren't places, e.g. wikipedia article on 
the place. Obviously, a place element is preferred.
Recommendation: rephrase 'by pointing to a definition of the place, 
typically a place element'.

gap/@hand
Spec says: "must be one of the hand identifiers declared in the document 
header"
- Query: If we c.f. handShift/@new it says "must refer to a handNote 
element, typically declared in the document header"
Recommendation: add ', typically' or rephrase as a

gloss/@cRef
Spec says: "should be a valid URI reference that resolves to a term element"
- Query: Similarly, this could point to a dictionary entry at the end of 
other URIs.
Recommendation: 'that typically resolves'

nym/@parts
Spec says: "1–100 occurrences of data.pointer separated by whitespace"
- Query: Many other elements have 1-infinity...why is this one so 
limited? (Ok, who has over 100 name parts but still seems arbitrary...)

occupation/@scheme and occupation/@code and socecStatus/@scheme and 
socecStatus/@code
"must identify a taxonomy element" and "must category a taxonomy element"
- Query: Are these necessarily 'musts'? It strikes me that 
occupation/@code and similar could point to other XML resources online 
that detail the occupation or similar.

respons/@resp
Spec says: "a pointer to one of the identifiers declared in the document 
header, associated with a person asserted as responsible for some aspect 
of the text's creation, transcription, editing, or encoding"
Recommendation: rephrase as att.responsibility/@resp

space/@resp
Spec says "a pointer to one of the identifiers declared in the document 
header, associated with a person asserted as responsible for some aspect 
of the text's creation, transcription, editing, or encoding"
Recommendation: rephrase as att.responsibility/@resp

tagUsage/@render
Spec says: "an identifier specified as the value of the xml:id attribute 
on some rendition element in the current document."
Recommendation: 'typically on some'

term/@cRef
BUG NOTE: At 
http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-term.html the 
french values note appears as well.
Spec says: "the result of applying the algorithm for the resolution of 
canonical references (described in section 16.2.5 Canonical References) 
should be a valid URI reference that resolves to a gloss element"
- Query: Do we want this to only ever point to gloss elements?

unclear/@hand
Spec says: "must be one of the hand identifiers declared in the document 
header"
Recommendation: rephrase as per att.textCritical/@hand above

I realise some of those are straightforward and some of those we 
probably don't want to change. I thought before starting that these 
would be simple adding the word 'typically' where it says 'in the 
document', and that is true of some of these, but not all. The others 
you can tell me I'm being ridiculous about.

-James

-- 
Dr James Cummings, InfoDev,
OUCS, University of Oxford