Thanks for the quick response James. I dont think the arguments for retaining the whole header and the whole transcr modules hold water, I fear. It's not hard to identify a subset of the Header that would tally with most of what existing archives use. I know of no existing TEI Simple project using sourceDoc, nor do I expect to. Do you? OTOH if the metric is existing TCP texts, you defininitely dont need anything like the current insane overload of elements. If you "don't think a customization has to describe and document elements separately where the function of them is not restricted significantly from the full Guideline" then do you expect to see anything at all in this document (since Simple hardly constrains anything) ? Sorry if I didnt make clear that by "with spec" in my lists I meant "with a specDesc" i.e. with a prose description of what the element is for and possibly also an example. Obviously, if there is a processing model there has to be an (modified) elementSpec in the ODD, since we dont have any models in the Guidelines yet, but that's different. I would still like to know why Simple proposes bibl AND biblStruct AND biblFull. And how you'd advise people to choose which to use. On 31/05/16 13:30, James Cummings wrote:

Hi Lou,

Thanks for your efforts so far. As you know with the header the decision was made that Simple wouldn't specify one you had to have (to let the practices of all the different text archives etc. be allowed, and because it is hard). I didn't know there were so many transcr elements in there which seems weird to me. Presumably these are the ones allowed as descendants of <sourceDoc> (which like header I think Simple decided not to enforce any restrictions upon).

With regard to not changing the schema, I only wanted to not invalidate any of the Simple documents already out there, e.g. the TCP ones, and thought we should start with Simple schema as it is and then entertain notions of improving it.

About having something that says 'go see the guidelines', I'm perfectly fine with that. I don't think a customization has to describe and document elements separately where the function of them is not restricted significantly from the full Guidelines. Where that is the case, perhaps we should add these in.

But I don't mind this being a document which leads people into the Guidelines rather than one which is a standalone replacement for it. (I believe MartinM may favour the latter more than me.)

Similarly, I don't have a problem with elements having <model> but no elementSpec ... it is right that the schema have processing model information for elements that it doesn't modify in any way, no? Or am I misunderstanding? The ones which have specs but no <model> seem to be header related so I'm not worried.

-James

On 31/05/16 11:30, Lou Burnard wrote:

...

I am rather uncertain as to how to proceed in improving the reference documentation for TEI Simple. Bear with me as I try to explain why.

I believe that in a proper TEI ODD

(a) the document should describe all and only the elements provided by the schema (b) the schema should provide all and only a useful subset of the TEI, appropriate to the stated goals of the Simple project (one of which I believe is to serve as an entry point to the full TEI)

I claim that neither of these is currently the case. The schema actually provides a staggering 218 elements. Of these, 165 in total are provided by means of an <elementRef> within the ODD (the balance are all pulled into the schema by its inclusion of the whole TEI Header module). Looking just at those 165 [1] the current document provides both a specification (via a <specDesc>) which generally triggers some kind of example or discussion in the text and an intended processing model (via a <model>) for only half of them (80). There are 44 with neither specification nor model; 26 with models but no specification; and 15 with specifications but no model.

I am less concerned about the presence/absence of models (though it does seem slightly perverse to provide a model for an element we are not documenting) than the presence/absence of specifications. Where is the Simple user to go for help when they fire up oxyGen, find that an element "<foo>" is available, and wonder what it's for? Where are they to go when they want to know what's the difference between (say) bibl, biblStruct, and biblFull ? If the answer is "they have to consult the TEI Guidelines", that needs to be spelled out (and we maybe need to consider the follow up question "so what's the point of this document then?") .

This is acutely the case for elements from the Header and Transcr modules, which appear to have been simply bunged into the schema with no thought at all about how to describe or document their use.

I see no easy way out of this uncomfortable situation, short of my giving up on my unattainable desires, and handing the job over to someone else. James has already expressed concern that producing the documentation should not perturb the existing state of the Simple schema, so it looks as if each subsection of the document is going to need a coda or health warning along the lines of "The Simple schema also makes available the following elements which we do not describe here. [insert long list of specs]. Guidance on their usage should be sought in the TEI Guidelines. Good luck."

Is that something the Council can live with? Or should we simply say "the TEI Simple schema is here" and stash away in the Exemplars the <schemaSpec> element on its own? The alternatives are to add a LOT of documentation (takes time and effort); or remove a LOT of elements (risks annoying developers short term).

I have however made some progress on polishing up the introduction, which I suppose is something.

[1] Gory details follow.

The following 44 elements have neither spec nor model: <att> <biblFull> <biblStruct> <change> <charDecl> <charProp> <damage> <damageSpan> <email> <facsimile> <gi> <glyph> <glyphName> <imprint> <line> <listChange> <listPerson> <listTranspose> <localName> <metamark> <mod> <monogr> <msDesc> <msIdentifier> <person> <physDesc> <redo> <relatedItem> <repository> <restore> <retrace> <sourceDoc> <surface> <surfaceGrp> <surplus> <tag> <term> <textDesc> <transpose> <typeDesc> <undo> <val> <value> <zone>

