Re: mention unused_oids script in pg_proc.dat

On Tue, Jul 1, 2025 at 12:25 PM Peter Eisentraut <peter(at)eisentraut(dot)org>
wrote:

> 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.
>

In practice people go to the git history to see the files touched by
similar commits,
and devise a to-do-list for their case.
so I think it helps them a lot to see some high-level READMEs waiting for
them there.

In this particular case, unused_oids isn't included in any commits so you
can't be aware of its existence even

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

Done

>
> > +
> > +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?
>

I agree. Added a link reference to that xfunc-c

Some basic stuff that was missing in xfunc, I've already added in 86e4efc .
For now I think it's good enough.