From a2165ab18b5064104b7ed3737188f7ba1346f1e2 Mon Sep 17 00:00:00 2001 From: Greg Lueck Date: Mon, 10 Jun 2024 10:23:37 -0400 Subject: [PATCH] Add new non-normative note format Add a new format for non-normative notes. This is the same format that the C++ specification uses, and we plan to migrate to this new format as we generally improve the formatting of the SYCL spec. --- adoc/chapters/architecture.adoc | 8 +++++++- adoc/syclbase.adoc | 11 +++++++++++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/adoc/chapters/architecture.adoc b/adoc/chapters/architecture.adoc index b2165bbf..499038ca 100644 --- a/adoc/chapters/architecture.adoc +++ b/adoc/chapters/architecture.adoc @@ -161,7 +161,8 @@ Programming languages — {cpp}>>, referred to in this specification as the next Unless stated otherwise, text within this SYCL specification is normative and defines the required behavior of a SYCL implementation. Non-normative / informational notes are included within this specification using -a "`note`" callout, of the form: +either of two formats. +One format for non-normative notes is the "`note`" callout of this form: [NOTE] ==== @@ -170,6 +171,11 @@ purposes and does not impose requirements on or specify behavior of a SYCL implementation. ==== +The other format for a non-normative note is like this: + +{note}This is also a non-normative note. +{endnote} + Source code examples within the specification are provided to aid with understanding, and are non-normative. diff --git a/adoc/syclbase.adoc b/adoc/syclbase.adoc index 73e2ec53..01897db3 100644 --- a/adoc/syclbase.adoc +++ b/adoc/syclbase.adoc @@ -64,6 +64,17 @@ include::config/attribs.adoc[] :cpp20: pass:[C++20] // Fortunately, the cpp macro for C++ is defined by default in AsciiDoctor +// Use these to format a non-normative note. The Asciidoc source: +// +// {note}Caveat emptor. +// {endnote} +// +// is formatted like: +// +// [Note: Caveat emptor. -- end note] +:note: pass:q[[_Note:_ ] +:endnote: pass:q,a[_—{nbsp}end{nbsp}note_]] + // SYCL Algebraic definitions :SYCLeval: Satisfied :SYCLperform: Perform