The following 26 elements have models but no specs: <ab> <actor> <addrLine> <addSpan> <am> <castGroup> <castItem> <castList> <cb> <c> <desc> <ex> <floatingText> <formula> <fw> <g> <handShift> <measure> <postscript> <rhyme> <role> <roleDesc> <space> <spGrp> <subst> <supplied>

The following 15 elements have specs but no model: <biblScope> <body> <editor> <editorialDecl> <extent> <idno> <keywords> <licence> <publicationStmt> <resp> <respStmt> <sourceDesc> <teiCorpus> <textClass> <titleStmt>

And the following 80 have both specs and models: <abbr> <add> <address> <anchor> <argument> <author> <back> <bibl> <byline> <cell> <choice> <cit> <closer> <corr> <date> <dateline> <del> <div> <docAuthor> <docDate> <docEdition> <docImprint> <docTitle> <encodingDesc> <epigraph> <expan> <figDesc> <figure> <fileDesc> <foreign> <front> <gap> <graphic> <group> <head> <hi> <imprimatur> <item> <label> <lb> <l> <lg> <listBibl> <list> <milestone> <name> <note> <num> <opener> <orig> <pb> <pc> <p> <profileDesc> <publisher> <pubPlace> <q> <quote> <ref> <reg> <row> <rs> <salute> <s> <seg> <sic> <signed> <sp> <speaker> <stage> <table> <teiHeader> <text> <time> <title> <titlePage> <titlePart> <trailer> <unclear> <w>

The logical conclusion of this line of argument is that we should just say Use Tei All, isn't it? Sent from my Honor Mobile -------- Original Message -------- Subject: Re: [tei-council] TEI Not so Simple From: James Cummings To: tei-council@lists.tei-c.org CC: On 31/05/16 13:07, Lou Burnard wrote:

Thanks for the quick response James. I dont think the arguments for retaining the whole header and the whole transcr modules hold water, I fear. It's not hard to identify a subset of the Header that would tally with most of what existing archives use. I know of no existing TEI Simple project using sourceDoc, nor do I expect to. Do you? OTOH if the metric is existing TCP texts, you defininitely dont need anything like the current insane overload of elements.

Well it wasn't just the TCP -- I didn't want to try to redo Sebastian's analysis and rationalisation of all the files-- that is the key to my resistance with the header.

If you "don't think a customization has to describe and document elements separately where the function of them is not restricted significantly from the full Guideline" then do you expect to see anything at all in this document (since Simple hardly constrains anything) ?

The key word is _has_ -- the customization _can_ document whatever it feels is important... But I think we can use this to our advantage to lead people into the right bits of the Guidelines to read more about subject X. The elements in your list are those people are less likely to read lots about I think.

Sorry if I didnt make clear that by "with spec" in my lists I meant "with a specDesc" i.e. with a prose description of what the element is for and possibly also an example. Obviously, if there is a processing model there has to be an (modified) elementSpec in the ODD, since we dont have any models in the Guidelines yet, but that's different.

Sure, and whether or not we'll ever have models in the full Guidelines is a completely separate topic for discussion which we shouldn't raise now, IMHO.

I would still like to know why Simple proposes bibl AND biblStruct AND biblFull. And how you'd advise people to choose which to use.

I'm assuming it does this for use in the context of the header since they are all valid in sourceDesc then if it is sticking to its "you can do what you like in the header" idea, then that seems sensible. I'd only ever recommend something like <bibl> for TEI Simple IMHO. But that doesn't mean I want to outlaw others doing so if they really want. ;-) -James

On 31/05/16 13:30, James Cummings wrote:

...

Hi Lou,

Thanks for your efforts so far. As you know with the header the decision was made that Simple wouldn't specify one you had to have (to let the practices of all the different text archives etc. be allowed, and because it is hard). I didn't know there were so many transcr elements in there which seems weird to me. Presumably these are the ones allowed as descendants of <sourceDoc> (which like header I think Simple decided not to enforce any restrictions upon).

With regard to not changing the schema, I only wanted to not invalidate any of the Simple documents already out there, e.g. the TCP ones, and thought we should start with Simple schema as it is and then entertain notions of improving it.

About having something that says 'go see the guidelines', I'm perfectly fine with that. I don't think a customization has to describe and document elements separately where the function of them is not restricted significantly from the full Guidelines. Where that is the case, perhaps we should add these in.

But I don't mind this being a document which leads people into the Guidelines rather than one which is a standalone replacement for it. (I believe MartinM may favour the latter more than me.)

