RefPageStatus.adoc

= OpenCL Refpage Status

  * Based on Vulkan / OpenXR refpage toolchain & formatting
  * Created expanded OpenCL XML
    link:https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/xml/cl.xml[cl.xml]
    including formal definitions of the APIs.
  ** Uses XML to create asciidoctor fragments defining API elements
  ** XML can also be used to create headers & other dev tooling - see Vulkan
     / GL / XR / etc.
  * Done for API spec - see `refpages` branch on
    https://github.com/KhronosGroup/OpenCL-Docs
  * Markup changes rearrange content slightly to follow a consistent
    pattern:
  ** Add asciidoctor open blocks around each reference page
  ** Introductory paragraph
  ** Interface definition, as generated by XML (replaces handcoded source
     block)
  ** Short descriptions of parameters
  ** Refpage body - long descriptions, tables of valid parameter values, etc.
  ** Return codes / error behavior
  ** Boilerplate end material - see also, notes, copyright statement

== Sample Pages Extracted From opengl_platform_layer.txt

=== HTML outputs

  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clGetPlatformIDs.html[clGetPlatformIDs]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clGetPlatformInfo.html[clGetPlatformInfo]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clCreateContextFromType.html[clCreateContextFromType]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clCreateContext.html[clCreateContext]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clCreateSubDevices.html[clCreateSubDevices]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clGetContextInfo.html[clGetContextInfo]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clGetDeviceAndHostTimer.html[clGetDeviceAndHostTimer]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clGetDeviceIDs.html[clGetDeviceIDs]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clGetDeviceInfo.html[clGetDeviceInfo]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clGetHostTimer.html[clGetHostTimer]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clReleaseContext.html[clReleaseContext]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clReleaseDevice.html[clReleaseDevice]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clRetainContext.html[clRetainContext]
  * link:http://htmlpreview.github.io/?https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/out/man/html/clRetainDevice.html[clRetainDevice]

=== Intermediate Markup Extracted From Spec

Compare regular parameter markup style in
link:https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/man/clGetPlatformIDs.txt[clGetPlatformIDs.txt]
with proposed bullet point-style markup in
link:https://github.com/KhronosGroup/OpenCL-Docs/blob/refpages/man/clGetPlatformInfo.txt[clGetPlatformInfos.txt]

== Remaining Work / Decisions

  * Complete adding markup to all other files containing refpage-worthy
    material.
  ** Done for API spec.
  * Misc. minor cleanup, tweaks of scripts to be OpenCL-specific, etc. as I
    noticed issues.
  ** Could modify markup to match Vulkan / OpenXR style, where parameters /
     structure members are described in a bullet list instead of separate
     paragraphs. This can be recognized easily by the refpage extraction
     script, but is more intrusive and a stylistic change WG, or spec
     editors might not like.
  ** Probably want to add an explicit Errors section, instead of just
     tacking it onto the end of the refpage body. This requires explicit
     (`// refError`, etc.) markup of some subsections of each refpage due to
     difficulty recognizing them automatically, and enhancing the extraction
     script to recognize this markup.
  * The C language refpage content (e.g. work_group_reduce) doesn't easily
    lend itself to extraction from the source document, since instead of
    each function appearing separately, they tend to be grouped together
    into tables of similar functions (e.g. work_group_*).
  ** My suggestion here is that instead of having a separate page per C
     function, we have a group page so we can still lift the content
     directly from the spec sources, then refer to the group page by each
     individual function in the index, and/or make the pages for each
     individual function alias the group page.
  * There are some refpages in the current published set that aren't
    actually present in the spec.
  ** We will probably want to convert these to asciidoctor markup and
     maintain them as static documents, since otherwise we'd have to find
     some way to integrate them into the spec documents proper.
  * Extraction scripts currently rewrite all asciidoctor xrefs into
    hyperlinks to an external single-page HTML spec document (e.g. the
    current published specs). Since quite a few commands use xrefs to tables
    of valid parameters, scripts need to be smart enough not to rewrite
    xrefs to anchors present in a refpage.
  * Function names don't crosslink to other refpages. They could, but this
    would involve more intrusive markup in the spec sources.
  * Should add attributes to open blocks defining cross-references and other
    metadata, as appropriate.
  * Might want to tweak scripts which generate asciidoctor interface
    fragments. Output is semantically the same as handwritten interfaces,
    but formatted a bit differently (more white space).
  * Can autogenerate some additional information in pages, e.g. version
    support table ("`clXYZ requires OpenCL 1.1 or later...`")

== Longer-Term Projects

  * We can consider moving to generated headers based on XML. This will
    require some additional scripting work since the Vulkan / OpenXR headers
    are a bit simpler, but I believe all the relevant metadata is now
    available in the XML I've created to support the refpage work.
  ** Our experience in Vulkan / OpenGL is that having this information
     available helps outside developers to write tooling like language
     bindings, debugging layers, etc.
  * Material in the OpenCL C++ spec really isn't covered at all in the
    current refpages.
  ** This is beyond the scope of this project, but I will make some
     suggestions about how we might approach it, if people want. I haven't
     looked at this much, yet.