Documentation does not build on current HEAD

[spheenik]

I maintain a package in the Arch User Repository, which contains a build of the HEAD of nvme-cli.

When building the docs in man format, I get the following error:

Documentation/meson.build:253:8: ERROR: File nvme-wdc-cloud-boot-SSD-version.1 does not exist.

The file is indeed missing in the current HEAD. Is there an option to gracefully continue the build process, ignoring this error?

[igaw]

The problem is that we haven't done a new release since the new man page was added. When I cut a new release I do the update docs steps which creates the $NAME.1 and $NAME.html out of the $NAME.txt file. I suspect you are using -Ddocs=man. You either drop this for the time being or you can add -Ddocs-build=true. Though in this case you need also the documentation build tool chain.

[spheenik]

I use the -D docs=man -D docs-build=true in my build command. This probably means I do not have the right tools installed. Could you point me to documentation on what exactly is needed? I tried to find it, to no avail.

[igaw]

Good point, we should document this.

This docs are generated when the asciidoc program is found (from the asciidoctor project). In case the binary is called differently, we should be able to make it more configurable.

And xmlto is also necessary for man pages.

[spheenik]

Yes, in arch, it is indeed called asciidoctor instead of asciidoc. The package was installed already, so I symlinked, and now the docs build. Any way for you to add asciidoctor as a second option in the detection script? Otherwise, can you add a way to configure it's name?

[igaw]

Luckily find_programs excepts a list of names. Let's try this first. We can still make it more complex later :)

[spheenik]

Sorry, but I think I found out asciidoctor is another package, and seems to be different. Arch says, it's a asciidoc implementation in Ruby, but when I tried a clean build with asciidoctor, and the build fails:

[18/358] Generating Documentation/nvme_delete_ns_xml with a custom command
FAILED: Documentation/nvme-delete-ns.xml 
/usr/bin/asciidoc -f ../Documentation/asciidoc.conf -b docbook -d manpage -o Documentation/nvme-delete-ns.xml Documentation/nvme-delete-ns.msubst
asciidoctor: invalid argument: -f ../Documentation/asciidoc.conf
Usage: asciidoctor [OPTION]... FILE...
Convert the AsciiDoc input FILE(s) to the backend output format (e.g., HTML 5, DocBook 5, etc.)
Unless specified otherwise, the output is written to a file whose name is derived from the input file.
Application log messages are printed to STDERR.

(/usr/bin/asciidoc is a symlink to asciidoctor in this case) I am not sure how I got a complete build before, I suspect there were some leftovers that made the build succeed.

Anyhow, there is a package asciidoc in arch, and it also produces the command your build files were looking for.

Sorry for causing confusion, but I think it's better to revert the commit mentioned above.

[eli-schwartz]

asciidoc is the original python-based implementation of the asciidoc file format. asciidoctor is the ruby reimplementation that also builds the asciidoc format, but conveniently, builds a slightly different asciidoc format, on top of taking different command-line options, requiring ruby, and sneakily registering a trademark for someone else's project?

This docs are generated when the asciidoc program is found (from the asciidoctor project). In case the binary is called differently, we should be able to make it more configurable.

Perhaps the option to build manpages should force building it? Currently, setting the "docs-build" option to "true" causes meson.build to check for docs-build dependencies, and then only build if those docs-build dependencies are found. It's impossible for someone to say "I really want to build the docs, and if I cannot do so, the build should report an error".

Maybe it would be better to use a feature option?

asciiidoc = find_program('asciidoc', required: get_option('docs-build'))
if asciidoc.found()
    # build it
endif