shaderc
shaderc copied to clipboard
Asciidoctor cannot convert glslc/README.asciidoc to manpage
Hello,
When packaging shaderc for Debian, I noticed asciidoctor fails to convert glslc/README.asciidoc to the manpage format:
asciidoctor -b manpage glslc/README.asciidoc -o glslc.1
asciidoctor: ERROR: README.asciidoc: line 1: non-conforming manpage title
Indeed, according to the documentation (Document Header), the first line of glslc/README.asciidoc should be:
= glslc(1)
Greetings, I'm working on packaging shaderc for MacPorts. @philippemilink, if I manually run the command that you used, I also get the same error message, but I do still get a glslc.1
manpage file that gets generated. I think there may be a larger problem, in that the CMake build doesn't appear to run the shaderc_add_asciidoc
function at all, as currently specified in utils.cmake
:
https://github.com/google/shaderc/blob/e166325b24d79d64bfa47065328890ce116ea642/cmake/utils.cmake#L74-L89
and called in glslc/CMakeLists.txt
:
https://github.com/google/shaderc/blob/e166325b24d79d64bfa47065328890ce116ea642/glslc/CMakeLists.txt#L66
As I am packaging shaderc and running through the build, no documentation gets generated, regardless of whether you output the default HTML, or modify the source code to try to generate a manpage. I have to manually exec asciidoctor myself in my MacPorts Portfile in order to get any documentation to be generated:
system "/opt/local/bin/asciidoctor -a toc \
-o ${build.dir}/glslc/glslc.html \
${worksrcpath}/glslc/README.asciidoc"
And to address your original issue, @philippemilink, I think the asciidoc file was written with generating HTML in mind, not a manpage.
https://docs.asciidoctor.org/asciidoctor/latest/html-backend/