2022.06.11 21:20 "[Tiff] Converting manual pages to Sphinx ReStructured Text", by Roger

Hi folks,

I made a start on this today, and you can see the initial progress here: https://gitlab.com/libtiff/libtiff/-/commits/sphinx-manpages

So far, I've updated the CMake build logic to enable manpage generation and installation, and done a trial conversion of three manual pages which can be found here: https://gitlab.com/libtiff/libtiff/-/tree/b6022ee867384ab1f397a48943ed633532 d5772b/doc/man (files ending in .rst; the other files are yet to be converted).

As for the main manual, I'll need to go through each page to convert the troff mandoc markup to Sphinx markup. Once it's complete we should get proper cross-references between the manpages and the rest of the HTML manual when generating them as HTML, and there is the option of generating HTTP references in the generated manpages to link back to the HTML docs online when going the other way. This will likely take a few weeks since I don't expect to have a big block of time to dedicate as I did for the HTML manual, but should be fairly straightforward to do now the build and installation logic is in place. As before, I'll update the automake logic as well once the main work is done.

If we want to add an additional couple of dependencies, we could use Doxygen to generate most of the API reference from the sources and then convert that into rst for Sphinx to make into HTML or manual pages. Possibly something to consider for future investigation; I'll get the basic conversion done first.

Kind regards,

Roger