I think you may be misunderstanding a crucial issue here Martin. An ODD does two things. It defines the elements which are available, and it documents how to use them. Simple currently makes all the header and all the transcr module elements available, and therefore in my view should document how to use them. It could perfectly easily not include them all, while still "pointing to the full Guidelines for more complex cases". (In fact, that's what TEI Lite already does). But at some point you Simple-tons decided that wasn't good enough, and bunged the whole shooting match in willy nilly. If you think biblStruct is out of scope, then it should not be available from the TEI Simple schema at all, though of course there's every reason to alert people to its existence in other ways. On 31/05/16 18:51, Martin Mueller wrote:

I'm puzzled by the inclusion of the transcr model. My understanding throughout the project has been that Simple constrained the descendants of text. facsimile and sourceDoc have always been out of scope.

I don't have much wisdom on the question of the header. I could imagine the Simple documentation including a recommended list of basic items, but pointing to the full Guidelines for more complex cases. It may be that the Best Practices folks would have some useful advice.

My hunch is that biblStruct is outside of Simple's scope. particDesc is another matter.

MM

Martin Mueller Professor emeritus of English and Classics Northwestern University

On 5/31/16, 06: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.

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>