Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: Martin Ågren <martin.agren@gmail.com>
Date: May 10, 2021, 18:43 UTC
Message-ID: <CAN0heSrcZrfD60SJW9pJADwF8=SQ3Zw0KW1ZZvF4EPh82cNtPw@mail.gmail.com>
In-Reply-To: <CAMP44s3wagd6pk-YfnYV3QoRbZ5cRA0MBU4=Mdxerbdx80J7hw@mail.gmail.com>

On Sun, 9 May 2021 at 20:46, Felipe Contreras <felipe.contreras@gmail.com> wrote:

>
> Are there some minimal requirements to say; this documentation was
> built correctly (as far as we know)? If so, maybe we can add a
> checker, or perhaps add a test under t/.

There's `make check-doc` which does some linting. But that's about checking that there's a manpage at all for each builtin, that the doc sources list sections in the right order, and such things. It doesn't actually build the docs.

ci/test-documentation.sh runs `make check-doc` (see above), then goes on to actually build the docs using both asciidoc and asciidoctor. It checks the exit status, but also that stderr is empty after filtering out some expected, harmless output.

I think that's about the right balance. We could perhaps do something under t/, but it probably shouldn't be to actually build the stuff. More like, "oh, you've built the documentation -- let me sanity-check it for you". One way to detect that it makes sense to check it might be to see if the Git version in the manpage footer(s) matches the version under test. But I don't know what to check next. (Actually, if we do find the version number there, we have verified a fairly tricky piece of content injection. At least "tricky" as in "we have more than one way of doing it, because we support more than one toolchain" [1]. And if that stuff broke, the test wouldn't notice, if we relied on detecting a version match to even start testing...)

[1] See 7a30134358 ("asciidoctor-extensions: provide `<refmiscinfo/>`", 2019-09-16) and its parent commit.

Martin