[OASIS Issue Tracker] Commented: (ODATA-381) Hanging paragraphs - all current csprd01 documents

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

    [ http://tools.oasis-open.org/issues/browse/ODATA-381?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=33384#action_33384 ] 

Stefan Drees commented on ODATA-381:
------------------------------------

I propose to not remove hanging paragraphs (if this is the English term for "text content of a section containing subsections") per se but instead provide more detail with the referers (where applicable) and only where natural, redistribute the content of the hanging paragraphs.
I further propose to resolve any obcious ambiguities stemming from a conformance reference to such a hanging paragraph alone on an individual basis.

We have at least two conflicting tasks, when specifying OData for reading implementers, service rpoviders and users alike: 
1) Map every construct (element, attribute, main concept, secondary concept, tertiary concept, etc.) as naturally as possible to a section of level N and 
2) remain readable by offering groupings, indicating hierarchies or other classifications (like common used and less common used etc.).

For 1 helps referenceing atomically and 2 shows our committment of writing to be read and understood.

My expectation is, that in most cases (imagine XML element or attribute of XML element) "mixed content" in a section referenced indicates all content, 
that includes the "text" and the subsections and all their children. Attributes and namespaces is a minefield. Using contained subsection elegantly removes any reference problems by hierarchical containment

Principle of least surpirse would be my understanding of terms like natrual used inside this comment ;-)





> Hanging paragraphs - all current csprd01 documents
> --------------------------------------------------
>
>                 Key: ODATA-381
>                 URL: http://tools.oasis-open.org/issues/browse/ODATA-381
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Bug
>          Components: OData ATOM Format , OData CSDL, OData Extension for JSON Data 
>    Affects Versions: V4.0_CSD01
>            Reporter: Patrick Durusau
>            Priority: Minor
>
> The current drafts have what are known as "hanging paragraphs." 
> As an example, from odata-v4.0-csprd01-part1-protocol:
> ****
> 8 Header Fields
> OData defines semantics around the following request and response headers. Additional headers MAY be specified, but have no unique semantics defined in OData.
> 8.1 Common Headers
> The OData-Version and Content-Type headers are common between OData requests and responses.
> ****
> If I say, conform to Section 8, do I mean:
> All of section 8 or do I mean only the paragraph following section 8, but not any of the following subsections?
> This happens with sub-sections as well, see odata-v4.0-csprd01-part2-url-conventions:
> ****
> 5.1.1.5 Lambda Operators
> OData defines two operators that evaluate a Boolean expression on a collection. Both must be prepended with a navigation path that identifies a collection. 
> 5.1.1.5.1 any 
> The any operator applies a Boolean expression to each member of a collection and evaluates to true if and only if the expression is true for any member of the collection. As a special case the Boolean expression may be empty, in which case the any operator evaluates to true if the collection is not empty.  
> ****
> If I say conform to 5.1.1.5 Lambda Operators, as in "prepend[ing]" a navigation path that identifies a collection, do I also mean conform to all the subparagraphs that follow? Or do I mean just that part? 
> Formally it is an ambiguous reference to have content following a section division that has sub-divisions. It isn't possible to resolve from the text along, say for a conformance clause, the meaning of the reference. Meaning different readers will assign different meanings to the reference. 

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira