man3 Documentation
Out of curiosity, I was trying to understand what man pages we generate.
I found man pgaes for the executables in man1 and a ton of documentation
in man7 related to SQL commands. The contents in man3 was a bit
perplexing. We only document a set of dblink SQL functions and a set of
SPI C functions.
Why do we document only those functions? I assume it was the wild west
(1998 and 2007) when the SGML for SPI and dblink were ported/created,
and the original authors, Thomas Lockhart[0]https://github.com/postgres/postgres/commit/c8cfb0cea88fec22f5aa0582fe846b46baf77eb1 and Bruce[1]https://github.com/postgres/postgres/commit/c3c69ab4fd25a20749b850d34cbc8ce3f1812e3b, simply did it
because they could.
I ask because I am trying to ascertain what our policy is for
documenting functions in man3. I was thinking it could be a cool
endeavor to increase coverage, but obviously it's not worth pursuing if
it would never be committed. If we don't want to continue documenting
things in man3, should we instead remove these pages?
I did look into the mailing list a bit, and I found a thread[2]/messages/by-id/CALBNtw4FDq_tWYErCeKO3djPEu8XHU0yKRv=5ZLUcN-FBP22tg@mail.gmail.com from Bear
proposing documenting libpq in man3 and man7.
[0]: https://github.com/postgres/postgres/commit/c8cfb0cea88fec22f5aa0582fe846b46baf77eb1
[1]: https://github.com/postgres/postgres/commit/c3c69ab4fd25a20749b850d34cbc8ce3f1812e3b
[2]: /messages/by-id/CALBNtw4FDq_tWYErCeKO3djPEu8XHU0yKRv=5ZLUcN-FBP22tg@mail.gmail.com
--
Tristan Partin
PostgreSQL Contributors Team
AWS (https://aws.amazon.com)
On 04.08.26 20:52, Tristan Partin wrote:
Out of curiosity, I was trying to understand what man pages we generate.
I found man pgaes for the executables in man1 and a ton of documentation
in man7 related to SQL commands. The contents in man3 was a bit
perplexing. We only document a set of dblink SQL functions and a set of
SPI C functions.
Man pages are produced for all refentry markup. If you want to add
more, you would have to format the material to fit into that schema. I
think proposals for more man pages could be considered.
On 2026-Aug-05, Peter Eisentraut wrote:
On 04.08.26 20:52, Tristan Partin wrote:
Out of curiosity, I was trying to understand what man pages we generate.
I found man pgaes for the executables in man1 and a ton of documentation
in man7 related to SQL commands. The contents in man3 was a bit
perplexing. We only document a set of dblink SQL functions and a set of
SPI C functions.Man pages are produced for all refentry markup. If you want to add more,
you would have to format the material to fit into that schema. I think
proposals for more man pages could be considered.
A few months ago I looked into changing the libpq documentation to
refentry format specifically to get a manpage for each function.
Eventually I decided not to do anything because most of them were way
too short and it looked a bit odd, and the current format is too
different from what the end shape would have to be. But maybe it's not
that bad. In principle I +1 the idea for libpq.
Not sure what else would be appropriate to turn into refentry, but I'd
say let's start with one section.
--
Álvaro Herrera PostgreSQL Developer — https://www.EnterpriseDB.com/