[tei-council] Proposed changes to "Gentle Introduction"

[Syd Bauman]

> 1. Statement on schema connectors
> PROPOSED CHANGE:
>   Change "possible connectors" to "commonly used connectors", and add a
>   note reading, "The RELAX NG compact syntax allows, in addition to
>   these DTD connectors, an ampersand (&) for 'interleave'. It is like
>   the comma connector but allows items in the sequence to appear in
>   any order.

I am (strongly) in favor of the change overall, but think that the
last sentence of the proposed note needs to be improved. The problem
is that the sentence describes the 'and' connector of XML DTDs, not
the 'interleave' connector of RELAX NG, which has further nuances.
(It allows sub-elements of interleaved groups to occur in any order,
not just the groups -- I'm not sure I'm describing that right; see
http://books.xmlschemata.org/relaxng/relax-CHP-6-SECT-2.html.) It
either needs to explain interleave more fully, or at least admit that
it doesn't (in which case we should refer the reader to a full
explanation).


> 2. Incorrect description of mixed content rules
>     I would suggest simply deleting this paragraph and its attached
>     note, as they get into arcana that go well beyond the introductory
>     level of this Guidelines section. 

My gut instinct is to relegate the entire discussion to a footnote: 

| <p>A group of this kind can contain <code>text</code> as well as named
| elements: this combination, known as <term>mixed content</term>,
| allows for elements in which the sub-components appear with
| intervening stretches of character data.
| <note place="foot">
| XML DTDs place constraints on the way that mixed content models may be
| defined. In brief, if <code>#PCDATA</code>, the DTD equivalent of
| <code>text</code>, appears with other elements in a content model:
| <list>
|   <item>it must always appear as the first option in an alternation,</item>
|   <item>it may appear once only, and</item>
|   <item>it must appear in the outermost model group.</item>
| </list>
| Furthermore, if the group containing it is repeated, the star operator
| must be used. The rationale for these restrictions is beyond the scope
| of this tutorial, as are the consequences of attempting to evade them.
| The TEI content models all obey these constraints.</note>
| For example, if we wished to
| mark place names wherever they appear inside our verse lines, then,
| assuming we have also added a pattern for  the
| <gi>name</gi> element, we could change the definition for
| <gi>line</gi> to <eg>line_p = element
| line { (text | name_p )* }</eg></p>


> 3. Incorrect statement on @xml:id
> PROPOSED CHANGE:
> 
>   (1) revise above to read "The @xml:id attribute is a special case,
>   because it is predefined in the XML language as containing a unique
>   value that identifies its parent element. This value may be used...",
>   etc.
> 
>   (2) Under "Identifiers and Indicators", at the end of the sentence
>   "XML therefore predefines an attribute...", add a note reading
>   "@xml:id is defined as a W3C Recommendation; see _xml:id Version 1.0_
>   [linking to http://www.w3.org/TR/xml-id/]

In general, I agree. I think perhaps the sentence in (2) should instead
be split in two at the colon, and the note should be attached to the
1st sentence resulting.


Unless there are objections, I am happy to effect these changes -- of
course, David, you may prefer to yourself.