Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-384

Normative text needs to be typographically distinct from examples

    XMLWordPrintable

    Details

    • Proposal:
      Hide

      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.
      (Example 1: text describing an example uses this paragraph style.)
      [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", the paragraph in parentheses uses "Caption", and the paragraph in square brackets uses "Code", so they look as their real counterparts in the following specification text.

      Show
      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. (Example 1: text describing an example uses this paragraph style.) [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", the paragraph in parentheses uses "Caption", and the paragraph in square brackets uses "Code", so they look as their real counterparts in the following specification text.
    • Resolution:
      Show
      https://www.oasis-open.org/committees/download.php/49353/odata-v4.0-wd02-part1-protocol-2013-05-28.docx https://www.oasis-open.org/committees/download.php/49354/odata-v4.0-wd02-part2-url-conventions-2013-05-28.docx https://www.oasis-open.org/committees/download.php/49277/odata-v4.0-wd02-part3-csdl-2013-05-28.docx https://www.oasis-open.org/committees/download.php/49351/odata-atom-format-v4.0-wd02-2013-05-28.docx https://www.oasis-open.org/committees/download.php/49352/odata-json-format-v4.0-wd02-2013-05-28.docx Accepted: https://www.oasis-open.org/committees/download.php/49557/odata-meeting-41_on-20130613_14-F2F-minutes.html#odata-384

      Description

      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.

        Attachments

          Activity

            People

            • Assignee:
              martinzurmuehl Martin Zurmuehl
              Reporter:
              patrick Patrick Durusau
            • Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: