search

KhronosGroup / SPIRV-Registry

SPIR-V specs
109 stars 72 forks source link

Options for fixing Note icons #245

Closed bashbaug closed 5 months ago

bashbaug commented 5 months ago

From a recent review comment: https://github.com/KhronosGroup/SPIRV-Registry/pull/243#pullrequestreview-1932696242

The "Note" icon in at least one of our specs is a broken image link. I think I know what's happening to cause this. By default, if you define an "icons" attribute, asciidoctor looks for images in a specified directory (link). If the images don't exist here, the icons show up as broken links, which explains the behavior we are seeing.

Here are some options to fix this:

  1. We add the images in this repo somewhere, and point the icons directory to it.
  2. We don't define the "icons" attribute. This will omit the image icon, and the "Note" will show up as text only. Needs a Makefile update in this repo.
  3. We define the "icons" attribute to be "font". This seems to work for me and produces nice output, but only for "asciidoctor", and not for "asciidoc". Our "official" toolchain still uses "asciidoc" though we really ought to update to "asciidoctor" at some point in the future.

(2) is the path of least resistance.

In the meantime, @gnl21, if you want to "fix" SPV_KHR_float_controls2, here are a few command lines that I think will work:

asciidoc -b html5 -a toc2 -a toclevels=1 extensions\KHR\SPV_KHR_float_controls2.asciidoc
asciidoctor -b html5 -a toc2 -a toclevels=1 extensions\KHR\SPV_KHR_float_controls2.asciidoc 
asciidoctor -b html5 -a icons=font -a toc2 -a toclevels=1 extensions\KHR\SPV_KHR_float_controls2.asciidoc
Naghasan commented 5 months ago

FYI, Vulkan and SYCL uses icons=font by default, but it is embedded in the main docs. We should probably define a settings document extension would import to unify the rendering of extensions.

Our "official" toolchain still uses "asciidoc" though we really ought to update to "asciidoctor" at some point in the future.

The main spec is already using asciidoctor and the khronos docker image only provides this tool. We probably need to update the build doc here.

bashbaug commented 5 months ago

I think we can close this now. As long as you use the updated toolchain added in #247 the "note" icon should appear correctly.