Re: mention unused_oids script in pg_proc.dat

On 24.05.25 12:34, Florents Tselai wrote:
>
>
>> On 24 May 2025, at 12:24 PM, Álvaro Herrera <alvherre(at)kurilemu(dot)de> wrote:
>>
>> On 2025-May-24, Florents Tselai wrote:
>>
>>> I aggree with having more READMEs around the src tree.
>>> It’s true that a lot of doc content found in VII. Internals is dev-oriented,
>>> but imho it should be closer to the src (and more succinct/less verbose too).
>>
>> Maybe these READMEs can simply contain little more than links to the
>> built HTML docs, to avoid having multiple sources of info.
>>
>>> Looking at some of the text in 67.2.2. OID Assignment for example,
>>> a few things look outdated wrt choosing OIDs.
>>>
>>> One can look through the history of similar commits to see what
>>> needs to be changed; So it’s not THAT bad.
>>
>> Sure, outdated docs is something that happens. Patches welcome.
>>
>
> Something like this ?

> diff --git a/src/include/catalog/README b/src/include/catalog/README
> new file mode 100644
> index 00000000000..5bd81c6d86c
> --- /dev/null
> +++ b/src/include/catalog/README
> @@ -0,0 +1,11 @@
> +# Catalog
> +
> +For more details see https://www.postgresql.org/docs/current/bki.html

I can see that having a README in src/include/catalog/ would be useful.
That directory contains some "unusual" files, and some hints about them
would be good. Before commit 372728b0d49, we used to have a README in
src/backend/catalog/README, but then this was moved to the SGML
documentation. Maybe you can read up there why this was chosen. But I
think src/include/catalog/ would be a better location in any case.

Maybe for now just a link like you show would be ok. (But it should
probably be s/current/devel/.)

> +
> +Below are some checklists for common scenarios.
> +
> +## Adding a New Built-in SQL Command
> +
> +1. Implement the function in C and place it in the appropriate
directory under `src` (typically in `src/utils/adt`)
> +2. Each function should have a unique integer OID. Run the script
`src/include/catalog/unused_oids` to find available ranges.
> +3. Add the entry to `pg_proc.dat` following the surrounding conventions.

Presumably, if you're developing this kind of thing, you are already
reading some other part of the documentation, maybe xfunc.sgml? Do we
need to add more information there, or some links?