[OASIS Issue Tracker] Commented: (ODATA-383) Examples, distinguishing from normative text

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

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

Stefan Drees commented on ODATA-383:
------------------------------------

As whatever we decide has to work in a convenient and robust way with the authoring tool used, I mutated seom revision of the protocol document into a smallish test document and placed this inside the proposals folder in SVN https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/proposals/table-of-figures-test.docx?rev=294&sc=1

This is only a test for semi-automatic example enumeration and generation of list of examples (also note the two different positioning tactics: Per convention below figure/example and the first above the example.

I thus suggest to if we really enumerate and label examples, we use a section prefixing and thus generate a nice list of examples directly after the table of content.

But we should really discuss if we want this.

What with small examples nearly placed inline. Inside a block with heading above (or caption below) looks somehow (over)wrapped and not supported by structure, as the text and spacing of the heading/caption hampers the flow or laughs at the DRY principle, reader and writer otherwise profit from (not reading stuff two time two times ;-) and not fixing an exampe but missing the typo in the heading/caption (or also very often missed inside the global list of examples).

Also the placement as heading or caption should be checked w.r.t. readability and clarity (in what is visually linked to the structural element (heading/or caption). 


DRY: Don't Repeat Yourself

> Examples, distinguishing from normative text
> --------------------------------------------
>
>                 Key: ODATA-383
>                 URL: http://tools.oasis-open.org/issues/browse/ODATA-383
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Bug
>          Components: OData ATOM Format , OData CSDL, OData JSON Format, OData Protocol , OData URL Conventions 
>    Affects Versions: V4.0_CSD01
>            Reporter: Patrick Durusau
>             Fix For: V4.0_CSD02
>
>
> section 1 of odata-v4.0-csprd01-part1-protocol (the first sentence) provides:
> ****
> All text is normative unless otherwise labeled.
> ****
> But, section 3 says:
> ****
> Some sections of this specification are illustrated with non-normative example OData request and response payloads. However, the text of this specification provides the definition of conformance.
> All code examples in this document are non-normative.
> ****
> So when I read under 8.2.6.3
> ****
> The following Prefer header requests that the annotation with the term name subject within the display namespace be returned if applied:
>  
>     Prefer: odata.include-annotations="display.subject"
> In the case that the client has specified the odata.include-annotations preference in the request, the service MAY include a Preference-Applied response header containing the odata.include-annotations preference to specify the annotations that MAY have been included in the response. This value MAY differ from the annotations requested in the Prefer header of the request. 
> ****
> Is the code block "Prefer: odata.include-annotations="display.subject"" non-normative followed by a normative interpretation of the example? 
> That seems risky at best if examples are truly non-normative and divorced from the normative portions of the text. 
> One strategy would be to label the code blocks as "Example" and simply have it follow normative text. And the normative text doesn't say anything about the example, they just appear as appropriate in the text. What a reader makes of them is on their watch. 
> A partial example from 8.2.6.3:
> Accepting the normative text above: "For example, the following Prefer header requests" for the moment, it would then be followed by a typographically distinct region:
> Example:
> Ex.1 Prefer header requests all annotations within a metadata document to be returned:
>     
>     Prefer: odata.include-annotations="*" 
> Ex.2 Prefer header requests that no annotations are returned:
>     
>     Prefer: odata.include-annotations="-*" 
> and so on.
> I have inserted numbers to avoid the ambiguity of following/previous, which I will list as a separate issue.

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