[tei-council] review of IM

[Lou Burnard]

OK, I have now spent 3 hours working through this list. 10/10 for 
providing useful comments, absolutely no marks for timing!

I've commented below only where I didn't do exactly what you suggested. 
Mostly.


Syd Bauman wrote:
> It's not clear to me that this section needs to be in the Guidelines
> at all. (It's very clear that it needs to exist -- it is important
> documentation.) It is currently part of the chapter "Using the TEI",
> but really has very little to do with _using_ the TEI. It is probably
> better positioned as an appendix.
>
>   
Not a very helpful suggestion at this stage of the proceedings, as 
others have remarked.


> The entire section does not mention the inclusion of Schematron rules
> in an ODD, nor their extraction.
>   
Work for 1.1 I think
>
> * #IM/p[1]: At the moment, the second word should be "section" not
>   "chapter". However, as I say above, I think maybe it should be
>   "appendix", if anything.
>
>   
First para revised. Removed a sentence which referenced NH !



> * Passim: very often the adjectival "firstly", "secondly", and
>   "thirdly" are used where I think we usually use "first", "second",
>   and "third".
>   
I can't find any non-adjectival uses of "first" "second" etc. And I find 
"firstly"  "secondly" used in four different chapters, so I am not 
planning to change this

> * #IM/p[4]: deserves a re-write; here's a starting point:
>       <p>An ODD processor is not mandated to perform these two stages
>       in sequence, but this may well be the simplest approach. The
>       ODD processing tools provided by the TEI Consortium and used to
>       process the source of these Guidelines take this approach.</p>
>
>   
OK: I've reworded this and preceding para:

<p>An ODD processing system has to accomplish two main tasks. A set of
selections, deletions, changes, and additions supplied by an ODD
customization (as described in <ptr target="#MD"/>) must first be
merged with the published TEI P5 ODD specifications. Next, the
resulting unified ODD must be processed to produce the desired outputs.</p>

<p>An ODD processor is not required to do these two stages in
sequence, but that may well be the simplest approach; the ODD
processing tools currently provided by the TEI Consortium, which are
also used to process the source of these Guidelines, adopt this 
approach.</p>


> * #IM-unified/p[1], 1st sentence, "... which specifies the name and
>   default namespace of the result.": I'm not sure what is meant by
>   "the name" (name of what? the schema? -- it doesn't have a name,
>   does it? the file that holds the schema? the identifier used to
>   refer to the schema?) or how it is specified (the ident=, I
>   presume?); it is not stated how the namespace is specified. Here is
>   a suggested re-work of what I think this sentence is trying to
>   convey. 
>       <p>Merging an ODD customization with the TEI P5 ODD
>       specification is driven by a <gi>schemaSpec</gi> element:
>       <specDesc key="schemaSpec" atts="ident ns"/> 
>       The <att>ident</att> attribute is required; it provides a name
>       for the generated schema. Other components of the ODD
>       processing system may use this name to refer to the schema
>       being generated, e.g. in issuing error messages or as the base
>       name of the generated output schema file or files. The
>       <att>ns</att> attribute may be used to specify the default
>       namespace within which elements valid against the resulting
>       schema belong, as discussed in <ptr ref="#MDNS"/>.
>   

I've included this, tho it is a bit repetitious, given that the specDesc 
will generate the same info
> * #IM-unified/p[1], 2nd sentence (pre-list): should perhaps a bit
>   more descriptive: "The main content of the <gi>schemaSpec</gi>
>   element consist of a series of specialized elements, in any order,
>   each of which falls into one of four types."
>   
Rewritten as

<p>The <gi>schemaSpec</gi> element contains an unordered series of 
specialized
elements, each of which is of one of the following four types:

> * #IM-unified/p[1]/list[1]: suggested revision follows. Note the PIs,
>   which indicate spots someone who underastands this process bettter
>   than I should check.
>
>   <list type="ordered">
>     <label>specifications</label>
>     <item>The TEI ODD specification elements <gi>elementSpec</gi>
I've adopted most of your rewording, but I am puzzled by the use of 
"<label> here. Is it meant to be a ordered list or a gloss list? I've 
assumed the latter.


