W3C home > Mailing lists > Public > www-xml-schema-comments@w3.org > April to June 2004

XML schema draft comments: 4.2.5.1, etc. wording pattern ambiguous, hard to follow

From: Daniel Barclay <daniel@fgm.com>
Date: Thu, 10 Jun 2004 17:25:27 -0400
Message-ID: <40C8D1C7.4000809@fgm.com>
To: www-xml-schema-comments@w3.org

Regarding the draft at
http://www.w3.org/TR/2004/PER-xmlschema-2-20040318/:

The form used to refer to properties of schema components seems
to be too compressed.  In at least one case, it also seems to
be wrong.


Section 4.2.5.1 says:

   ... {value} is inherited from {value} of {base type definition}.

Which value from a (base) type definition?  (And the base type
definition of what?)

Specifically, that second occurrence of "value" is ambiguous and/or
wrong.  A type definition does not have a property named "value."
A type definition does have facets that have "value" properties,
but that wording doesn't say which one.

(Clicking on the second "value" link does take one to the section
on the numeric facet (component?), which has a "value" property,
but the wording must stand on its own (should not depend on the
hypertext links).)

The wording should be expanded to say which value is being referred
to, perhaps as follows (roughly, since I don't know the right
terminology):

   ... {value} is inherited from {value} of the
   numeric facet (component?) of {base type definition}.



Actually, wouldn't the document be clearer if it were written with
normal English articles, etc., instead of the current non-standard
form?  For example, consider this rewording of the original:

   ... the value property is inherited from the value property
   of the base type definition

or, leaving in the special highlighting for property names but
still making everything else regular English, this mix:

   ... the {value} property is inherited from the {value} property
   of the {base type definition}

Note how it would be more obvious to authors that something is
missing.  (It's easier to notice that "the value property of the
base type definition" doesn't refer to anything valid.)

Notice how saying what named things are each time makes things
much clearer (e.g., "use x" vs. "use the command 'x'" or
"read xyz" vs. "read the xyz property").


Dropping what things are also introduces ambiguity.

Section 4.1.2 says (double quotes represent fixed-width font):

   ...
   {name}
      The actual value of the "name" [attribute], if present,
      otherwise null

and the text "[attribute]" is linked to the definition of attribute
information items.

Is it not clear whether that really means "attribute" or means
"attribute information item."  (Yes, they're related, but
have different defined properties, etc.)

If that really means "attribute information item," then it
should use those words and not just "attribute".  (If
the special highlighting is still desired, then either
"[attribute] information item" or "[attribute information item"
would do.)





Daniel
Received on Thursday, 10 June 2004 17:26:02 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 5 February 2014 07:15:34 UTC