Use asciidoctor to generate man pages from asciidoc sources

[hansu]

asciidoctor does a much better job in converting the man pages from the asciidoc format than a2x.
But asciidoctor needs to be installed on the CI.

Resolves #3057

[hansu]

1. Does anyone knows how to install software on the GitHub CI?
2. Man pages which include other man pages makes some problems
   e.g. I get
   make: *** No rule to make target '../docs/man/millturn.1', needed by '../docs/html/man/man1/millturngui.1.html'. Stop.
   The millturn.1 man page is generated from milltun.1.adoc, but millturngui.1 just consists of ".so millturn.1" - there is no millturngui.1.adoc. I wonder how does it know to include that man page?

[petterreinholdtsen]

[Hans Unzner]

2. Man pages which include other man pages makes some problems e.g. I get ` make: *** No rule to make target '../docs/man/millturn.1', needed by '../docs/html/man/man1/millturngui.1.html'. Stop. ` The millturn.1 man page is generated from milltun.1.adoc, but millturngui.1 just consists of ".so millturn.1" - there is no millturngui.1.adoc. I wonder how does it know to include that man page?

How do you trigger this problem? I have not seen it. the .SO pages are generated when there are several names listed in a .adoc manpage, the first one get the content, the rest get a .SO redirect.

…

-- Happy hacking Petter Reinholdtsen

[hansu]

How do you trigger this problem?

Just build the docs from this branch (with first asciidoctor installed)

the .SO pages are
generated when there are several names listed in a .adoc manpage, the
first one get the content, the rest get a .SO redirect.

So the last line here generates an include for millturngui? Interesting automatism.

== NAME

millturn, millturngui - Vismach Virtual Machine GUI

[andypugh]

`make: *** No rule to make target '../docs/man/millturn.1', needed by '../docs/html/man/man1/millturngui.1.html'.

This sounds familiar, in that millturn and friends were the subject of a recent commit, is this related?

5d44850

[hansu]

Yes and the problem is more that we have now one man page for millturn and one for millturngui where we had only one for both before. But that one I got resolved with Petters hint, now I am at the man3 pages...

[hansu]

This man page for example

= rtapi_module_param(3rtapi)

== NAME

rtapi_module_param, EXPORT_FUNCTION, RTAPI_MP_INT, RTAPI_MP_LONG,
RTAPI_MP_STRING, RTAPI_MP_ARRAY_INT, RTAPI_MP_ARRAY_LONG,
RTAPI_MP_ARRAY_STRING, MODULE_LICENSE, MODULE_AUTHOR,
MODULE_DESCRIPTION - Specifying module parameters

creates files like EXPORT_FUNCTION.3
which contains .so rtapi_module_param.3
So far so good.
But it fails when trying to generate the HTML pages:

make: *** No rule to make target '../docs/man/rtapi_module_param.3', needed by '../docs/html/man/man3/EXPORT_FUNCTION.3.html'. Stop.

If I omit the including like I started in d52975b but there should be way to fix it without that.

As I have no idea, I will close that. Seems we have to live with the slightly ugly man pages now.

If someone has an idea to fix that, feel free to open this again.