api spec editorial fixes (#531)

* fix memory regions table

* format CLK enums

* unify table widths for clGetXXXInfo APIs

* minor grammar fix

* tidy up device partitioning property lists

* remove the cl_image_desc ifdef from the XML file

The ifdef is currently rendering poorly in the generated spec
snippet, and what is in the XML file does not match what is
in the headers currently anyhow.

We will need to resolve this if and only if we decide to generate
actual headers for cl_image_desc from the XML file.

* fix indentation in preprocessor option descriptions

* move the "uniform work group size" and "no subgroup IFP" options

They are not options that control floating-point arithmetic.

* properly format -cl-std= build option and refer to the unified OpenCL C spec

* remove unnecessary phrase for debug option

* tidy up events section

* adjust table column widths one more time

For the PDF spec it's better to use a slightly wider first column.

* unify column headers for get info APIs

* remove the space for pointer "get info" return types

This causes at least one table cell to break better in the PDF
spec.

Author: bashbaug

api/embedded_profile.asciidoc

@@ -151,7 +151,7 @@ Device Queries>> table.
 
 [[embedded-device-queries-table]]
 .List of supported param_names by <<clGetDeviceInfo>> for embedded profile
-[options="header"]
+[width="100%",cols="<33%,<17%,<50%",options="header"]
 |====
 | Device Info | Return Type | Description
 | {CL_DEVICE_MAX_READ_IMAGE_ARGS}

api/footnotes.asciidoc

@@ -70,7 +70,7 @@ To create an image object from another image object that share the data store be
 ]
 
 :fn-image-mem-fence: pass:n[ \
-This value for memory_scope can only be used with atomic_work_item_fence with flags set to CLK_IMAGE_MEM_FENCE. \
+This value for memory_scope can only be used with atomic_work_item_fence with flags set to `CLK_IMAGE_MEM_FENCE`. \
 ]
 
 :fn-int64-performance: pass:n[ \

api/opencl_architecture.asciidoc

@@ -897,41 +897,40 @@ or the host can read and/or write to a memory region).
 
 [[memory-regions-table]]
 .Memory Regions
-[width="80%",options="header"]
+[cols="2,2,3,3,3,3",options="header"]
 |====
-| | Global | Constant | Local | Private
-.2+| Host
-  | Dynamic Allocation
-      | Dynamic Allocation
-          | Dynamic Allocation
-              | No Allocation
-| Read/Write access to buffers and images but not pipes
-  | Read/Write access
-      | No access
-          | No access
-.2+| Kernel
-  | Static Allocation for program scope variables
-      | Static Allocation
-          | Static Allocation.
-
-            Dynamic allocation for child kernel
-              | Static Allocation
-| Read/Write access
-  | Read-only access
-      | Read/Write access.
-
-        No access to child's local memory.
-          | Read/Write access
+| | | Global | Constant | Local | Private
+.2+| *Host*
+  | Allocation
+    | Dynamic
+    | Dynamic
+    | Dynamic
+    | None
+  | Access
+    | Read/Write to Buffers and Images, but not Pipes
+    | Read/Write
+    | None
+    | None
+.2+| *Kernel*
+  | Allocation
+    | Static (program scope variables)
+    | Static (program scope variables)
+    | Static for parent kernel,
+      Dynamic for child kernels
+    | Static
+  | Access
+    | Read/Write
+    | Read-only
+    | Read/Write,
+      No access to child kernel memory
+    | Read/Write
 |====
 
-.Caption
-****
 The <<memory-regions-table, Memory Regions>> table shows the different
 memory regions in OpenCL and how memory objects are allocated and accessed
 by the host and by an executing instance of a kernel.
-For the case of kernels, we distinguish between the behavior of local memory
-with respect to a kernel (self) and its child kernels.
-****
+For kernels, we distinguish between the behavior of local memory
+for a parent kernel and its child kernels.
 
 Once allocated, a memory object is made available to kernel-instances
 running on one or more devices.
@@ -1290,11 +1289,11 @@ Depending on the memory_order argument, this operation:
   * is a sequentially-consistent fence with both acquire and release
     semantics, if *memory_order_seq_cst*.
 
