search

KhronosGroup / OpenCL-Docs

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

Bad Latexmath Rendering in SPIR-V Environment Spec PDF #324

Closed bashbaug closed 4 years ago

bashbaug commented 4 years ago

The latexmath in the OpenCL 3.0 provisional PDF spec appears to be rendering incorrectly. See, for example, section 7.4.1. Conversion Rules for Normalized Integer Channel Data Types. This problem seems to be toolchain-related since the same spec source renders fine in the published 2.2 specs. I'm seeing similar errors when I build the Vulkan spec, also. Note that the HTML rendering is fine.

I have a stripped down example that demonstrates the incorrect rendering. I've tried the latest versions of asciidoctor, asciidoctor-pdf, and asciidoctor-mathematical, but they don't seem to fix the issue.

If we cannot get this issue resolved promptly, we should consider whether having the latexmath is worth the trouble, or if we should switch to monospace code font instead.

bashbaug commented 4 years ago

I got this working with two small fixes:

  1. I needed to update to asciidoctor-mathematical 0.3.2 (the latest).
  2. I needed to install some missing fonts. I fixed this on my Ubuntu system by installing the fonts-lyx package.

With these fixes the latexmath is rendering correctly again:

https://bashbaug.github.io/OpenCL-Docs/pdf/OpenCL_Env.pdf

I'll leave this issue open until I get a chance to update the readme and travis configuration.

@oddhack, heads up, this might save you some time if/when you decide to update the Vulkan spec toolchain.

oddhack commented 4 years ago

Thanks. We now use a Docker image as the supported method of installing the required toolchain, to alleviate issues with the complex dependencies - recommended (in part because CI runtime goes way down, but mostly just to have a known-good baseline). You could use the same khronosgroup/docker-images:vulkan-docs-base image we do, if you want, or roll your own if you want something more stripped down since you don't need much of our toolchain (if you do this, I recommend adding the Dockerfile to the https://github.com/KhronosGroup/DockerContainers repo).

I'm not aware of the problems you encountered coming up for Vulkan, but I don't inspect the PDF in enormous detail, either - if you recall where you were seeing the similar errors I'll take a look at what we publish. The image does have fonts-lyx but is using asciidoctor-mathematical 0.3.1, so lags you a bit.

"Math is Hard!"