search

openv / vcontrold

:fire: vcontrold Daemon for control and logging of Viessmann® type heating devices
https://github.com/openv/openv/wiki
GNU General Public License v3.0
102 stars 57 forks source link

manual pages #10

Closed speters closed 6 years ago

speters commented 6 years ago

This branch features

I don't partially like the heavy build requirements for md2man, as it relies on ruby and a whole bunch of modules. Maybe it is better to supply pre-generated *.1.gz manual files with the sources and just optionally re-create them from markdown.

I chose markdown over rst, because it looked like it is the standard format on GitHub and is also used throughout the openv wiki.

speters commented 6 years ago

I attached the converted manpages: $ man -l vclient.1.gz $ man -l vcontrold.1.gz $ man -l vsim.1.gz

l3u commented 6 years ago

I think that Markdown is not a good choice here.

Correct me if I'm wrong, but as far as I know, there only exists some definition of it along with some reference implementation in Perl. And that only covers the conversion of Markdown to XHTML. Additionally, this "standard" seems not to be specified unambiguously (cf. http://commonmark.org/).

Tools doing the conversion to troff we need here are third-party tools. The tool you mention above is not even part of the official Gentoo package repository Portage (we have something called dev-go/go-md2man here, referring to https://github.com/cpuguy83/go-md2man/). This leads to the problem that – even if we would choose to generate the manpages build-time (which would be surely the better approach than packaging pre-processed output files in a CVS), we can't rely on such a tool to even exist on the distribution the user is on.

ReStructuredText is in contrast, along with all the conversion tools (including rst2man.py) is distributed via Python's Docutils. All part of one official package, which is most probably already installed on the user's system, or at least available so that an optional dependency to this could be satisfied at all. Using RST, we could definitely build the manpages from the sources when compiling the project instead of tracking process data. This can also be switched on and off via a cmake switch or made optional (we build it if we have it, we don't if we don't).

Briefly: (My personal opinon in addition to the hopefully solid arguments above is:) Only because Markdown earned some poularity lately because some flavor of it is being used on Github for comments and whatnot, it's not neccesarily the best choice for everything ;-)

speters commented 6 years ago

The rst2man argument is just too convincing.