add a section describing document conventions

Author: bashbaug

api/introduction.asciidoc

@@ -10,7 +10,7 @@ envelope, Central Processing Units (CPUs) now improve performance by adding
 multiple cores.
 Graphics Processing Units (GPUs) have also evolved from fixed function
 rendering devices into programmable parallel processors.
-As todays computer systems often include highly parallel CPUs, GPUs and
+As today's computer systems often include highly parallel CPUs, GPUs and
 other types of processors, it is important to enable software developers to
 take full advantage of these heterogeneous processing platforms.
 
@@ -76,19 +76,6 @@ devices; and a set of optional extensions that are likely to move into the
 core specification in later revisions of the OpenCL specification.
 
 
-== Normative References
-
-Normative references are references to external documents or resources to
-which implementers of OpenCL must comply with all, or specified portions of,
-as described in this specification.
-
-[[iso-c11]]
-_ISO/IEC 9899:2011 - Information technology - Programming languages - C_,
-https://www.iso.org/standard/57853.html (final specification),
-http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1570.pdf (last public
-draft).
-
-
 == Version Numbers
 
 The OpenCL version number follows a _major.minor-revision_ scheme.  When this
@@ -124,3 +111,96 @@ versions of OpenCL support that feature.
     glossary.
   * Universal: Features that have no mention of what version they are missing
     before or deprecated by are available in all versions of OpenCL.
+
+
+[[introduction-document-conventions]]
+== Document Conventions
+
+The OpenCL specification is intended for use by both implementors of the API and
+application developers seeking to make use of the API, forming a contract
+between these parties.
+The OpenCL specification text may address either party; typically the intended
+audience can be inferred from context, though some sections address only one of
+these parties.
+
+[[introduction-normative-requirements]]
+=== Normative Requirements
+
+The OpenCL Specification uses a combination of
+<<introduction-normative-terminology, normative terminology>> and
+<<introduction-normative-descriptions, normative descriptions>> to express
+the requirements that it imposes on applications and implementations.
+An application which complies with all normative requirements imposed on
+applications is said to make *valid use* of the API; failing to comply with
+such requirements may result in undefined behavior, as described in the
+<<valid-usage, Valid Usage>> section.
+In the context of this document, an implementation which complies with all
+normative requirements imposed on implementations is said to be
+*conformant*.
+
+[[introduction-normative-terminology]]
+==== Normative Terminology
+
+Within this specification, the key words must, required, should, may,
+and optional are to be interpreted as described in
+https://www.ietf.org/rfc/rfc2119.txt[RFC 2119 - Key words for use in RFCs to
+Indicate Requirement Levels] (https://www.ietf.org/rfc/rfc2119.txt).
+The additional key word optionally is an alternate form of optional, for
+use where grammatically appropriate.
+
+[[introduction-normative-descriptions]]
+==== Normative Descriptions
+
+The normative term must is primarily used to describe *application* behavior,
+and in particular to constrain what inputs or commands issued by the application
+to the implementation are considered valid.
+
+To constrain *implementation* behavior, the specification sometimes uses
+must, but more often simply describes the behavior of the implementation in
+response to specified commands and inputs.
+Unless explicitly stated otherwise, such references to implementation
+behavior describe the behavior of *conformant* implementations, and express
+normative requirements which an implementation must satisfy in order to
+conform to the specification.
+
+When the normative terms may, should, or optional are used to describe
+implementation behavior, they define alternative or optional behaviors which
+a conformant implementation may or may not exhibit.
+Such statements are also normative.
+
+[[introduction-normative-references]]
+==== Normative References
+
+References to external documents are considered normative references if the
+OpenCL specification uses <<introduction-normative-terminology, normative
+terminology>> or <<introduction-normative-descriptions, normative descriptions>>
+to refer to them or their requirements, either as a whole or in part.
+
+The following documents are referenced by normative sections of the
+specification:
+
+[[iso-c11]]
+_ISO/IEC 9899:2011 - Information technology - Programming languages - C_,
+https://www.iso.org/standard/57853.html (final specification),
+http://www.open-std.org/jtc1/sc22/WG14/www/docs/n1570.pdf (last public
+draft)
+
+[[spirv-spec]]
+_SPIR-V Specification, Version 1.6, Unified_.
+https://registry.khronos.org/spir-v/
+
+[[introduction-error-codes]]
+=== Error Codes
+
+In many cases, the OpenCL specification describes conditions when an
+implementation must return an error code due to invalid application usage.
+If multiple conditions are described for an error code, the error code must be
+returned if any of the conditions are met.
+If error conditions are met for multiple error codes, the implementation may
+return any of the error conditions.
+
+[[introduction-strings]]
+=== String Representation
+
+Unless specified otherwise, strings passed to or returned from OpenCL API
+functions are defined to be null-terminated and UTF-8 encoded.