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: https://github.com/rtomayko/ronn But all is not perfect. Install 'ronn' and see for yourself what it spits out. 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: https://github.com/fvwmorg/fvwm/tree/ta/docs-to-md Specifically, the 'ta/docs-to-md' branch. Kindly, Thomas Adam
