[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [opencsa-liaison] Use of "may", "must", etc.
I'd like to point to the XQuery
spec as an example of a good way of handling a formal specification in the
area of programming languages and models. It is one of the most formal
specifications I’ve ever seen – complete with the definition of rigorous
formal semantics. It uses terms such as “may” with their regular English
meaning throughout the specification. However, in one Conformance section,
it uses RFC 2119 language. It is precise about the bounds by including the
following sentence at the beginning of the section: “In this section, the
following terms are used to indicate the requirement levels defined in [RFC 2119].” I think this is better than having a distinction between upper and
lower-case terms, since 2119 explicitly says that the case of the terms doesn’t
matter. Michael -----Original Message----- > I think it is perfectly possible to write meaningful text without
using > RFC 2119 terms. Whether we want to spend the time doing this > wordsmithing across > the specs is the issue. I agree. I also want to comment on the use of 'MAY' in the 1st example. I think it is appropriate. On other SCA calls, comments have been made that 'MAY' is all about interop. If you look at RFC 2119, it may^h^h^hmight seem that way, but in most practical implementation cases, the interop part results in impl. just raising errors when they don't support the optional part. The more important part (to me) about 'MAY' is that: it is optional, you don't *have* to implement it, but if you do then you MUST follow all the rules that are defined. -Anish -- Mike Edwards wrote: > > Folks, > > OK, I'll bite on the challenge set by > full and certain knowledge that showing a solution for > just these two will not address the wider sea of cases spread
across all > the SCA specifications. > > 1) > I'd take this as being normative in the first instance. It is
stating > something testable - that a C++ service interface has an optional > annotation, that, when present, indicates that the contract
defined by > the interface is conversational. The target for the normative > statement is the interface document itself: > > "Service interfaces MAY be annotated to specify whether their
contract > is conversational, as described in the Assembly Specification
[ASSEMBLY], > using the @Conversational annotation." > > ...if you don't want the statement to be normative, then I would
cast it > as follows: > > "A @Conversational annotation is optionally applied to a C++
Service > interface to indicate that the service contract is conversational,
as > described in the SCA Assembly specification [ASSEMBLY]." > > 2) > I'm assuming that there is nothing normative here. > > "The data exchange semantics for calls to local services is > /by-reference/. This means that code needs to be written with the
> knowledge that changes > made to parameters (other than simple types) by either the client
or the > provider of the service can be seen by the other." > > > I think it is perfectly possible to write meaningful text without
using > RFC 2119 terms. Whether we want to spend the time doing this > wordsmithing across > the specs is the issue. > > Yours, Mike. > > Strategist - Emerging Technologies, SCA & SDO. > Co Chair OASIS SCA Assembly TC. > > Phone & FAX: +44-1962-818014 > Email: mike_edwards@uk.ibm.com > > > *Bryan Aupperle <aupperle@us.ibm.com>* > > 04/12/2007 20:41 > > > To > opencsa-liaison@lists.oasis-open.org > cc > > Subject > RE: [opencsa-liaison] Use of "may",
"must", etc. > > > > > > > > > > A couple of examples we have come across so far: > > Service interfaces may be annotated to specify whether their
contract is > conversational, as described in the Assembly Specification
[ASSEMBLY] > using the @Conversational annotation. > Note for C++, annotations are currently anticipated to be
processed by > tools so annotated source, in and of itself, does not force any
behavior > on anything other than a annotation processor. The conversational
> intent in the SCDL is what is meaningful. Thus use of
"MAY" is not > appropriate here. Replacing "may" with "can"
is not grammatically correct. > > The data exchange semantics for calls to local services is > /by-reference/. This means that code must be written with the
knowledge > that changes made to parameters (other than simple types) by
either the > client or the provider of the service can be seen by the other. > This is not really a compliance point (I would not expect a test
for it) > but clearly guidance to someone reading the specification
intending to > implement components. Removal or "must" is awkward and
other options > are wordier. > > > > Bryan Aupperle, Ph.D. > STSM, WebSphere Enterprise Platform Software Solution Architect > Master Inventor > > > +1 919-254-7508 (T/L 444-7508) > Internet Address: aupperle@us.ibm.com > > *"Patil, Sanjay" <sanjay.patil@sap.com>* > > 12/04/2007 10:34 AM > > > To > <ashok.malhotra@oracle.com>, > cc > <opencsa-liaison@lists.oasis-open.org> > Subject > RE: [opencsa-liaison] Use of "may",
"must", etc. > > > > > > > > > > > > If we did that (that is treat the terms in lower-case differently
from > their upper-case version), then our specs can not claim full
compliance > with RFC 2119, since RFC 2119 does not differentiate the key words
based > on their case. The problem with invoking RFC 2119 only for
upper-case > keywords would be that - we might be upsetting a lot of readers
out > there who have by now started expecting a full compliance with RFC
2119. > > > faced while substituting the RFC terms? Perhaps we can just
identify the > common situations of such awkwardness and try to come up with some > alternative terms that can be uniformly used by all the SCA specs. > > -- Sanjay > > > -----Original Message----- > > From: ashok malhotra [mailto:ashok.malhotra@oracle.com] > > Sent: Tuesday, Dec 04, 2007 6:32 AM > > To: Bryan Aupperle > > Cc: opencsa-liaison@lists.oasis-open.org > > Subject: Re: [opencsa-liaison] Use of "may",
"must", etc. > > > > Hi > > I agree that this is a problem. My alternate proposal is
that the > > upper-case words indicate the RFC 2119 keywords and the > > lower-case words > > indicate normal English usage. But not everyone likes this
solution. > > > > Bryan Aupperle wrote: > > > > > > > > I believe all of the TCs have adopted use of RFC 2119
keywords in > > > uppercase only and to not use the keywords in
lower-case > > form at all, > > > using synonyms when necessary. We have started
scrubbing > > the C++ spec > > > to eliminate use of "may", "must",
etc. and found that some rather > > > awkward language can result Has anyone else started
this exercise > > > and how are your results? > > > > > > Bryan Aupperle, Ph.D. > > > STSM, WebSphere Enterprise Platform Software Solution
Architect > > > Master Inventor > > > > > > > > > +1 919-254-7508 (T/L 444-7508) > > > Internet Address: aupperle@us.ibm.com > > > > > > > > -- > > All the best, Ashok > > > > --------------------------------------------------------------------- > > To unsubscribe from this mail list, you must leave the OASIS
TC that > > generates this mail. You may a link to this group and all > > your TCs in OASIS > > at: > >
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr > > oups.php > > > > > > > > >
------------------------------------------------------------------------ > > / > / > > /Unless stated otherwise above: > IBM United Kingdom Limited - Registered in > 741598. > Registered office: > > > > > > --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. You may a link to this group and all your TCs in
OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]