On Thu Jan 29, 2026 at 4:43 PM UTC, Bear Giles wrote: > 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.
Hi Bear, I'm curious if you planned to follow through on the proposal. I think it sounds pretty interesting. -- Tristan Partin PostgreSQL Contributors Team AWS (https://aws.amazon.com)
