search

KhronosGroup / OpenCL-Docs

OpenCL API, OpenCL C, Extensions, SPIR-V Environment Specs, Ref page, and C++ for OpenCL doc sources.
Other
351 stars 110 forks source link

bad extension link appearance in the online reference pages #1093

Closed bashbaug closed 3 months ago

bashbaug commented 3 months ago

I fixed a bunch of lengthy and unsightly links in the online reference pages in https://github.com/KhronosGroup/OpenCL-Docs/pull/987, but a few new ones have crept in after merging #950, mostly for extension links, which show up in the spec source like:

    If the `<<cl_khr_command_buffer_multi_device>>` extension is not
    supported, this **must** be one.

Some possible choices:

  1. Do not link the extensions at all.
  2. Use explicit link text, like what was done for #987, even though it's redundant in many cases.
  3. Generate asciidoc attributes for the extension names, then we can easily link or change formatting as desired.

(1) is the easiest option, obviously. (2) is pretty easy too, although the redundancy annoys me. I don't think (3) would be too bad, and I might play around with this when I have a few free minutes.

oddhack commented 3 months ago

These links are automatically rewritten by the refpage extraction script to point back into the spec, so another possibility is to make the script rewrite them with the added text (and probably, have them link to the corresponding extension refpage which is generated from the extension appendix, to stay inside the refpages as much as possible when navigating).

However, that's a very specific thing to include in the script and probably not the best choice. In Vulkan we use asciidoc macros for every link to an extension or API name, and the macro implementation is aware of whether it's being run for the spec or the refpages. You take a different approach to this in OpenCL by using attribute names and pre-generating their definitions, but it is amenable to the same treatment. I think #3 is the best solution under the circumstances, though it will generate a pretty noisy PR since there are about 400 extension links at present. The attributes would need to be specific to any of the C, API, or refpage builds.