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

Key words within paragraphs use character style "Datatype" with courier type in the same font size as the surrounding text.

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

<section-content>
Keywords defined by this specification 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.
</section-content>

The word in back-ticks uses the "Datatype" character style, the paragraph in curly braces uses "Source Code", and the paragraph in square brackets uses "Code", so they look as their real counterparts in the following text

  was:
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.




> 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