Update README Misc. updates for the integrated API / C specifications and the current publishing path for vendor extensions.
diff --git a/README.adoc b/README.adoc index c5f8c4d..637dab7 100644 --- a/README.adoc +++ b/README.adoc
@@ -3,59 +3,83 @@ The OpenCL-Registry repository contains the OpenCL API and Extension Registry, including specifications, reference pages, and reference cards. It is also used as a backing store for the web view of the registry at -https://www.khronos.org/registry/cl/ ; commits to the main branch of this +https://registry.khronos.org/OpenCL/ ; commits to the main branch of this repository will be reflected there. Please file issues with the OpenCL API (specification bugs, feature -requests, etc.) on the companion https://github.com/KhronosGroup/OpenCL-Docs -repository. +requests, etc.) in the companion +link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs] repository. Issues that should be filed in *this* repository include adding OpenCL -extension specifications, and problems with the content of the registry -*itself*. +extension specifications, and problems with the structure and content of the +registry *itself*. + == Reserving OpenCL Enumerant Ranges -OpenCL enumerants are now documented in the specification repository -https://github.com/KhronosGroup/OpenCL-Docs in the file -https://github.com/KhronosGroup/OpenCL-Docs/blob/main/xml/cl.xml +OpenCL enumerants are now documented in the +link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs] repository in +the file +link:https://github.com/KhronosGroup/OpenCL-Docs/blob/main/xml/cl.xml[xml/cl.xml]. New enumerant ranges can be allocated by proposing a pull request to `main` branch of OpenCL-Docs modifying `cl.xml`, following the -existing examples. Allocate ranges starting at the lowest free values -available (search for "`Reserved for vendor extensions`"). Ranges are not -officially allocated until your pull request is *accepted* into `main` -branch of the OpenCL-Docs repository. At that point you can use values from -your assigned range for API extensions. +existing examples. +Allocate ranges starting at the lowest free values available (search for +"`Reserved for vendor extensions`"). +Ranges are not officially allocated until your pull request is *accepted* +into `main` branch of the OpenCL-Docs repository. +At that point you can use values from your assigned range for API +extensions. -== Adding Extension Specifications -Extension specification documents can be added by proposing a pull request -to main, adding the specification '.txt' or '.html' file under -'extensions/<vendor>/<filename>'. You must also: +== Adding Khronos Extension Specifications -* Modify 'extensions/registry.py' to include the extension, using the next - free extension number. Execute the python script 'nextfree.py' in the - 'extensions/' directory to find the next free number. The extension `flags` - must be marked as `public` , similar to other entries in 'registry.py', - for the extension to be linked from the registry index page. -* Include that extension number in the extension specification document -* In the 'extensions/' directory, `make` to regenerate the HTML index file - 'clext.php' from 'registry.py'. If this doesn't succeed due to not having - the right Python version or something like that, we'll take care of it - when merging to main. +Khronos `khr` extensions must now be documented in the OpenCL API and OpenCL +C Specifications, written as conditionally-included markup. +Propose a pull request against the appropriate specification markup and XML +files in the link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs] +repository. -Sometimes extension text files contain inappropriate UTF-8 characters. They -should be restricted to the ASCII subset of UTF-8 at present. They can be -identified using the iconv Linux command-line tool via + +== Adding Vendor Extension Specifications + +Vendor extension specification documents should be written as separate +asciidoc markup files in the +link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs] repository. +Use the +link:https://github.com/KhronosGroup/OpenCL-Docs/blob/main/extensions/cl_extension_template.asciidoc[asciidoc +extension template] and follow the markup style of existing, similar +extensions. +Propose a pull request against the appropriate specification markup and XML +files in the link:https://github.com/KhronosGroup/OpenCL-Docs[OpenCL-Docs] +repository when you are ready to publish the extension. + +The repository maintainer will assist with importing the HTML generated from +the asciidoc source file and making needed changes to files in this +repository when publishing: + + * Modify 'extensions/registry.py' to include the extension, using the next + free extension number. + Execute the python script 'nextfree.py' in the 'extensions/' directory + to find the next free number. + The extension `flags` must be marked as `public` , similar to other + entries in 'registry.py', for the extension to be linked from the + registry index page. + * Include that extension number in the extension specification document + * In the 'extensions/' directory, `make` to regenerate the HTML index file + 'clext.php' from 'registry.py'. + If this doesn't succeed due to not having the right Python version or + something like that, we'll take care of it when merging to main. + +Older extensions are written as text (`.txt`) files. +Sometimes extension text files contain inappropriate UTF-8 characters. +They should be restricted to the ASCII subset of UTF-8. +Problematic characters can be identified using the iconv Linux command-line +tool: iconv -c -f utf-8 -t ascii filename.txt -(see internal Bugzilla issue 16141 for more). - -It is recommended to use the asciidoc-based extension template to generate HTML -extension specifications instead, see -https://github.com/KhronosGroup/OpenCL-Docs/blob/master/extensions/cl_extension_template.asciidoc == Repository Contents