Document accessing global module in ODD

data/doc/documentation.xml

@@ -2879,6 +2879,24 @@ declare function pmf:code($config as map(*), $node as element(), $class as xs:st
           </para>
         </section>
       </section>
+      <section>
+        <title>Accessing Global Configuration Variables/Functions</title>
+        <para>Sometimes you may want to access global configuration parameters, e.g. to determine
+          the data root collection of the current application. <parameter>tei-publisher-lib
+            4.0.0</parameter> imported the entire <filename>modules/config.xqm</filename> into the
+          XQuery code generated from the ODD, and exposed it in the <parameter>global</parameter>
+          namespace. This way one could access the data root as
+            <parameter>$global:data-root</parameter> inside a predicate or parameter expression in
+          the ODD. However, the complexity of config.xqm caused unnecessary overhead and failures on Windows.</para>
+        <para>Version 4.0.1 instead allows you to explicitely import one or more modules in the ODD
+          processing configuration file (<filename>odd/configuration.xml</filename> or
+            <filename>resources/odd/configuration.xml</filename>). </para>
+        <programlisting language="xml" xml:space="preserve"><![CDATA[<modules>
+    <!-- Import global variables and functions from modules/odd-global.xqm -->
+    <module uri="http://e-editiones.org/tei-publisher/odd-global" prefix="global" at="odd-global.xqm"/>
+    ...
+</modules>]]></programlisting>
+      </section>
     </section>
   </section>
   <section xml:id="css-styling">
@@ -4506,13 +4524,18 @@ declare function config:collection-config($collection as xs:string?, $docUri as
         when compiling an ODD. The underlying reason is that <filename>config.xqm</filename> itself imports a large number of other modules, leading to
         recursive imports, which eXist-db is currently unable to resolve properly on Windows. </para>
       <para>In general, importing all of <filename>config.xqm</filename> into the ODD generated code
-        is usually unnecessary as most of the settings are not needed. This creates an overhead.
-        Version 4.0.1 of <emphasis>tei-publisher-lib</emphasis> therefore no longer imports
+        is usually unnecessary as most of the settings are not needed. Version 4.0.1 of
+          <emphasis>tei-publisher-lib</emphasis> therefore no longer imports
           <filename>config.xqm</filename> by default. Instead, you can configure the modules to be
         made available via <filename>odd/configuration.xml</filename> (or
           <filename>resources/odd/configuration.xml</filename>). By default, TEI Publisher 9.1
-        imports the dedicated <filename>modules/odd-global.xqm</filename>.</para>
-      <para>To update follow the generic instructions above.</para> 
+        imports the dedicated <filename>modules/odd-global.xqm</filename>. </para>
+      <para>To preserve backwards compatibility with apps generated by TEI Publisher 9.0,
+        tei-publisher-lib 4.0.1 will still import the entire config.xqm if no other module is
+        configured to be imported. However, to avoid unnecessary overhead, we strongly recommend to
+        switch to an explicit import as described below.</para>
+      <para>To update follow the generic instructions above and register the dedicated configuration
+        module:</para> 
       <orderedlist>
         <listitem>
           <para>If your ODD was using <parameter>$global</parameter> anywhere, copy <filename>modules/odd-global.xqm</filename> from TEI Publisher 9.1 into the corresponding location of your app. Open the