Skip to content

Latest commit

 

History

History
108 lines (98 loc) · 6.85 KB

RefPageStatus.adoc

File metadata and controls

108 lines (98 loc) · 6.85 KB
Raw

OpenCL Refpage Status

  • Based on Vulkan / OpenXR refpage toolchain & formatting

  • Created expanded OpenCL 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

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.