Building and packaging NUT on a system without man page generation tools

[jimklimov]

A troubleshooting session is slowly unrolling at the moment, to build recent NUT for OmniOS (so long as #1498 remains unsolved directly).

There is a neat make package recipe in NUT, which supports legacy SVR4 tooling to make a monolithic package from whatever was built. This relied on dist goal however, which needs to store pre-built docs, and that failed out of the box.

• For CI runs we have trick options to skip the docs and explicitly make an invalid dist archive
• For package it is in fact not really a needed prerequisite, except for AIX RPM (which calls $(MAKE) dist explicitly

Still, a loose thread in the world to pull...

One trouble that remained unresolved is that the asciidoc toolkit provided there can not in fact build man pages (or I did not pick the right set of dependency packages to make it happen). HTMLs are built, and there was a manual installation of docbook-xml with registration via xmlcatalog to let PFDs happen. So some things work but not everything yet, at least on my testbeds.

jim@donutci-oo:~/nut/docs$ "xmllint" --nonet --noout --valid "/export/home/jim/nut/docs/tmp/pdf.user-manual.pdf.3958/user-manual.xml"
I/O error : Attempt to load network entity http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd
 /export/home/jim/nut/docs/tmp/pdf.user-manual.pdf.3958/user-manual.xml:2:
 warning: failed to load external entity "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
 D DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
                                                                                 ^
/export/home/jim/nut/docs/tmp/pdf.user-manual.pdf.3958/user-manual.xml:6: validity error : Validation failed: no DTD found ! 

• ooce/text/docbook-xsl is installed but files the issue references are not on the system (nor in that pkg contents)
• https://www.linuxfromscratch.org/blfs/view/svn/pst/docbook.html copy-pasta worked (modulo arguments to cp in the beginning) with https://mirrors.omnios.org/docbook/docbook-xml-4.5.zip

So the next idea was to use the "dist archive" instead of a build from git, as the recently added GHA jobs produce them nicely. Hard to find, led to adding a https://github.com/networkupstools/nut/wiki/Finding-recent-development-iteration-artifacts wiki page.

It seems the configure --with-docs=dist-auto may have to be used to ship the man pages from tarball instead of locally built ones.

• It remains to be confirmed if this is also required when the system can not generate man pages - that would be wrong then
• However that now stumbles on the smart platform-dependent defaults for man page sections (which differ in Solaris legacy from what Linux/BSD prefer). Automatic platform-dependent setting of --with-docs-man-section-api etc. default section numbers should be neutered if shipping files from tarballs (keep their extensions, even if wrong for the target distro; perhaps warn about that).