https://projects.osmocom.org/https://projects.osmocom.org/favicon.ico?16647414092018-07-06T10:24:35ZOpen Source Mobile CommunicationsCellular Network Infrastructure - Feature #3386: Generate man pages at build time from adoc fileshttps://projects.osmocom.org/issues/3386?journal_id=102552018-07-06T10:24:35Zpespin
<ul><li><strong>Due date</strong> set to <i>07/09/2018</i></li><li><strong>Start date</strong> changed from <i>07/06/2018</i> to <i>07/09/2018</i></li><li><strong>Follows</strong> <i><a class="issue tracker-2 status-3 priority-2 priority-default closed" href="/issues/3385">Feature #3385</a>: Move project specific manuals from osmo-gsm-manuals to each respective git repository</i> added</li></ul> Cellular Network Infrastructure - Feature #3386: Generate man pages at build time from adoc fileshttps://projects.osmocom.org/issues/3386?journal_id=111052018-09-01T20:40:29Zlaforge
<ul><li><strong>Assignee</strong> changed from <i>4368</i> to <i>osmith</i></li></ul> Cellular Network Infrastructure - Feature #3386: Generate man pages at build time from adoc fileshttps://projects.osmocom.org/issues/3386?journal_id=125912018-11-15T09:42:06Zosmith
<ul><li><strong>Due date</strong> deleted (<del><i>07/09/2018</i></del>)</li></ul><p>(removed the confusing due date)</p> Cellular Network Infrastructure - Feature #3386: Generate man pages at build time from adoc fileshttps://projects.osmocom.org/issues/3386?journal_id=182872020-05-12T12:19:57Zlaforge
<ul><li><strong>Priority</strong> changed from <i>Normal</i> to <i>Low</i></li></ul> Cellular Network Infrastructure - Feature #3386: Generate man pages at build time from adoc fileshttps://projects.osmocom.org/issues/3386?journal_id=268702023-05-11T10:36:31Zosmith
<ul></ul><p>As this issue is assigned to me, some thoughts:</p>
<p>The full usermanuals are too verbose for man pages. Besides the volume of information, they also contain graphs that we can't display there.</p>
Therefore I suggest to write a short man page for each project instead with:
<ul>
<li>a description of the program</li>
<li>the command-line parameters</li>
<li>path to the config files</li>
<li>path to other files, e.g. the database for osmo-hlr</li>
<li>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 <a class="external" href="https://ftp.osmocom.org/docs/">https://ftp.osmocom.org/docs/</a></li>
<li>links to the git repository in gitea, bug tracker in redmine etc.</li>
</ul>
<p>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: <a class="external" href="https://manpages.debian.org/testing/scdoc/scdoc.5.en.html">https://manpages.debian.org/testing/scdoc/scdoc.5.en.html</a> (source: <a class="external" href="https://git.sr.ht/~sircmpwn/scdoc/tree/master/item/scdoc.5.scd">https://git.sr.ht/~sircmpwn/scdoc/tree/master/item/scdoc.5.scd</a>)</p>
<p>Note that right now debian doesn't build our usermanuals and vty references, I guess because of the dependencies that pulls in.</p> Cellular Network Infrastructure - Feature #3386: Generate man pages at build time from adoc fileshttps://projects.osmocom.org/issues/3386?journal_id=268722023-05-11T11:01:26Zlaforge
<ul></ul><p>The point of asciidoc [or some format that can generate man + asciidoc] is that the man pages can become a chapter in the manual</p> Cellular Network Infrastructure - Feature #3386: Generate man pages at build time from adoc fileshttps://projects.osmocom.org/issues/3386?journal_id=268762023-05-11T11:24:28Zosmith
<ul></ul><p>laforge wrote in <a href="#note-6">#note-6</a>:</p>
<blockquote>
<p>The point of asciidoc [or some format that can generate man + asciidoc] is that the man pages can become a chapter in the manual</p>
</blockquote>
<p>Sorry I misread that, makes more sense now.</p>