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.

Using markdown for this seems sensible---using just nroff (or my preference,
mdoc) is one solution, but not as accessible to everyone, and since we've a
*lot* of options in FVWM, the documentation needs to be easier to manipulate
and have others contribute to, hence why I'm keen to go with plain text in
this regard.

So far, I've got something lashed together, but it is just mechanical
conversions at the moment.  There's a lot more that needs to happen which I'll
outline below.  However, I'm hoping I'm not the person to do this, although
I'll happily help/mentor anyone who wishes to pick up from where I've started.

What I've done so far is used pandoc to convert the existing Docbook files
(XML) to Markdown.  I've not checked extensively whether this was successful,
but by-and-large it seems to have been.

Then, I moved all the generated files to a new top-level directory, "manpages"
and added a file in there called ORDER which details how the Markdown files
should be catted together to form one huge markdown file which will be the
fvwm man page.

There's a script called 'generate_manpages.sh' which does all of this
mechanically.   Run it from within the manpages directory.

The conversion of markdown -> nroff is done using a program called 'ronn',
found here:


But all is not perfect.   Install 'ronn' and see for yourself what it spits

Anyone who's interested in this needs to:

* Audit the markdown files to ensure the conversion is complete;
* Think whether we need all of the individual .md files or whether we can
  amalgamate.  I suspect we can quite a bit.  I'm keen not to see one huge
  file again.
* Fix up a lot of warnings from the markdown files converting to nroff;
* Hook these things into the buildsystem, removing the Docbook files.

Any questions, do please ask.  Any offers of help, *definitely* let me know.
You can find my efforts here:


Specifically, the 'ta/docs-to-md' branch.

Thomas Adam

Reply via email to