OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

opencsa-liaison message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [opencsa-liaison] Use of "may", "must", etc.


Title: Message

 

If you look at that XQuery spec, you will see that only appendixes H, I and J are non-normative.  All other text in the spec is normative, except minor things that are explicitly marked as non-normative (such as namespace prefixes).

 

Michael

 


From: Martin Chapman [mailto:martin.chapman@oracle.com]
Sent: Monday, December 10, 2007 5:13 PM
To: Michael Rowley; 'Anish Karmarkar'; 'Mike Edwards'
Cc: opencsa-liaison@lists.oasis-open.org
Subject: RE: [opencsa-liaison] Use of "may", "must", etc.

 

One certainly could mark sections as informative and normative and make the RFC2119 rules apply only to normative sections, but I really don't see why we have to go through this. I have always been able to find a substitute, and I think with a bit of practice we can all get the hang of things. Maybe you can provide a sample that you think is not translatable and I'll try and write an equivalent. Otherwise I remain unconvinced.

 

Martin.

-----Original Message-----
From: Michael Rowley [mailto:mrowley@bea.com]
Sent: Monday, December 10, 2007 6:58 PM
To: Anish Karmarkar; Mike Edwards
Cc: opencsa-liaison@lists.oasis-open.org
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-----
From: Anish Karmarkar [mailto:Anish.Karmarkar@oracle.com]
Sent: Monday, December 10, 2007 3:48 AM
To: Mike Edwards
Cc: opencsa-liaison@lists.oasis-open.org
Subject: Re: [opencsa-liaison] Use of "may", "must", etc.

 

 

 > 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 Bryan for these two cases, in the

> 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.

> IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.

> Phone & FAX: +44-1962-818014    Mobile: +44-7802-467431 

> 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

>

> Research Triangle ParkNC

> +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>, Bryan Aupperle/Raleigh/IBM@IBMUS

> 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.

>

> Bryan, could you give us one or two examples of the awkwardness you

> 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 Bryan:

>  > 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

>  > >

>  > > Research Triangle ParkNC

>  > > +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 England and Wales with number

> 741598.

> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU/

>

>

>

>

>

>

 

---------------------------------------------------------------------

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]