Re: small fix for pg_overexplain docs

On Wed, 16 Jul 2025 at 18:26, Nathan Bossart <nathandbossart(at)gmail(dot)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(at)xzilla(dot)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 of the 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