-If specified, the cl_mem_fence_flags argument must be CLK_IMAGE_MEM_FENCE,
-CLK_GLOBAL_MEM_FENCE, CLK_LOCAL_MEM_FENCE, or CLK_GLOBAL_MEM_FENCE |
-CLK_LOCAL_MEM_FENCE.
+If specified, the cl_mem_fence_flags argument must be `CLK_IMAGE_MEM_FENCE`,
+`CLK_GLOBAL_MEM_FENCE`, `CLK_LOCAL_MEM_FENCE`, or `CLK_GLOBAL_MEM_FENCE |
+CLK_LOCAL_MEM_FENCE`.
 
-The atomic_work_item_fence(CLK_IMAGE_MEM_FENCE) built-in function must be
+The `atomic_work_item_fence(CLK_IMAGE_MEM_FENCE, ...)` built-in function must be
 used to make sure that sampler-less writes are visible to later reads by the
 same work-item.
 Without use of the atomic_work_item_fence function, write-read coherence on
@@ -1733,7 +1732,7 @@ release sequence headed by *A*, and the scopes of *A* and *B* are inclusive.
 <<iso-c11,[C11 standard, Section 7.17.4, paragraph 4, modified.]>>
 
 Let *X* and *Y* be two work-item fences that each have both the
-CLK_GLOBAL_MEM_FENCE and CLK_LOCAL_MEM_FENCE flags set.
+`CLK_GLOBAL_MEM_FENCE` and `CLK_LOCAL_MEM_FENCE` flags set.
 *X* global-synchronizes-with *Y* and *X* local synchronizes with *Y* if the
 conditions required for *X* to global-synchronize with *Y* are met, the
 conditions required for *X* to local-synchronize-with *Y* are met, or both
@@ -1773,10 +1772,10 @@ chapter as well as the following:
   * The exit fence is an acquire fence with the same flags and scope as
     requested for the barrier.
   * For each work-item the entry fence is sequenced before the exit fence.
-  * If the flags have CLK_GLOBAL_MEM_FENCE set then for each work-item the
+  * If the flags have `CLK_GLOBAL_MEM_FENCE` set then for each work-item the
     entry fence global-synchronizes-with the exit fence of all other
     work-items in the same work-group.
-  * If the flags have CLK_LOCAL_MEM_FENCE set then for each work-item the
+  * If the flags have `CLK_LOCAL_MEM_FENCE` set then for each work-item the
     entry fence local-synchronizes-with the exit fence of all other
     work-items in the same work-group.
 
@@ -1828,10 +1827,10 @@ chapter as well as the following:
   * The exit fence is an acquire fence with the same flags and scope as
     requested for the barrier.
   * For each work-item the entry fence is sequenced before the exit fence.
-  * If the flags have CLK_GLOBAL_MEM_FENCE set then for each work-item the
+  * If the flags have `CLK_GLOBAL_MEM_FENCE` set then for each work-item the
     entry fence global-synchronizes-with the exit fence of all other
     work-items in the same sub-group.
-  * If the flags have CLK_LOCAL_MEM_FENCE set then for each work-item the
+  * If the flags have `CLK_LOCAL_MEM_FENCE` set then for each work-item the
     entry fence local-synchronizes-with the exit fence of all other
     work-items in the same sub-group.
 
@@ -1947,10 +1946,10 @@ following:
     {CL_COMPLETE} (for example, from a host thread using a
     {clSetUserEventStatus} function), then *X* global-synchronizes-with *C*.
   . If a device enqueues a command *C* with the
-    CLK_ENQUEUE_FLAGS_WAIT_KERNEL flag, then the end state of the parent
+    `CLK_ENQUEUE_FLAGS_WAIT_KERNEL` flag, then the end state of the parent
     kernel instance global-synchronizes with *C*.
   . If a work-group enqueues a command *C* with the
-    CLK_ENQUEUE_FLAGS_WAIT_WORK_GROUP flag, then the end state of the
+    `CLK_ENQUEUE_FLAGS_WAIT_WORK_GROUP` flag, then the end state of the
     work-group global-synchronizes with *C*.
 
 When using an out-of-order command queue, a wait on an event or a marker or

api/opencl_platform_layer.asciidoc

