Misc. comments on XML Schema part 2

Here are some misc last call comments on XML Schema part two:

Numbers are section numbers.

1.4 Definition of constraints on schemas: 'conditions components must satisfy'
     -> 'the conditions that the components must satisfy'
     [there are other cases where adding a 'that' helps readers to
      parse the text]

General: The convention to use a double-s-like mark for chapter and section
     number is not explained at all, is not usual in W3C or other IT-related
     documents, and is not accessible.

2.2: 'The value space of a given datatype can be defined in one of
       the following ways:' -> 'The value space of a given datatype
       is defined in one of the following ways:'.

General: Citing style, for example 'related activities such as [XSL]',
       where the text in the [] has to be read, is not usual in any
       IT-related or other publications, and looks bad. Related:
       in 2.4.1.12: 'Section 6.8 [RFC 2045]' -> 'Section 6.8 of RFC 2045'.

2.4.1.1: 'A and B are not related by ,': by what?

2.4.1.3: Give a definition of <= in terms of ordering

2.4.2.2/3: length is measured in list items -> min/maxLength is measured
       in list items.

2.4.2.: It is unclear why all three of length/minLength/maxLength are needed,
       and how they relate. The spec should say here that length is provided
       only for convenience (or better, should remove 'length').

2.4.2: Repeating how lenght is calculated for each of the relevant datatypes
        is suboptimal. This belongs to each of these types.

2.4.2.9: 'value is itself excluded' -> 'value itself is excluded'

2.4.2.12: 'consisting the two hexadecimal digits' -> 'consisting of two...'
           'the entire binary stream is encoding' -> '... is encoded'.

3.3/4/5: The relationship between float, double, and decimal should
        be explained. Their value spaces (in the mathematical sense)
        overlap, and this will lead to confusion.

3.3/4/5: 'The order-relation on XXX is: x < y iff y - x is positive.'
        This is uselessly circular. It assumes that the reader will
        know which definition of subtraction is meant, while s/he
        doesn't know '<'. A more appropriate wording is something like:
        The order-relation on XXX is defined as the natural numeric
        ordering on the represented numbers.

3.2.12 Entity (also entities): The spec should explicitly mention
        that because XML Schema doesn't allow to define entities,
        the referential constraints on Entity-type attributes
        (see http://www.w3.org/TR/REC-xml#entname) cannot be enforced.

3.3.various: The wording 'XXX is derived from YYY by fixing the value
        of xxxYyclusive to be Z' or similar is used repeatedly. This gives
        the impression that further constraining/derivation may not
        be possible anymore. The wording should be changed to
        something like 'XXX is derived from YYY by adding a constraing
        facet of xxxYylusive=Z'.

3.3.8.2: Integer lists 'scale' as constraining facet. This gives the
        impression that 'scale' can be further constrained. This
        should be clarified, or 'scale' removed.

4.2.1 and others: 'where units of length varies depending on {base type
        definition}': depends also on {variety}.

In the Schema for datatypes, there is both '<complexType name="simpleType"'
        and '<element name="simpleType" equivClass="schemaTop"'.
        Using the same name for type and element is okay, but if it's
        used for different things, it's bad practice.

App. B, DTD: '<!Entity % simpleTypeAttrs ''>': This gives the impression
        that simpleType does not have any attributes. Change entity
        name to simpleTypeAttrExt or some such to avoid wrong impressions.
        Same for a lot of other enities.

App. E: The substructure of this section is hopelessly slanted.
        Please add subtitles and change the section numbering.

In section 5, avoid things such as:
        {value}   The value of the value [attribute].
        Such text is highly inaccessible, and even difficult to understand
        for the average reader.


Regards,   Martin.

Received on Tuesday, 30 May 2000 05:42:34 UTC