Project

General

Profile

Actions

Feature #3386

open

Generate man pages at build time from adoc files

Added by pespin over 5 years ago. Updated 10 months ago.

Status:
New
Priority:
Low
Assignee:
Target version:
-
Start date:
07/09/2018
Due date:
% Done:

0%

Spec Reference:

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).


Related issues

Follows Cellular Network Infrastructure - Feature #3385: Move project specific manuals from osmo-gsm-manuals to each respective git repositoryResolvedosmith07/06/2018

Actions
Actions #1

Updated by pespin over 5 years ago

  • 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
Actions #2

Updated by laforge over 5 years ago

  • Assignee changed from 4368 to osmith
Actions #3

Updated by osmith over 5 years ago

  • Due date deleted (07/09/2018)

(removed the confusing due date)

Actions #4

Updated by laforge almost 4 years ago

  • Priority changed from Normal to Low
Actions #5

Updated by osmith 10 months ago

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.

Actions #6

Updated by laforge 10 months ago

The point of asciidoc [or some format that can generate man + asciidoc] is that the man pages can become a chapter in the manual

Actions #7

Updated by osmith 10 months ago

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.

Actions

Also available in: Atom PDF

Add picture from clipboard (Maximum size: 48.8 MB)