[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: Examples versus Contract Definitions
|
Then keep it simple… “The single biggest problem in communication is the illusion that it has taken place.”
– George Bernard Shaw.
From: obix@lists.oasis-open.org [mailto:obix@lists.oasis-open.org]
On Behalf Of Gemmill, Craig
OK, after reading Section 1.6, it seems that even the Contract Definitions are intended to be non-normative (surprise!), as they are really just an Example
instance of an object from the Schema definition. My earlier statements had assumed the contract definitions were normative, which is apparently incorrect. So, I’m seeing less of a problem with having both of these be in the same style, as they are both
non-normative. It does sort of elevate the need for the white paper about “Obix by Example”. I could put some note around the contract definitions to mark them as normative, but I think that would be unnecessarily confusing. From: Toby Considine [mailto:tobyconsidine@gmail.com]
On Behalf Of Toby Considine Well, you can check out the “code” style – but I think that is likely to be too subtle. My take: All examples are non-normative unless otherwise marked. And mark the ones you want to be normative. tc "There are seldom good technological solutions to behavioral problems "
-- Ed Crowley
From: Gemmill, Craig [mailto:craig.gemmill@tridium.com]
Toby, what do you think? I see his point, that there are some cases which are truly an example of usage of the rule, and not normative (such as the Brady Bunch references). But others
are intended to be fully normative like the contract definitions. What is the typical committee behavior in this case? Both of these are using the defined style named “XML”. You can see it clearly in 4.3.1.X, where we give the (normative) contract definition,
followed a line later by a (presumably non-normative) example usage. There is a style called “Code” in the document template that looks similar. I could change one usage or the other to use the “Code” style. I’m happy to add
a new style, with a different background color or something, but I want to stick within the OASIS guidelines. Or would this just be better as a PR comment that we can address then? Thanks Craig From:
obix@lists.oasis-open.org [mailto:obix@lists.oasis-open.org]
On Behalf Of Bertsch, Ludo Re: WD34 clean document.
Section 1.6, Lines 340-341 indicate that grayed boxes such as on Line 342 are to be used to show "Examples". Following that, the next three grayed boxes are in fact Examples: Lines 407-411, Lines 435-450, and Lines 476-491. However, the grayed box in Section 4.2, Line 580 is not an Example but is a Contract Definition. Following that, some of the grayed boxes are Examples, and some are Contract Definitions. Using the same type of grayed box for both Examples and Contract Definitions can lead to a lack of clarity and is especially confusing when grayed boxes were noted
to be used for Examples, but was not noted for Contract Definitions. It is suggested that a different type of box be used for Examples versus Contract Definitions to clarify the difference between the two, and to aid new readers
to understand the difference. This will help to identify Examples (versus Contract Definitions) when not specially mentioned, but implied, such as in Section 4.2.7.6, Line 666. This will also help with the understanding of the Lobby Contract Definition that
we have discussed in Section 5.1, Lines 886-893. Cheers, Ludo |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]