Hi flashromers,
For all the time I'm now working on flashrom I've avoided to touch the man-page. The reason: it is written in plain groff (the manpage format), which is, IMO, neither great to read in source nor makes it fun to edit.
Nowadays there are a lot of tools for converting a source readable format like md or rst into groff / man-pages. So I've played around with some and found a solution with `Sphinx`[0] that might fit flashrom well. Sphinx is well known in the Open Source Community for project documentation. Coreboot, the Linux kernel and many other projects are using it already. So it is time tested and nothing really new. Beside rendering to html sides, sphinx is also capable to render groff/manpages which is quite nice.
My reason for choosing sphinx over other tools was: - It is known to many people - reStructuredText is easy to read and write - It can produce groff/manpages *and* html without plugins/extensions/quirks - It is, like our meson based build system, written in python. So it runs where the build system runs and has no additional software stack like nodejs or ruby on rails - It is extendable to our needs (e.g. generate documentation from data with python)
The conversion of the manpage from groff to sphinx/rst can be found here: https://review.coreboot.org/c/flashrom/+/72619
Going forward I would also like to suggest integrating the existing documentation of the Wiki to Sphinx (flashrom source / Gerrit) and supersede the current homepage with it.
What do you think about this?
-- Thomas