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>
