On Mon, Apr 04, 2016 at 11:14:59PM +0100, Thomas Adam wrote: > Hi all, > > I've started to look at moving away from using docbook for man page > generation, and instead using markdown as the base format which can then be > converted to nroff and HTML, etc.
So I've looked again. markdown is an OK format for this, but the generation of markdown -> nroff is far from perfect. Thankfully, there's RST (http://docutils.sourceforge.net/rst.html) which can be used instead; similar to Markdown if nothing else. On most systems, there's rst* programs from the 'python-docutils' package which we can use to provide the conversion. To that end, I've removed everything in doc/* and instead, added a 'manpages' directory with a single file in there which is the basis file for the fvwm man page. The conversion was automatic from HTML. It will need a few tweaks, but running: rst2html manpages/fvwm.rst > manpages/fvwm.1 and then viewing the man page: mandoc ./manpages/fvwm.1 | less is a good start. Anyone who wants to pick this up, do please let me know. I'll also add this into the the build at some point, assuming people are happy with this as a way forward. Historically, writing the documentation has been a reason for turning developers away. I hope using RST simplifies that. -- Thomas Adam