> * #IM-unified/p[2]: 
>   - I don't believe the term "object" has been defined, and it should be
>   - insert "with the <att>key</att> attribute" between
>     "<gi>moduleRef</gi>" and "must"
>   - in the list, the values of mode= are mis-encoded as <att> instead of <val>
>   - the list says what do do with objects of same ident= when mode=
>     is 'delete', 'replace', or 'change', but not 'add' (footnote 87
>     above notwithstanding -- it is too far removed from this list,
>     I'd say)
>   
added a clause saying it';s an error to add something that already 
exists (but not saying what you should do in such a situation)
> * #IM-unified/p[3], 2nd sentence, before the <list>: how about
>   "Each component could fall into one of four categories:"?
>   
OK
> * #IM-unified/p[3]/list[1]/item[1]: Last I knew, this included the
>   xml:id= attribute, with the result that you could not use an
>   xml:id= value in your customization that occurs on an object in the
>   TEI ODD specification (at least, if that module is included). I'm
>   wondering if xml:id= should be excluded from this rule, so that
>   other ODD processors may get around this restriction. Or does that
>   lead to madness?
>
>   
Not sure what you're proposing here
> * #IM-unified/p[3]/list[1]/item[3], parenthetical: missing ", and",
>   but moreover I'm uncomfortable with the loose use of "elements",
>   "macros", and "attributes" for "when the ODD processor is building
>   an element" or whatever. Would the following do?
>   
>         (<gi>equiv</gi>, <gi>desc</gi>, <gi>gloss</gi>,
>         <gi>exemplum</gi>, <gi>remarks</gi>, and <gi>listRef</gi> in
>         the specifications of elements or macros, and
>         <gi>datatype</gi> and <gi>defaultVal</gi> in the
>         specification of attributes)
>   

surely this ought to refer to the classes rather than to the elements? 
it does now.
> * #IM-unified/p[3]/list[1]/item[3], after parenthetical: insert
>   "occurrences" after "all".
>   
OK
> * #IM-unified/p[3]/list[1]/item[4]: "i.e." -> "e.g."; make
>   "attribute" plural:
>      <item>identified objects (i.e. those with an <att>ident</att>
>      attribute, e.g. <gi>attDef</gi> and <gi>valItem</gi>) are
>      processed according to their <att>mode</att> attributes,
>      following the rules in this list.</item>
>   It would be better, I think, to reword the whole list to use
>   singular subjects, e.g. "Each object which can occur ... is taken
>   
The list does need rewording: I've had another crack at it, and 
reordered it slightly.

>   ..." 
>
> * #IM-unified/p[4], sentence 2: Should we be pointing out that the
>    example demonstrates a non-conformant customization? In any case,
>    the term "element" should probably be more specific:
>       Consider this simple example of a non-conformant customization
>       to the <gi>p</gi> element:
>   
I think this is p[5] actually: rather than get into conformance issues 
here, I've simply said "modification"
> * #IM-unified/p[4], between the <egXML>s: s/affect/effect/; reverse
>   "not" and "to"; also probably good to expand "the att.typed class";
>   thus perhaps
>        The effect of making <gi>p</gi> a member if the <name
>        type="class">att.typed</name> class is to provide it with both
>        the <att>type</att> and <att>subtype</att> attributes. If we
>        want <gi>p</gi> <emph>not</emph> to have the
>        <att>subtype</att> attribute, ...
>   
already caught by arianna I think
> * #IM-unified/p[4], after 2nd <egXML>: change <code> to <tag>
>
>   
check

> * #IM-unified/p[6]: s/entire/entirely/; 
its not the novelty that matters, it's the completeness, so i changed to 
"completely"
> but moreover, why is it
>   easier to deal with multiple examples? 
>
>   
Probably because they're less confusing than multiple glosses. Have 
reworded the para anyway.

> * #IM-unified/p[7]: delete first comma; I'm not fond of the
>   "whether to take account of" construct. How about "<p>When
>   processing the content models of elements and the content of
>   macros, the processor has to decide whether to take deleted
>   elements into account or not."?
>
>   
OK, likewise the next few comments...

>
>   "is itself inside an <gi>zeroOrMore</gi> inside a <gi>group</gi>":
>   the "an" should be an "a".
>
>   
except that it's now aN <gi>rng:zeroOrMore</gi>  i think!


> * #IM-unified/p[8]: "flat set" is not explained. (I think it would
>   be good to explain it, but low priority.)
>   
Yes. I think it's not adding much.
> * #IMGS: In this section the voice switches from making the ODD
>   processor the active party ("an ODD processor must ...") and things
>   like "it will be necessary to remove" (what is that -- 'impersonal
>   passive'?) to the first person plural.
>
>   
Have revised this for consistency

>
> * #IMGS: In this section the `trang` program is encoded as an
>   <ident>; in the previous section Roma, I think it was, was not
>   encoded at all. I think that all references to programs, utilities,
>   commands, etc. should be encoded as <name type='pgm'>. (After all,
>   "trang" is the name of a program.)
>   
That's one consistency check I haven't done...
> * #IMGS/p[3]: if the rewrite of the beginning of para 2 is accepted,
>   #then this should be deleted.
>   
I dont see why

> * #IMGS/p[4], last sentence: is "Roma processors" (plural) correct?
>   Also, to anyone who has read a schema "in as simple a style as
>   possible" seems like an exaggeration. (E.g., much of the indirection
>   could be resolved -- not that I think this is a good idea, mind
>   you.) How about "in a comparatively simple style"?
>   

