[OASIS Issue Tracker] Updated: (ODATA-384) Normative text needs to be typographically distinct from examples

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

     [ http://tools.oasis-open.org/issues/browse/ODATA-384?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Ralf Handl updated ODATA-384:
-----------------------------

       Proposal: 
Syntax, grammar, signatures, etc., all of which are normative text, must have a distinct typography from examples. 

Examples use paragraph style "Code" with 9-point courier type, grey background, and black lines above the first and below the last line.

Normative "source" text uses paragraph style "Source Code" with 10-point courier type and white background. Using the same font size and background color as normative prose text should be sufficient to express that it is part of the normative specification.

Add a section "Typographical Conventions" as the last section of chapter 1 of each document with the text

Keywords defined by this specification `use` this _monospaced_ font.
{Normative source code uses this paragraph style.}
Some sections of this specification are illustrated with non-normative example OData requests and responses. 
[Non-normative examples use this paragraph style.]
All examples in this document are non-normative.
All other text is normative unless otherwise labeled.



  was:
Syntax, grammar, signatures, etc., all of which are normative text, should have a distinct typography from examples. 

I don't know if this would be sufficient or be accepted by the TC but surrounding examples with broken lines to signal they are distinct from the normative text might be one way to reliable distinguish examples. 

Plus recording the typographical conventions at the start of the text would also be a good thing.

    Environment: [Proposed]

> Normative text needs to be typographically distinct from examples
> -----------------------------------------------------------------
>
>                 Key: ODATA-384
>                 URL: http://tools.oasis-open.org/issues/browse/ODATA-384
>             Project: OASIS Open Data Protocol (OData) TC
>          Issue Type: Bug
>          Components: OData Protocol , OData URL Conventions 
>    Affects Versions: V4.0_CSD01
>         Environment: [Proposed]
>            Reporter: Patrick Durusau
>             Fix For: V4.0_CSD02
>
>
> In parts 1 and 2 of CSDL, the typography for examples is used for normative text. For example, under 8.2.6.3 of part 1, it is used to report the syntax of odata.include-annotations. 
> In part 2, under 5.1.1.4.1 (and elsewhere), it is used to report the signatures of functions, followed by examples using the same typography. 
> Which confuses the issue of which is the example and which is the signature.

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