[OASIS Issue Tracker] Issue Comment Edited: (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 edited comment on ODATA-381 at 5/12/13 6:42 AM:
-------------------------------------------------------------

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

EDIT (amended below to further refresh :-)

Both examples given in the description are clear in what a reader reads out of following the fictive conformance statements added. 
Text content of section 8 has two statements:

A) OData defines semantics around the following request and response headers. 
Hence the reader has to expect a list of request and response headers which are wrapped into individual sections as service.
So containment is clear. No ambiguity here.

B) Additional headers MAY be specified, but have no unique semantics defined in OData. 
Upon conforming to this, well she knows at least, that some X-foo-bar-baz headers won't hurt.


The second given example when following the fictive conformance from the description of this issue yields:

Section 5.1.1.5 with text content (again two statements):
A) OData defines two operators that evaluate a Boolean expression on a collection. 
Here the reader expects a list of exactly two operators evaluating a Boolean expression on a collection which are again wrapped into individual sections as service.
So containment is clear. No ambiguity here.

B) Both must be prepended with a navigation path that identifies a collection. 
This statement also leaves no doubt, that a prefix for both is needed and also which (a navigation path) and nicely places this in only one location and hierarchically correctly "above" the subsections.


I like to keep structure generally only as a secondary, only supporting and not wrapping the primary content.

In my experience all real things are mixed content and despite some old buggy SGML parser everyone can even formally deal with it in a perfect way.

In addition if say an element has 5 attributes, writer and reader alike will find it helpfull, when there is one section documenting this element and 5 subsections inside documenting every attribute individually and in a hopefully meaningfull and consistent sequence.




      was (Author: sdrees):
    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