Upgrade documentation connected with shared_preload_libraries et al.

tglsfdc · tglsfdc · commit ba63dbd9edc0 · 2017-06-20T13:40:06.000-04:00
Noplace in the documentation actually defined what these variables contain. Define them as lists of arguments for LOAD, and improve that command's documentation a bit. Discussion: https://postgr.es/m/CAB-oJtxHVDc3H+Km3CjB9mY1VDzuyaVH_ZYSz7iXcRqCtb93Ew@mail.gmail.com
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
@@ -7003,12 +7003,6 @@ SET XML OPTION { DOCUMENT | CONTENT };
       <literal>tcl</>, or <literal>python</>.
      </para>
 
-     <para>
-      For each parameter, if more than one library is to be loaded, separate
-      their names with commas.  All library names are converted to lower case
-      unless double-quoted.
-     </para>
-
      <para>
       Only shared libraries specifically intended to be used with PostgreSQL
       can be loaded this way.  Every PostgreSQL-supported library has
@@ -7037,6 +7031,10 @@ SET XML OPTION { DOCUMENT | CONTENT };
        <para>
         This variable specifies one or more shared libraries that are to be
         preloaded at connection start.
+        It contains a comma-separated list of library names, where each name
+        is interpreted as for the <xref linkend="SQL-LOAD"> command.
+        Whitespace between entries is ignored; surround a library name with
+        double quotes if you need to include whitespace or commas in the name.
         The parameter value only takes effect at the start of the connection.
         Subsequent changes have no effect.  If a specified library is not
         found, the connection attempt will fail.
@@ -7083,10 +7081,15 @@ SET XML OPTION { DOCUMENT | CONTENT };
       <listitem>
        <para>
         This variable specifies one or more shared libraries that are to be
-        preloaded at connection start.  Only superusers can change this setting.
+        preloaded at connection start.
+        It contains a comma-separated list of library names, where each name
+        is interpreted as for the <xref linkend="SQL-LOAD"> command.
+        Whitespace between entries is ignored; surround a library name with
+        double quotes if you need to include whitespace or commas in the name.
         The parameter value only takes effect at the start of the connection.
         Subsequent changes have no effect.  If a specified library is not
         found, the connection attempt will fail.
+        Only superusers can change this setting.
        </para>
 
        <para>
@@ -7120,9 +7123,13 @@ SET XML OPTION { DOCUMENT | CONTENT };
       <listitem>
        <para>
         This variable specifies one or more shared libraries to be preloaded at
-        server start.  This parameter can only be set at server
-        start.  If a specified library is not found, the server will fail to
-        start.
+        server start.
+        It contains a comma-separated list of library names, where each name
+        is interpreted as for the <xref linkend="SQL-LOAD"> command.
+        Whitespace between entries is ignored; surround a library name with
+        double quotes if you need to include whitespace or commas in the name.
+        This parameter can only be set at server start.  If a specified
+        library is not found, the server will fail to start.
        </para>
 
        <para>
diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
@@ -541,8 +541,9 @@ CREATE [ OR REPLACE ] FUNCTION
        dynamically loadable C language functions when the function name
        in the C language source code is not the same as the name of
        the SQL function. The string <replaceable
-       class="parameter">obj_file</replaceable> is the name of the
-       file containing the dynamically loadable object, and
+       class="parameter">obj_file</replaceable> is the name of the shared
+       library file containing the compiled C function, and is interpreted
+       as for the <xref linkend="SQL-LOAD"> command.  The string
        <replaceable class="parameter">link_symbol</replaceable> is the
        function's link symbol, that is, the name of the function in the C
        language source code.  If the link symbol is omitted, it is assumed
diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml
@@ -38,11 +38,12 @@ LOAD '<replaceable class="PARAMETER">filename</replaceable>'
   </para>
 
   <para>
-   The file name is specified in the same way as for shared library
-   names in <xref linkend="sql-createfunction">; in particular, one
-   can rely on a search path and automatic addition of the system's standard
-   shared library file name extension.  See <xref linkend="xfunc-c"> for
-   more information on this topic.
+   The library file name is typically given as just a bare file name,
+   which is sought in the server's library search path (set
+   by <xref linkend="guc-dynamic-library-path">).  Alternatively it can be
+   given as a full path name.  In either case the platform's standard shared
+   library file name extension may be omitted.
+   See <xref linkend="xfunc-c-dynload"> for more information on this topic.
   </para>
 
   <indexterm>
