[Bug 5099] sml section 4.1 References most text should be moved into other sections

http://www.w3.org/Bugs/Public/show_bug.cgi?id=5099

           Summary: sml section 4.1 References most text should be moved
                    into other sections
           Product: SML
           Version: unspecified
          Platform: PC
        OS/Version: Windows XP
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Core
        AssignedTo: cmsmcq@w3.org
        ReportedBy: johnarwe@us.ibm.com
         QAContact: public-sml@w3.org


4.1 is intended to be explanatory; its limited possibly normative statements
are already covered in other normative sections excepts as noted below.

Proposal: 

Excerpt 1: move to non-normative section
XML documents introduce boundaries across content that needs to be treated as a
unit. XML Schema does not have any support for inter-document references. SML
extends XML Schema to support inter-document references and a set of
constraints on inter-document references.

Support for inter-document references includes:

    *      Multiple addressing schemes for representing references.
    *      Constraints on the type of a referenced element.
    *      The ability to define key, unique, and key reference constraints
across inter-document references. 
An SML reference is a link from one element in an SML model to another element
from the same model. 

Excerpt 2: update as follows move to non-normative section
from
It can be represented by using a variety of schemes, such as 4.2.1 URI Scheme
and Endpoint References (EPRs) [WS-Addressing Core]. 
to
It can be represented by using a variety of reference schemes, including those
defined in this specification. 

Excerpt 3: delete, duplicates content already in 4.2
SML does not mandate the use of any specific scheme for representing
references; implementations are free to choose suitable schemes for
representing references.  

Excerpt 4: keep in 4.1, not covered elsewhere that I can see
References MUST be supported by model validators that conform to this
specification. 

Excerpt 5: delete, duplicates content already in 4.2
An SML reference MAY use one or more reference schemes.

Excerpt 6: delete, duplicates content already in 4.1.1.1
Reference elements MUST be identified by sml:ref="true" or sml:ref="1" where
sml:ref is a global SML attribute whose declaration is as follows:

Excerpt 7: delete, duplicates content already in schema
<xs:attribute name="ref" type="xs:boolean" />

Excerpt 8: reword and move to non-normative section
from
Although either sml:ref="true" or sml:ref="1" can be used to identify an SML
reference element, for the sake of brevity and consistency, the rest of this
specification uses sml:ref="true" in examples and other definitions.
to
Although its normative definition allows several syntaxes to be used to
identify an SML reference element, for the sake of brevity and consistency,
this specification uses sml:ref="true" in examples and text.

Excerpt 9: merge into 4.1.1.1, not covered elsewhere that I can see
An element that has sml:ref="true" MUST be treated as a reference element. 
Changing 4.1.1.1 content from
"An element information item in an SML model instance document is an SML
reference if and only if"
to
"An element information item in an SML model instance document MUST be treated
as an SML reference if and only if"
would be my approach.

Excerpt 10: move to 4.1.1.1, not covered elsewhere that I can see
This mechanism enables schema-less identification of reference elements, i.e.,
reference elements can be identified without relying on PSVI.

Excerpt 11: keep, (optionally under new non-normative h3 Reference Example)
from "The following example illustrates" to end of example just before "Null
references are different from empty references"

Excerpt 12: delete, should have been nuked when "empty ref" was excised
Null references are different from empty references. An empty reference is a
normal reference that just happen to be empty. For a null reference, the
content of that reference is intentionally left empty, as an explicit
declaration of intent from the document author that the reference must be
empty.

Excerpt 13: reword
from "...illustrates the use of sml:ref. Consider..."
to   "...illustrates the use of SML references. Consider..."

Excerpt 14: reflow so it is not truncated when printing
Example following "content model and this can be used to mark instances of
EnrolledCourse as reference elements as shown below:"
split the sml:uri value just before #xmlns

Excerpt 15: edit
from "...references are represented using         URI and EPR schemes,"
to   "...references are represented using the SML URI and EPR schemes,"

Excerpt 16: edit
from "...marked as a null reference if it defines the sml:nilref="true"..."
to   "...marked as a null reference if it specifies   sml:nilref="true"..."

Excerpt 17: edit
from "By setting  the reference null, the document author ..."
to   "By specifying a null reference, the document author ..."

Excerpt 18: edit to fix wildly incorrect current content
from "Student doesn't have an EnrolledCourse with a name PHY101 and grade A"
to   "Student element does not refer to any target element.  Specifying a null
reference does not have any SML-defined effect on the interpretation of element
in non-SML contexts.  In particular, in this case, SML says nothing about the
interpretation of the <Grade> and <Name> elements.  Any such interpretation is
left to the application, its usage context, other specifications, etc."

Received on Sunday, 30 September 2007 16:37:47 UTC