I wonder if this para is a hostage to fortune: it says "the TEI project" 
(whatever that is) will generate both parameterized and non 
parameterized schemas, which I thought we'd decided we didn't want to 
guarantee.
 
> * #IMGS/p[5]/eg[1] and eg[2]: Since there is no markup in the
>   examples, the CDATA marked sections are superfluous.
>   
I think it's needed to stop the stylesheet filling and wrapping the lines
> * #IMGS/p[5] text in between the two <eg>: The idea that "the
>   knowledge that the attributes such as <att>n</att> and
>   <att>rend</att> come from the global attribute class is lost" seems
>   pretty counter-intuitive: everyone and anyone can see that n= and
>   rend= come from the global attribute class, because the patterns
>   used are named "att.global.n" and "att.global.rend". Here is a
>   suggested re-wording:
>     In the above, a redefinition of an attribute class will have no
>     effect, as each class has already been expanded to its
>     constituent attributes.
>
>   
Have revised this, hopefully clearer now!

> * #IMGS/p[5] text after the 2nd <eg>:
>   - change "class attributes" to "attribute classes", no?
>   - change "with a pointer" to "via a reference"
>
>   
do
> ** #IMGS/p[7], after <eg>s: I'm not fond of the wording here (no
>   reason not to use more precise industry-wide term "deterministic";
>   the last sentence makes it sound like it is a problem that RELAX NG
>   does not require determinism), but I think it is low priority and
>   can await 1.1, unless someone can re-word this a lot faster than I.
>
>   
I had a stab

> * IMGS/p[8], rest of para: Why are we recommending this only for
>   DTDs? Just because it is hard for us to do for RELAX NG doesn't
>   mean we should not recommend ODD processors do this.
>   
I'm confused didn't we discover that this was actually *illegal* for W3C 
Schema? so why are we doing it? I've commented that para out for now.

> * #IM-naming/head: how about "Names and Documentation in Generated
>   Schemas"? 
>
> * #IM-naming/p[1], sentence 1: insert Oxford comma after "element".
>
>   
yup. Did you know that Oxford's web site house rules have just banned 
the oxford comma? But I digress.

>   Note that this does not give advice on what to do when there are
>   two or more with the same value of xml:lang=. Fodder for a 1.1
>   improvement. 
>
>   
Have had a stab at that too!

> * #IM-naming/p[2]/list/item[2]: there is an exception: colons are
>   removed first, so that the namespace prefix and attribute name are
>   run together, as in 'att.global.attribute.xmlid'.
>
>   
i think this only applies to xml: though?


> * #IMCL/p[2]/egXML[2]:
>   - I expected to see an <a:documentation> element; am I crazy?
>   
No: it got lost in translation some versions back: it's back now

> * #ref-faith: probably would be good to come up with a more recent
>   image. 
>   
Done, I think
> * #STPE: This section deals with instructions on how to "stitch
>   together" the RELAX NG or DTD schema fragments into a usable
>   schema. My recollection is that Council decided this information
>   should not be included in the Guidelines themselves, so I am
>   recommending we delete the entire section, and I am not giving it a
>   closer reading.
>
>   

It has to go somewhere. I don't recall Council saying it should be 
excluded from the Guidelines entirely; only that it should be moved out 
of ST (which it has been). If you're doing anything with the XML DTDs 
you need to know about this stuff. Iff we remove support for XML DTDs, 
we can certainly remove it, but not (I fear) before.