Обсуждение: Add documentation for PG_ABS_SRCDIR, PG_ABS_BUILDDIR, PG_LIBDIR, PG_DLSUFFIX

Hi all,

d1029bb5a26c has switched the in-core tests suited based on pg_regress
to do path substitutions based on the set of environment variables
listed in $subject, rather than replacements based on input and output
files, generating new files.

These can be really useful for extension developers who maintain SQL
test suites, so how about documenting them?

I'd like to propose the attached patch, for HEAD, so as one does not
need to guess their existence from the SQL files or pg_regress.c.

Thoughts or comments?
--
Michael

On Wed, Mar 11, 2026 at 11:10:44AM +0800, zhanghu wrote:
> The doc changes look good overall. I applied the patch locally and rendered
> the documentation to HTML, the new page also looks good.
>
> A few minor nitpicks:
>
> +       <para>
> +        Name of extension for dynamically-loadable modules (e.g.
> +        <literal>.so</literal> on Linux).
> +       </para>
>
> I think we need a "the" before "dynamically-loadable".

Don't think this one's necessary here, actually, as it refers to a
general concept around modules.

> +      These are useful when dealing with function and object loading
> +      that require specific paths to work, like paths defined in a
> +      <command>CREATE FUNCTION</command> or <command>LOAD</command>
> +      command, for example.
>
> The ending "for example" sounds redundant, since "like" already conveys the
> meaning of "for example".

WFM.
--
Michael

> On Mar 12, 2026, at 05:34, Michael Paquier <michael@paquier.xyz> wrote:
>
> On Wed, Mar 11, 2026 at 11:10:44AM +0800, zhanghu wrote:
>> The doc changes look good overall. I applied the patch locally and rendered
>> the documentation to HTML, the new page also looks good.
>>
>> A few minor nitpicks:
>>
>> +       <para>
>> +        Name of extension for dynamically-loadable modules (e.g.
>> +        <literal>.so</literal> on Linux).
>> +       </para>
>>
>> I think we need a "the" before "dynamically-loadable".
>
> Don't think this one's necessary here, actually, as it refers to a
> general concept around modules.
>
>> +      These are useful when dealing with function and object loading
>> +      that require specific paths to work, like paths defined in a
>> +      <command>CREATE FUNCTION</command> or <command>LOAD</command>
>> +      command, for example.
>>
>> The ending "for example" sounds redundant, since "like" already conveys the
>> meaning of "for example".
>
> WFM.
> --
> Michael


I checked d1029bb5a26c, and based on that, the doc change overall looks good to me.

I have a small observation regarding "e.g.”.

Since "e.g." is equivalent to "for example," and "for example" is commonly followed by a comma, my impression was that
"e.g."should also follow one. I did a quick search across all SGML files to check the existing convention: 
```
chaol@ChaodeMacBook-Air postgresql % grep -RohF --include='*.sgml' 'e.g.' . | wc -l
     328
chaol@ChaodeMacBook-Air postgresql % grep -RohF --include='*.sgml' 'e.g.,' . | wc -l
     239
chaol@ChaodeMacBook-Air postgresql % grep -RohF --include='*.sgml' 'e.g.:' . | wc -l
      55
chaol@ChaodeMacBook-Air postgresql % grep -RohF --include='*.sgml' 'e.g. ' . | wc -l
      31
```

It looks like the usage isn't entirely consistent, but the vast majority use a following punctuation mark. Only about
1/10use "e.g." followed only by a space. 

While the inconsistency is already there and a dedicated cleanup might not be worthwhile, my preference is still to
limitthe inconsistency. 

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/

On Thu, Mar 12, 2026 at 08:08:39AM +0800, Chao Li wrote:
> While the inconsistency is already there and a dedicated cleanup
> might not be worthwhile, my preference is still to limit the
> inconsistency.

Honestly, for some it may come to a difference between American
English (mostly with comma) vs British English (no comma), so at the
end both styles should be OK.  I have let that as-is after considering
the whole with fresher eyes.  One thing that felt missing is a mention
about \getenv, that one would need to be able to reuse these
variables.  Added a paragraph for that, and applied the result.
--
Michael