Re: [PATCH] doc: Fix description of relative extension "directory" setting

Hi,

Thanks for the patch!

I tested extension_control_path with a few different "directory" values:
a relative 'scripts', the MODULEDIR style 'extension/foo', an absolute
path, 'extension' and no directory at all. In all cases the scripts were
loaded from where the new wording says they should be, and 'extension'
behaves the same as not setting it. The patch also applies cleanly on
REL_18_STABLE, which has the same wrong text, and the docs build fine.

I have some small comments:

1: The SHAREDIR vs extension_control_path wording

- the directory where the control file was found. By default,
- the script files are looked for in the same directory where the
- control file was found.
+ the installation's <literal>SHAREDIR</literal> directory, or to the
+ <xref linkend="guc-extension-control-path"/> element used to locate
+ the primary control file. The default behavior is equivalent to
+ specifying <literal>directory = 'extension'</literal>.

The "or" in the new sentence doesn't say when each case applies. If the
control file is found via $system, the extension_control_path element
is $system itself, which expands to SHAREDIR/extension, not SHAREDIR,
so the "element used to locate the primary control file" can still be
read as the extension subdirectory. Maybe something like this?

Unless an absolute path is given, the name is relative to the parent
of the extension directory where the primary control file was
found, that is, the installation's SHAREDIR directory, or the
corresponding extension_control_path element.

It's just a nit though, v2 is already much better than the current text.

2: Commit message

"relative to the installation's base directory, i.e., SHAREDIR or the
extension_control_path element" is a bit loose, since a custom path
element is not really the installation's directory. Just "the base
directory" would be enough IMO.

Unrelated to the "directory" fix, but while reading the
extension_control_path docs I noticed that it says "If a list element
starts with the special string $system, the compiled-in PostgreSQL
extension directory is substituted for $system", but
get_extension_control_directories() only accepts an exact match, so
something like '$system/foo' is not expanded. CREATE EXTENSION then
fails with "component in parameter "extension_control_path" is not an
absolute path", while pg_available_extensions silently skips it.

The attached v3 includes a 0002 that fixes the docs for this. 0001 is
the same as v2-0001, so the comments above still apply to it.

--
Matheus Alcantara
EDB: https://www.enterprisedb.com