Asciidoctor cannot convert glslc/README.asciidoc to manpage

[philippemilink]

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)

[jasonliu--]

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"

[jasonliu--]

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/