Re: Proposal: doxygen + MAN 7 pages

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)