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

The conversion was automatic from HTML.  It will need a few tweaks, but

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

Historically, writing the documentation has been a reason for turning
developers away.  I hope using RST simplifies that.

-- Thomas Adam

Reply via email to