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
 hi,
    I actually think that pretty much all of a "spec" should be normative.  That doens't mean Mandatory = so don't confuse the two.
    Even examples should be "normative" -  i.e. they are correct according to the spec.

   I would leave non-normative/informative docs to things like primers, etc. which are clearly labelled.

  Also, OASIS is about to approve (actually the board already approved it, but we are working out some IPR issues before officially issuing it), an "informational doc" track for documents that want to have a TC stamp of approval, but aren't specs.

  cheers,
   jeff

Jeff Mischkinsky                                jeff.mischkinsky@oracle.com
Director, Web Services Standards      +1(650)506-1975
Oracle Corporation                             500 Oracle Parkway M/S 4OP9
                                                        Redwood Shores, CA 94065



From Martin Chapman <martin.chapman@oracle.com>
Sent Fri 12/14/2007 8:46 AM
To 'Mike Edwards' <mike_edwards@uk.ibm.com>
Cc 'Anish Karmarkar' <Anish.Karmarkar@oracle.com>; 'Michael Rowley' <mrowley@bea.com>; opencsa-liaison@lists.oasis-open.org
Subject RE: [opencsa-liaison] Use of "may", "must", etc.

Issue 6 was easy to reword, and IMHO reads well.
What I don't want to see is switching between normative and informative on a paragraph by paragraph basis!
I think we are looking at a problem that doesn't really exist.
 
Martin.
-----Original Message-----
From: Mike Edwards [mailto:mike_edwards@uk.ibm.com]
Sent: Wednesday, December 12, 2007 5:48 PM
To: Martin Chapman
Cc: 'Anish Karmarkar'; 'Michael Rowley'; opencsa-liaison@lists.oasis-open.org
Subject: RE: [opencsa-liaison] Use of "may", "must", etc.


Martin,

My suggestion is that by limiting the extent of normative sections the amount of work to get the normative text
in shape will be that much less.

This is largely a debate about the amount of work to do.  The more text, the more work.  After our experiences
with Issue 6 in Assembly, I'm minded to keep the extent of normative text to the absolute minimum.


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



"Martin Chapman" <martin.chapman@oracle.com>

12/12/2007 17:31

To
"'Michael Rowley'" <mrowley@bea.com>, "'Anish Karmarkar'" <Anish.Karmarkar@oracle.com>, Mike Edwards/UK/IBM@IBMGB
cc
<opencsa-liaison@lists.oasis-open.org>
Subject
RE: [opencsa-liaison] Use of "may", "must", etc.





I really don't know what to suggest here. However big or small a normative section is, we will still have to find alternatives for must, may, should etc.
 
Martin.
 
-----Original Message-----
From:
Michael Rowley [mailto:mrowley@bea.com]
Sent:
Tuesday, December 11, 2007 4:14 PM
To:
Martin Chapman; Anish Karmarkar; Mike Edwards
Cc:
opencsa-liaison@lists.oasis-open.org
Subject:
RE: [opencsa-liaison] Use of "may", "must", etc.

 
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 Park,  NC
> +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 Park,  NC
>  > > +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
 






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








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