Feature #3386
open
Generate man pages at build time from adoc files
Added by pespin almost 6 years ago.
Updated 11 months ago.
Description
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).
- Due date set to 07/09/2018
- Start date changed from 07/06/2018 to 07/09/2018
- Follows Feature #3385: Move project specific manuals from osmo-gsm-manuals to each respective git repository added
- Assignee changed from 4368 to osmith
- Due date deleted (
07/09/2018)
(removed the confusing due date)
- Priority changed from Normal to Low
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.
The point of asciidoc [or some format that can generate man + asciidoc] is that the man pages can become a chapter in the manual
laforge wrote in #note-6:
The point of asciidoc [or some format that can generate man + asciidoc] is that the man pages can become a chapter in the manual
Sorry I misread that, makes more sense now.
Also available in: Atom
PDF
