[tei-council] chapter ST

[James Cummings]

Sebastian Rahtz wrote:
> I'd like to see two chapters
> 
>  a) this is how the TEI works, as a set of modules; this is how you use
> these modules in anger
> 
>  b) global facilities: attributes, datatypes, classes
> 
> I think the Guidelines can only benefit from shorter more focussed
> chapters.

Lou,

I've finally had a chance to read this as well and would start by echoing
Sebastian's comments.  Specifically I think 3.3 (Global Attributes) and 3.5
(Datatypes) could be moved to another place (whether another chapter, a chapter
of their own or at worst to just after 3.7).  I'm less bothered about moving the
 discussion of the Class System (3.6) but if, as Sebastian suggests this was
separated into a separate chapter, then it would make sense.

Other comments that occurred to me as I read:

- The second and third paragraph are some of the most important in the chapter
for users trying to understand the whole infrastructure and how it works.
Although the Guidelines seem to be positively anti-diagrams, I think that some
form of structural diagram or image which explains the relationship between TEI,
schemas, modules (core and otherwise), classes, macros, datatypes, elements and
attributes, would really help at this point.  I can't think of what such a
diagram would look like, but it would form a good reference for inexperienced
users to look back on while reading the chapter.  ("So this is a 'macro', what
was one of those again?"...look at diagram..."oh yeah.")

3.1 - terminology module doesn't appear to be defined anywhere in the list of them

3.2 p[2]: "As previously noted, the TEI provides an application independent way
of specifying the components of a TEI schema by means of the <schemaSpec>
element defined in..."  Erm, it hasn't been previously noted in this chapter
that one can do it with the <schemaSpec>.  The concept is mentioned, but this
sentence to me makes it sound like you've already described how to use this
element to do so (which is just coming up).  Perhaps "TEI schema. This is done
by means of..."

3.2 p[2]: For some reason the sentence "A running XML system, such as a
validating editor, may use this specification in several different ways:"
bothers me.  Firstly, the 'running XML system'... although correct and less
problematic than 'application' still seems confusing to the novice user.
Secondly, the validating editor isn't producing the schemas mentioned in the
list which follows, so the first point seems confusing.

3.2 DOCTYPE example: Is the dtd for TEI P5 really going to be called tei2.dtd?
If so, why?!

3.2 3rd list Second list item "a definition of composite texts which comprise
front matter, a group or several possible nested groups of collected texts,
themselves possibly composite..."  Should mention of back matter be made here
(since front matter is mentioned).

3.3 Mention of 'TEIform' even though it isn't in the list of att.global being
discussed.

3.4 Elements defined: ____ (Blank).  Are there no elements defined in the tei
module available to all TEI modules, or is it that this chapter is defining
these or some such and so at this point they aren't yet defined?  If the latter
then this needs to be faked then to produce an actual list of elements defined
in the 'tei' module which are available to all TEI modules.

3.6 p[1] "A class is known as an attribute class if its members share attributes
, and as an model class if its members appear at the same locations in the
content models of other TEI elements."  1) Should that be 'a model class'? 2)
This is a confusing description of what a model class is, the explanation from
3.6.2 is much more understandable!


3.6.3 All the model.nameLike=notAllowed ... although you have explained
notAllowed way back in 3.4, it would be really helpful to see the default of
what should be allowed even if it hasn't been declared at this point.  (i.e.
what is the point of telling a novice user "model.nameLike = notAllowed" or
"model.phrase = notAllowed" it isn't really helpful to them.


3.8 Any benefit in hiving off DTD-specific mechanisms discussion to a separate
location?


Hope that is of any help,

-James