Generate man pages at build time from adoc files
Once we have documentation being build in each project repository separately (see #3385), we want to generate man pages for each repository.
The idea here is to have an .adoc file with all the required content to be used in the man pag, and which is already included in the user manual. Then we need to scripts/makefile to transform this .adoc file into man source format and make it be build and installed when --enable-man is passed. Then, install it in the debian packages (which means we in turn need to modify dh_configure or similar to pass the --enable-man flag, and somehow include the common osmo-gsm-manuals.git in there when sending to OBS).
As this issue is assigned to me, some thoughts:
The full usermanuals are too verbose for man pages. Besides the volume of information, they also contain graphs that we can't display there.Therefore I suggest to write a short man page for each project instead with:
- a description of the program
- the command-line parameters
- path to the config files
- path to other files, e.g. the database for osmo-hlr
- where the user can find the full usermanuals and vty references - either in the filesystem if they were built, or in any case online at https://ftp.osmocom.org/docs/
- links to the git repository in gitea, bug tracker in redmine etc.
Regarding tooling, I think asciidoc is a bit heavy just to generate man pages. I would suggest scdoc, which has no dependencies and an installed size of < 100 KB. Like asciidoc, the format is easy to read and write: https://manpages.debian.org/testing/scdoc/scdoc.5.en.html (source: https://git.sr.ht/~sircmpwn/scdoc/tree/master/item/scdoc.5.scd)
Note that right now debian doesn't build our usermanuals and vty references, I guess because of the dependencies that pulls in.