CI: Check asciidoc link/linkdoc/... validity during builds

[jimklimov]

As confirmed during issue #1957 investigation, we can generate documentation entries intended to be cross-linked (within the present set of documents) with such links leading nowhere in fact, e.g. if some anchors were planned but forgotten, lost in refactoring, mis-typed or with wrong markup so not recognized, etc.

This issue is about somehow (using asciidoc itself? parsing the HTMLs/PDFs?) determining that documentation links which should lead to targets in the same codebase (not absolute URLs) in fact lead nowhere, and making it a fatal problem for automated builds eventually.

Feels related to #823 (fightwarn in C/C++ code) :)

For examples currently online, a generated wrong link for "A.2.2 ups: General unit information -> ups.status -> OL" looks like this:

• in PDF:

  https://networkupstools.org/docs/developer-guide.pdf#[0,{%22name%22:%22Fit%22}]
  

• in HTML:

  https://networkupstools.org/docs/developer-guide.chunked/index.html
  

For comparison, a nearby link to "NUT daisychain support notes" looks like this:

• in PDF:

  https://networkupstools.org/docs/developer-guide.pdf#daisychain
  

• in HTML:

  https://networkupstools.org/docs/developer-guide.chunked/apb.html
  

[jimklimov]

When it gets to this, also check if nut-website handles these links somehow differently compared to "local HTML" documentation builds. Maybe the solution would need to cater to many situations.

[jimklimov]

FWIW, it may make sense to adopt somehow the auto-URI scheme which includes the original filename, and makes some things easier, maybe. Looking at URLs like https://git-scm.com/docs/pretty-formats#Documentation/pretty-formats.txt-emnem as inspiration for this part of the idea.

[jimklimov]

Related to networkupstools/nut-website#52 and (partially?) addressed by networkupstools/nut-website#53 and networkupstools/nut-website#54 introducing htmlproofer check ability into NUT-Website builds.

At the moment the subject is left "as is". Some issues were found and fixed, others await their time, and it does not seem like something for NUT CI to pick up soon, as the check takes tens of minutes (maybe a bit less if not crawling external dead links, but only cross-page references).