@@ -76,7 +76,7 @@ in the <<platform-queries-table, Platform Queries>> table.
 
 [[platform-queries-table]]
 .List of supported param_names by <<clGetPlatformInfo>>
-[width="100%",cols="<50%,<10%,<40%",options="header"]
+[width="100%",cols="<33%,<17%,<50%",options="header"]
 |====
 | Platform Info | Return Type | Description
 | {CL_PLATFORM_PROFILE_anchor} footnote:[{fn-platform-profile}]
@@ -332,7 +332,7 @@ device except for the following queries:
 
 [[device-queries-table]]
 .List of supported param_names by <<clGetDeviceInfo>>
-[width="100%",cols="<30%,<20%,<50%",options="header"]
+[width="100%",cols="<33%,<17%,<50%",options="header"]
 |====
 | Device Info | Return Type | Description
 | {CL_DEVICE_TYPE_anchor}
@@ -1149,7 +1149,7 @@ include::{generated}/api/version-notes/CL_DEVICE_EXTENSIONS.asciidoc[]
 
         Additionally, the following Khronos extension names must be returned
         by all devices that support OpenCL 2.0, OpenCL 2.1, or OpenCL 2.2.
-        For devices that support OpenCL 3.0, these extension names must only
+        For devices that support OpenCL 3.0, these extension names must
         be returned when and only when the optional feature is supported:
 
         *cl_khr_3d_image_writes* +
@@ -1607,7 +1607,7 @@ on the queue are executed only on the sub-device.
 
 [[subdevice-partition-table]]
 .List of supported partition schemes by <<clCreateSubDevices>>
-[width="100%",cols="<30%,<20%,<50%",options="header"]
+[width="100%",cols="<33%,<17%,<50%",options="header"]
 |====
 | Partition Property | Partition Value | Description
 | {CL_DEVICE_PARTITION_EQUALLY_anchor}
@@ -1709,7 +1709,8 @@ containing 8 compute units, pass the following in _properties_:
 
 [source,c]
 ----
-{ CL_DEVICE_PARTITION_EQUALLY, 8, 0 }
+{ CL_DEVICE_PARTITION_EQUALLY, 8,
+  0 } // 0 terminates the property list
 ----
 
 To partition a device with four compute units into two sub-devices with one
@@ -1719,7 +1720,8 @@ unit, pass the following in properties argument:
 [source,c]
 ----
 { CL_DEVICE_PARTITION_BY_COUNTS,
-  3, 1, CL_DEVICE_PARTITION_BY_COUNTS_LIST_END, 0 }
+    3, 1, CL_DEVICE_PARTITION_BY_COUNTS_LIST_END,
+  0 } // 0 terminates the property list
 ----
 
 To split a device along the outermost cache line (if any), pass the
@@ -1728,8 +1730,8 @@ following in properties argument:
 [source,c]
 ----
 { CL_DEVICE_PARTITION_BY_AFFINITY_DOMAIN,
-  CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE,
-  0 }
+    CL_DEVICE_AFFINITY_DOMAIN_NEXT_PARTITIONABLE,
+  0 } // 0 terminates the property list
 ----
 --
 
@@ -1846,7 +1848,7 @@ on one or more devices specified in the context.
 
 [[context-properties-table]]
 .List of supported context creation properties by <<clCreateContext>>
-[width="100%",cols="<34%,<33%,<33%",options="header"]
+[width="100%",cols="<33%,<17%,<50%",options="header"]
 |====
 | Context Property | Property Value | Description
 | {CL_CONTEXT_PLATFORM_anchor}
@@ -2057,9 +2059,9 @@ _param_value_ by {clGetContextInfo} is described in the
 
 [[context-info-table]]
 .List of supported param_names by <<clGetContextInfo>>
-[width="100%",cols="<34%,<33%,<33%",options="header"]
+[width="100%",cols="<33%,<17%,<50%",options="header"]
 |====
-| Context Info | Return Type | Information returned in param_value
+| Context Info | Return Type | Description
 | {CL_CONTEXT_REFERENCE_COUNT_anchor} footnote:[{fn-reference-count-usage}]
 
 include::{generated}/api/version-notes/CL_CONTEXT_REFERENCE_COUNT.asciidoc[]