This started because I was looking for MAN pages for a number of functions. They're documented on the website but there aren't MAN pages for them.
(Except SPI_*, and I don't think they're bundled in any of the debian/ubuntu packages by default. However I would need to double check.)
Doxygen is a common approach for this - it only requires annotating code comments that should already be there (*cough*) and can produce Docbook/SGML in addition to manpages, HTML, Latex, etc.
But... libpq has a lot of functions, it is not clear what purpose many of them serve, etc., so MAN 3 pages won't be enough.
Enter OpenSSL. If you look at its documentation it has a MAN 3 page for each function, but more importantly it also has MAN 7 pages that provide the context required to use a number of related functions. With libpq there would be a 1-to-1 relationship between the official documentation and a MAN 7 page. (Mostly - there are some pages with a single deprecated function so they don't need to be added.)
Each of these pages would refer to the official pages... and working sample code.
I have a POC implementation and plan to create a PR for other people to review later. I'm currently focused on getting some sample code to compile but this is far enough along that a PR shouldn't take long to produce. I wanted to give you a heads up since the man and related HTML pages should definitely be included in libpq-dev.
......
On a similar note I saw the SPI_* pages - and the same thing applies. Custom extensions using the API, not a PGXN wrapper, is not for the faint hearted. But if someone is willing to take it on it would be a tremendous help to have some MAN 7 pages that cover the required macros, palloc/pfree, the fact that each connection/session runs in its own thread, etc.
Bear
