Tracker for remaining refpage todo items

[oddhack]

These are the significant remaining steps following #67 before we can replace the old Docbook reference pages with ones extracted from the specification sources:

• Missing short descriptions in API refpage markup
• Add cross-references in API refpage markup
  • Also add to Apache redirects in published refpages on khronos.org.
• Modify C / Doc generator scripts to not try and align function parameter / member names per Ben
• Generate aliases (either HTML or server-side redirects via .htaccess) for OpenCL C refpages containing many functions.
• TOC page for the entire refpage set.
  • Static part of TOC is out of date
• Some missing OpenCL C pages that will probably have to be static, like 'attribute' and 'dataTypes'.
• Missing API (mostly, some C) pages, found by running @outofcontrol's link-checker against the published pages. The majority of these are API handle types.
  • clCreateImage2D
  • clCreateImage3D
  • cl_command_queue
  • cl_context
  • cl_device_id
  • cl_event
  • cl_kernel
  • cl_kernel_sub_group_info
  • cl_khr_mipmap_image_writes
  • cl_mem
  • cl_pipe_properties
  • cl_platform_id
  • cl_program
  • cl_queue_properties
  • cl_sampler
  • cles_khr_int64
  • get_image_num_mip_levels
  • imageFunctions
  • qualifiers
• No refpages for KHR extensions, yet. It is difficult to mark up the extension diff specs for autoextraction as they're currently constructed, and it may be best to retain the static refpages (converted to asciidoctor) until such time as a unified core + extensions spec might be generated.
  • As of Add static refpages #83, the existing static extension refpages have been added, but they are well out of date, since they are just a translation of the Docbook sources to asciidoctor.
• Nothing done for C++ or Environment specs, yet. (crossed out because these are beyond the scope of the refpage project - if the WG wants to add new categories of pages, this work could be done).

[oddhack]

See #72 for WIP MR addressing some of these points.

[oddhack]

#83 adds extension refpages (static) and some of the missing index pages.

[oddhack]

OpenCL 2.2 refpages are published on khronos.org/registry/OpenCL/ now. More could be done, of course.

[oddhack]

#116 cleans up a bunch of broken internal refpage links, and adds a missing static page (possibly out of date) listing allowed enum values for enumerated cl_* types.

[oddhack]

@bashbaug commented on #116, and I responded:

• Is there some way we can better document some or all of the enums described in the enums page vs. having a catch-all enumerants page to describe them? For example, could the cl_device_info enums map to the page for clGetDeviceInfo instead?

• For enums that will live in the enums page for the foreseeable future, can we auto-generate the enums page from the XML file so it's more likely to stay up-to-date?

It's straightforward to add aliases - look for the [open] block for clGetDeviceInfo and add cl_device_info to the 'alias' attribute (or create it, if not already present). It might be necessary to edit the static part of the TOC (in man/toctail) depending on the page.

Generating (the majority of) the enums page would also be straightforward, though it would take a
little time to write a new generator for the purpose. I don't think we could get the informative footnotes added automatically. It would probably still be useful to have an entry for cl_device_info in the enums page that links out.

Mixing and matching these two approaches would be more work, since whatever manual aliases were added, would have to be filtered out of the autogenerated aliases.

[oddhack]

@bashbaug @ntrevett - @outofcontrol brought up the 2.2 refpage missing link issue again in the registry repo. Here's where it stands, as best I recall:

• Last time I looked, which was a few years ago, it was hard to extract most of these from the spec sources either because there was really no good language describing them or because it was scattered in a way which would require significant rewrites to group into a refpage block. I have a vague memory of most of the CL handle datatypes being described in a big table.
• Easy fix from the standpoint of avoiding broken link errors is to create stub pages in man/static that just link into a relevant section of the 2.2 spec.
• Given that default branch is now at 3.0, we would have to work in a branch based on the last updated 2.2 spec, right? I'm not sure which branch / tag this is, since I haven't been paying much attention to CL WG activity.
• I don't know where 3.0 refpages stand? I tried generating them from current default branch and unsurprisingly they're considerably different than the 2.2 pages in the registry. Is there an intent to publish 3.0 refpages? That's a separate issue from making 2.2 internally self-consistent, though.
• If the WG wants me to take a swing at the 2.2 pages, I'm happy to do that. If not, I think I've given a reasonable guideline above to a minimal solution that shouldn't take long to propose. A better solution with appropriate spec language would be quite a lot more work and necc. draw in WG members to generate and/or review that language.

Let me know how you want to proceed.

[oddhack]

