From: Tom Lane <tgl@sss.pgh.pa.us>
To: Andres Freund <andres@anarazel.de>
cc: Andrew Dunstan <andrew@dunslane.net>, Robert Haas <robertmhaas@gmail.com>,
        "pgsql-hackers@postgresql.org" <pgsql-hackers@postgresql.org>
Subject: Re: documentation structure
In-reply-to: <20240416182310.2j6g5fqqcwi4s6wm@awork3.anarazel.de>
References: <CA+TgmoZ2F+K0j=6BOJLD=YfpJMdJRXC7sWmtXGRjx1Rq0x8PUA@mail.gmail.com> <CAD5tBcJUVQu=9zpr9C+Z=3SjxrECURtr_i1oipMqke4dpZXtyQ@mail.gmail.com> <20240416182310.2j6g5fqqcwi4s6wm@awork3.anarazel.de>
Comments: In-reply-to Andres Freund <andres@anarazel.de>
	message dated "Tue, 16 Apr 2024 11:23:10 -0700"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <1355790.1713294332.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable
Date: Tue, 16 Apr 2024 15:05:32 -0400
Message-ID: <1355791.1713294332@sss.pgh.pa.us>
Archived-At: <https://www.postgresql.org/message-id/1355791.1713294332%40sss.pgh.pa.us>
Precedence: bulk

Andres Freund <andres@anarazel.de> writes:
> I think we should work on generating a lot of func.sgml.  Particularly t=
he
> signature etc should just come from pg_proc.dat, it's pointlessly painfu=
l to
> generate that by hand. And for a lot of the functions we should probably=
 move
> the existing func.sgml comments to the description in pg_proc.dat.

Where are you going to get the examples and text descriptions from?
(And no, I don't agree that the pg_description string should match
what's in the docs.  The description string has to be a short
one-liner in just about every case.)

This sounds to me like it would be a painful exercise with not a
lot of benefit in the end.

I do agree with Andrew that splitting func.sgml into multiple files
would be beneficial.

			regards, tom lane