Re: small fix for pg_overexplain docs

On Wed, 16 Jul 2025 at 18:26, Nathan Bossart <nathandbossart@gmail.com> wrote:
>
> On Tue, Jul 15, 2025 at 04:14:44PM +0100, Dean Rasheed wrote:
> > On Tue, 15 Jul 2025 at 04:17, Robert Treat <rob@xzilla.net> wrote:
> >> On Mon, Jul 14, 2025 at 3:22 PM David G. Johnston
> >> > The pg_overexplain extends EXPLAIN with new options that provide...
> >> > Suggest instead:
> >> > The pg_overexplain module provides EXPLAIN with new options intended to assist with debugging of and development
ofthe planner. 
> >> > (replacing the first two sentences of the existing paragraph)
> >>
> >> +1 for consistency, though I'd argue "intended to assist with
> >> debugging and development of the planner" would be easier to read (in
> >> either one sentence or two sentence format).
> >
> > +1. I find that easier to read.
>
> I disagree.  While it might sound nicer, the extra "of" establishes
> parallelism to make it clear that the module is intended for debugging of
> the planner and not debugging in general.

Hmm, I would normally only do that if it was 2 different prepositions,
and even then, I find it kind-of clunky. But I don't feel particularly
strongly one way or the other.

> > Something else that's missing is instructions on how to load the
> > module, which usually follows this first paragraph.
>
> Good point.  That should probably look something like this, which is mostly
> lifted from auto_explain:
>
>         To use it, simply load it into the server.  You can load it into an
>         individual session:
>
>         LOAD 'pg_overexplain';
>
>         (You must be superuser to do that.)  You can also preload it into some
>         or all sessions by including pg_overexplain in
>         session_preload_libraries or shared_preload_libraries in
>         postgresql.conf.

Seems reasonable.

> As an aside, the superuser note isn't totally true because administrators
> can put stuff in $libdir/plugins/ to allow non-superusers to LOAD it.
> Maybe we should just remove the superuser note in the module docs.

Maybe. It's kind-of annoying that all the modules that aren't
extensions use different text. Maybe there are genuine differences --
I didn't look too closely. It would be nice if we just had one
standard description that they all could refer to, but if that's
possible, it's a much bigger patch than you probably want to worry
about here, so I'm happy to go with your text above.

Regards,
Dean