@outofcontrol I generated a tweaked version of the CL 2.2 refpages under https://www.khronos.org/registry/OpenCL/sdk/2.2/docs/man/test/ . Could you run your link checker over it? I tried to get all the dangling pages you mentioned in KhronosGroup/OpenCL-Registry#94 but I can't be sure without automatic verification.

[outofcontrol]

Missing pages:

/test/atomic_flag_test_and_set_explicitatomic_init.html
/test/cl_command_queue.html
/test/cl_context.html
/test/cl_device_id.html
/test/cl_event.html
/test/cl_kernel.html
/test/cl_khr_mipmap_image_writes.html
/test/cl_mem.html
/test/cl_pipe_properties.html
/test/cl_platform_id.html
/test/cl_program.html
/test/cl_queue_properties.html
/test/cl_sampler.html
/test/clCreateImageWithProperties.html
/test/cles_khr_int64.html
/test/get_image_num_mip_levels.html
/test/imageFunctions.html

[oddhack]

@bashbaug I was puzzled by why the 2.2 Extensions Specification wasn't resolving get_image_num_mip_levels until I realized that it was generated from a 2019 snapshot of the tree while the refpages branch I'm working in for the moment were done in 2020, and the cl_khr_mipmap_image section didn't contain those calls until later. Do you think it would be OK for me to update the 2.2 OpenCL_Ext.html from the https://github.com/KhronosGroup/OpenCL-Docs/tree/update-refpages-2.2-from-0a92eee branch?

[oddhack]

Missing pages:

/test/atomic_flag_test_and_set_explicitatomic_init.html
/test/cl_command_queue.html
/test/cl_context.html
/test/cl_device_id.html
/test/cl_event.html
/test/cl_kernel.html
/test/cl_khr_mipmap_image_writes.html
/test/cl_mem.html
/test/cl_pipe_properties.html
/test/cl_platform_id.html
/test/cl_program.html
/test/cl_queue_properties.html
/test/cl_sampler.html
/test/clCreateImageWithProperties.html
/test/cles_khr_int64.html
/test/get_image_num_mip_levels.html
/test/imageFunctions.html

Please try again. I had not updated the .htaccess file properly to rewrite those.

[bashbaug]

I was puzzled by why the 2.2 Extensions Specification wasn't resolving get_image_num_mip_levels until I realized that it was generated from a 2019 snapshot of the tree while the refpages branch I'm working in for the moment were done in 2020, and the cl_khr_mipmap_image section didn't contain those calls until later.

Yeah, this sounds right... it looks like the last v2.2 spec was tagged in July 2019 (V2.2-11, 2aaf7b5) and the mipmaps built-ins weren't re-added until later (#149, bd449aa). Do you happen to know when the 2.2 refpages were built? Was it from commit 0a92eee?

Do you think it would be OK for me to update the 2.2 OpenCL_Ext.html [...]

Would you only update the extension spec?

In theory it would be OK to update any of the 2.2 specs to any commit before the v3.0.1-Provisional tag (fafc202). The extension spec especially should be pretty low-risk to update and when I took a look at the diffs they were pretty minor.

Another option would would be to link the 2.2 refpages to the 3.0-unified extensions spec since the extension spec has been unified for some time now, although this might be a little confusing and it does add a coupling between the 2.2 refpages and the 3.0 specs that wouldn't exist otherwise.

[oddhack]

Do you happen to know when the 2.2 refpages were built? Was it from commit 0a92eee?

You can sort of puzzle it out from the footer information on the pages although it's oddly encoded - Version V2.2-11-107-g6eaa3d2 => commit 6eaa3d2 + various minor fixes I made, which were then committed under the next commit 0a92eee.

Do you think it would be OK for me to update the 2.2 OpenCL_Ext.html [...]

Would you only update the extension spec?

That's all that's needed and seems like less work for you to verify.

Another option would would be to link the 2.2 refpages to the 3.0-unified extensions spec since the extension spec has been unified for some time now, although this might be a little confusing and it does add a coupling between the 2.2 refpages and the 3.0 specs that wouldn't exist otherwise.

That seems better than regenerating a 2.2 OpenCL_Ext spec just for this reason. Will change accordingly.

[oddhack]

Pushed an update to https://github.com/KhronosGroup/OpenCL-Docs/tree/update-refpages-2.2-from-0a92eee for the get_image_num_mip_levels issue. I think this is completely fixed for the 2.2 pages now, pending @outofcontrol's link-checker.

[outofcontrol]

0 broken links now.

[oddhack]

@bashbaug I (edit: went) ahead and updated the 2.2 pages from the https://github.com/KhronosGroup/OpenCL-Docs/tree/update-refpages-2.2-from-0a92eee branch in order to get this off the table and move on to 3.0 pages.

[oddhack]

Closing. Will open a new issue for 3.0 refpages as those progress.