From 49cccd90f206605698accae18541d656f6342c9b Mon Sep 17 00:00:00 2001
From: Matheus Alcantara <mths.dev@pm.me>
Date: Mon, 9 Nov 2026 13:04:54 -0300
Subject: [PATCH v3 2/2] doc: Fix description of $system in
 extension_control_path

The documentation says that a list element of extension_control_path
that starts with $system gets the system extension directory
substituted for it.  However, since commit 81eaaa2c41d,
get_extension_control_directories() only recognizes an element that is
exactly "$system".  Any other element, like "$system/foo", is taken as
a literal path with the "extension" suffix appended, so CREATE
EXTENSION fails with a "not an absolute path" error, while
pg_available_extensions silently returns no rows for it.

Expanding $system as a prefix doesn't fit well with the path elements
being base directories to which "extension" is appended, since $system
already points to the extension directory itself.  So, rather than
changing the behavior, fix the documentation to say that the element
must be exactly $system.  While at it, clarify that $system is the
"extension" subdirectory of pg_config --sharedir and that the
"extension" suffix is not appended to it.

Backpatch to 18, where the current behavior was introduced.
---
 doc/src/sgml/config.sgml | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 0a94a7cac36..1f89be6eb04 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -11759,14 +11759,15 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
        <para>
         The value for <varname>extension_control_path</varname> must be a
         list of absolute directory paths separated by colons (or semi-colons
-        on Windows).  If a list element starts
-        with the special string <literal>$system</literal>, the
+        on Windows).  If a list element is
+        the special string <literal>$system</literal>, the
         compiled-in <productname>PostgreSQL</productname> extension
         directory is substituted for <literal>$system</literal>; this
         is where the extensions provided by the standard
         <productname>PostgreSQL</productname> distribution are installed.
-        (Use <literal>pg_config --sharedir</literal> to find out the name of
-        this directory.) For example:
+        (This is the <filename>extension</filename> subdirectory of the
+        directory shown by <literal>pg_config --sharedir</literal>.)
+        For example:
 <programlisting>
 extension_control_path = '/usr/local/share/postgresql:/home/my_project/share:$system'
 </programlisting>
@@ -11778,7 +11779,9 @@ extension_control_path = 'C:\tools\postgresql;H:\my_project\share;$system'
         subdirectory <filename>extension</filename> which will contain the
         <filename>.control</filename> and <filename>.sql</filename> files; the
         <filename>extension</filename> suffix is automatically appended to
-        each path element.
+        each path element other than <literal>$system</literal>.
+        <literal>$system</literal> cannot be combined with other path
+        components, as in <literal>$system/foo</literal>.
        </para>
 
        <para>
-- 
2.50.1 (Apple Git-155)