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

[David Sewell]

Here I'm posting the two items related to SG-GentleIntroduction.xml that
I put in the Sourceforge tracker, plus an additional one.

1. Statement on schema connectors

PROBLEM: Section 5.3, "Connectors", states

    There are two possible connectors: the comma, representing sequence,
    and the vertical bar, representing choice.

While this is true of DTDs, it is not true of RELAX NG, the schema
language now used for illustrations in "Gentle Intro".

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.

2. Incorrect description of mixed content rules

PROBLEM: Section 5.3, "Groups", gives the following as an example of the
definition of an element with mixed content:

    line_p = element
    line { (text | name_p )* }

and goes on to say

    XML places constraints on the way that mixed content models may be
    defined. In brief, if text appears with other elements in a content
    model: it must always appear as the first option in an alternation;
    it may appear once only, and in the outermost model group; and if
    the group containing it is repeated, the star operator must be used.

That is true of XML DTDs, but not of RELAX NG schemas, so this is
technically an incorrect statement as it stands.

PROPOSED CHANGE:

    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. But if someone wants to argue for
    revision that preserves the basic information, go ahead...

3. Incorrect statement on @xml:id

PROBLEM: Section 5.5, "Attributes", has the wording

    The @xml:id attribute is a slightly special case in that, by
    convention, it is always used to supply a unique value to identify a
    particular element occurrence, which may be used for cross reference
    purposes, as discussed further below (Identifiers and indicators)

The passage in P4 was identical except with "id" instead of "@xml:id".
But, as discussed in the referenced section "Identifiers and
indicators", @xml:id is a predefined attribute now, and its ID datatype
is no longer conventional.

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/]

David

-- 
David Sewell, Editorial and Technical Manager
ROTUNDA, The University of Virginia Press
PO Box 801079, Charlottesville, VA 22904-4318 USA
Courier: 310 Old Ivy Way, Suite 302, Charlottesville VA 22903
Email: dsewell at virginia.edu   Tel: +1 434 924 9973
Web: http://rotunda.upress.virginia.edu/