Similarly, I don't have a problem with elements having <model> but no elementSpec ... it is right that the schema have processing model information for elements that it doesn't modify in any way, no? Or am I misunderstanding? The ones which have specs but no <model> seem to be header related so I'm not worried.

-James

On 31/05/16 11:30, Lou Burnard wrote:

...

I am rather uncertain as to how to proceed in improving the reference documentation for TEI Simple. Bear with me as I try to explain why.

I believe that in a proper TEI ODD

(a) the document should describe all and only the elements provided by the schema (b) the schema should provide all and only a useful subset of the TEI, appropriate to the stated goals of the Simple project (one of which I believe is to serve as an entry point to the full TEI)

I claim that neither of these is currently the case. The schema actually provides a staggering 218 elements. Of these, 165 in total are provided by means of an <elementRef> within the ODD (the balance are all pulled into the schema by its inclusion of the whole TEI Header module). Looking just at those 165 [1] the current document provides both a specification (via a <specDesc>) which generally triggers some kind of example or discussion in the text and an intended processing model (via a <model>) for only half of them (80). There are 44 with neither specification nor model; 26 with models but no specification; and 15 with specifications but no model.

I am less concerned about the presence/absence of models (though it does seem slightly perverse to provide a model for an element we are not documenting) than the presence/absence of specifications. Where is the Simple user to go for help when they fire up oxyGen, find that an element "<foo>" is available, and wonder what it's for? Where are they to go when they want to know what's the difference between (say) bibl, biblStruct, and biblFull ? If the answer is "they have to consult the TEI Guidelines", that needs to be spelled out (and we maybe need to consider the follow up question "so what's the point of this document then?") .

This is acutely the case for elements from the Header and Transcr modules, which appear to have been simply bunged into the schema with no thought at all about how to describe or document their use.

I see no easy way out of this uncomfortable situation, short of my giving up on my unattainable desires, and handing the job over to someone else. James has already expressed concern that producing the documentation should not perturb the existing state of the Simple schema, so it looks as if each subsection of the document is going to need a coda or health warning along the lines of "The Simple schema also makes available the following elements which we do not describe here. [insert long list of specs]. Guidance on their usage should be sought in the TEI Guidelines. Good luck."

Is that something the Council can live with? Or should we simply say "the TEI Simple schema is here" and stash away in the Exemplars the <schemaSpec> element on its own? The alternatives are to add a LOT of documentation (takes time and effort); or remove a LOT of elements (risks annoying developers short term).

I have however made some progress on polishing up the introduction, which I suppose is something.

[1] Gory details follow.

The following 44 elements have neither spec nor model: <att> <biblFull> <biblStruct> <change> <charDecl> <charProp> <damage> <damageSpan> <email> <facsimile> <gi> <glyph> <glyphName> <imprint> <line> <listChange> <listPerson> <listTranspose> <localName> <metamark> <mod> <monogr> <msDesc> <msIdentifier> <person> <physDesc> <redo> <relatedItem> <repository> <restore> <retrace> <sourceDoc> <surface> <surfaceGrp> <surplus> <tag> <term> <textDesc> <transpose> <typeDesc> <undo> <val> <value> <zone>

The following 26 elements have models but no specs: <ab> <actor> <addrLine> <addSpan> <am> <castGroup> <castItem> <castList> <cb> <c> <desc> <ex> <floatingText> <formula> <fw> <g> <handShift> <measure> <postscript> <rhyme> <role> <roleDesc> <space> <spGrp> <subst> <supplied>

The following 15 elements have specs but no model: <biblScope> <body> <editor> <editorialDecl> <extent> <idno> <keywords> <licence> <publicationStmt> <resp> <respStmt> <sourceDesc> <teiCorpus> <textClass> <titleStmt>

And the following 80 have both specs and models: <abbr> <add> <address> <anchor> <argument> <author> <back> <bibl> <byline> <cell> <choice> <cit> <closer> <corr> <date> <dateline> <del> <div> <docAuthor> <docDate> <docEdition> <docImprint> <docTitle> <encodingDesc> <epigraph> <expan> <figDesc> <figure> <fileDesc> <foreign> <front> <gap> <graphic> <group> <head> <hi> <imprimatur> <item> <label> <lb> <l> <lg> <listBibl> <list> <milestone> <name> <note> <num> <opener> <orig> <pb> <pc> <p> <profileDesc> <publisher> <pubPlace> <q> <quote> <ref> <reg> <row> <rs> <salute> <s> <seg> <sic> <signed> <sp> <speaker> <stage> <table> <teiHeader> <text> <time> <title> <titlePage> <titlePart> <trailer> <unclear> <w>

-- Dr James Cummings, James.Cummings@it.ox.ac.uk Academic IT Services, University of Oxford -- tei-council mailing list tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council PLEASE NOTE: postings to this list are publicly archived