This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 5720 - Inconsistent languge describing sml references and schemes
Summary: Inconsistent languge describing sml references and schemes
Status: RESOLVED FIXED
Alias: None
Product: SML
Classification: Unclassified
Component: Core (show other bugs)
Version: LC
Hardware: PC Windows XP
: P2 normal
Target Milestone: ---
Assignee: Virginia Smith
QA Contact: SML Working Group discussion list
URL:
Whiteboard:
Keywords: resolved
: 5710 (view as bug list)
Depends on:
Blocks:
 
Reported: 2008-05-28 18:51 UTC by Julia McCarthy
Modified: 2008-07-14 18:56 UTC (History)
2 users (show)

See Also:


Attachments

Description Julia McCarthy 2008-05-28 18:51:08 UTC
The specification uses a variety of apparenly inconsistent phrases to describe SML references, SML reference schemes, instances of SML reference schemes and their relationships.  

Here are a few examples:
Section 4.2: An SML reference (element with sml:ref='true') is an instance of an SML reference scheme 
Section 4.2.1 and 4.2.2: An SML reference contains an SML reference scheme 
Section 4.3: An SML reference is represented by reference schemes 
Section 4.1.3: "None of the recognized reference schemes resolves." 
Section 9.2.4: "sml:uri specifies an SML reference represented by the SML URI reference scheme" 

I think new readers would be greatly helped if we settled on consistent terminology to describe these concepts.
Comment 1 Julia McCarthy 2008-05-28 21:55:51 UTC
Ginny tells me that the workgroup discussed this language previouly and agreed to say an SML Reference is an instance of a reference scheme. Consitent use of this language would resolve my issue.

All places in the specification that use contraditory language need to be identified and updated.
Comment 2 Kirk Wilson 2008-05-29 12:00:09 UTC
While 4.1.1 needs to formally state/clarify the relationship between SML reference and SML reference scheme, as Julia has pointed out, the current definition of SML reference scheme,

An SML Reference Scheme is a set of rules defining the syntax used to represent an instance of the reference scheme in the context of an SML reference...

doesn't provide a basis for this relationship (besides being a bit of mind-twister--all it says is that a SML ref scheme defines what an instance of a the defintion is). The phrase "in the context of a SML reference" can mean anything, and thus it specifies nothing.   The word "instance" in the definition is not referring to the notion of an instance of an SML reference scheme; thus, the spec uses "instance" in one context in the definition of SML ref scheme and we are proposing to use it another context for the explanation of the relationship between SML Ref and SML ref scheme.

I would suggest defining "SML Ref scheme" along the following lines:

An SML ref scheme is a set rules that define XML markup for a mechanism for expressing(/representing ?) an (instance of an ?) SML reference....  The instantiation, or XML markup, of a SML ref scheme may be specified as either an attribute or child element of an SML Reference.  
Comment 3 Virginia Smith 2008-05-29 15:09:21 UTC
Proposal:

1- Expand section 4.1.1 (definition of an SML reference) to include some text about reference schemes as follows:

An SML reference is considered to be an instance of a specific SML reference scheme, if it can be identified as such according to the SML reference scheme rules. See [link to 4.3]. An SML reference MAY be an instance of multiple SML reference schemes.

2 - In section 4.1.3, change bullet 2 ("None of the recognized reference schemes resolves to an element in the model.") to "None of the reference schemes, of which the SML reference is recognized as an instance, resolves to an element in the model."

3 - In section 4.2.2, change "If a non-null SML reference contains multiple reference schemes" to "If a non-null SML reference is an instance of multiple reference schemes". Make similar change to all uses of "contains".

4 - Change the 1st 2 paragraphs in section 4.3 to the following (changes in **):
An SML reference MAY be *an instance of* a variety of reference schemes. SML does not mandate the use of any specific reference schemes. An SML reference scheme MAY use child elements, attributes, both, or neither to capture the information necessary to identify the reference target. It is not required that all elements in an SML model be reachable via an SML reference. This will depend on the support defined by the chosen reference scheme.

Although SML does not require the use of any specific scheme, it does specify how a reference MUST be represented when using SML-defined reference schemes. This specification defines the 4.3.1 SML URI Reference Scheme for *use* in SML references.

5 - Section 9.2.4 (non-normative) - Change "Specifies an SML reference represented by the SML URI reference scheme." to "Specifies an SML reference that is an instance of the SML URI reference scheme."

6 - In the definition of SML Reference Scheme: Change "An SML Reference Scheme is a set of rules defining the syntax used to represent an instance of the reference scheme" to "An SML Reference Scheme is a set of rules defining the syntax used to identify an instance of the reference scheme"

7 - Review doc to see if there are other locations that should be changed similar to the above changes.
Comment 4 Julia McCarthy 2008-05-29 20:11:26 UTC
+1 to points 1-5 and 7 in Ginny's comment #3. 

For point 6, would "create" work better than "idenify"? i.e. "An SML Reference Scheme is a set of rules defining the syntax used to crete an instance of the reference scheme" instead of "An SML Reference Scheme is a set of rules defining the syntax used to identify an instance of the reference scheme".
Comment 5 Virginia Smith 2008-06-05 18:27:54 UTC
Resolution: fix per comment #3 and #4; mark needsReview when done.
Comment 7 John Arwe 2008-06-16 15:44:46 UTC
4.2.5 
then model processors MUST NOT [attempt to recognize any reference schemes in it and MUST NOT] attempt to resolve it.

The portion enclosed in [] was deleted according to the diff.  It should not have been.  Since we still use "recognize" in the context of ref schemes (4.2.1, 4.2.2) I tend to think the deletion was accidental.  
Proposal: restore the text in []

4.1.3 the new clause in item 2 (between the commas) is pretty tortured.
from (with context):
An SML reference is unresolved if and only if all of the following is true:

   1.       It is a non-null SML reference.
   2.      None of the recognized reference schemes , of which the SML reference is recognized as an instance, resolves to an element in the model.

Proposal: replace 2 with
2. None of the reference schemes the SML reference is recognized as using 
                              resolves to an element in the model.

The rest looks fine.
Comment 8 Virginia Smith 2008-06-19 00:03:10 UTC
+1 with the following editorial changes:

4.2.5 new text:
...then model processors MUST NOT attempt to recognize any reference schemes used in it.

4.1.3 new text:
None of the reference schemes, which the SML reference is recognized as using, resolves to an element in the model.
Comment 9 Virginia Smith 2008-06-19 18:17:56 UTC
*** Bug 5710 has been marked as a duplicate of this bug. ***
Comment 10 Virginia Smith 2008-06-19 19:00:43 UTC
Resolution 6/19: Fix per comment #8. No needsReview necessary.
Comment 11 Virginia Smith 2008-07-14 18:56:38 UTC
Fixed per comment #10.