Update main userdocs

public/docs/user/main/_sources/build_env.rst.txt

@@ -261,6 +261,14 @@ meaning that no intermediate decrypted data is ever present on disk. See
 Environment Variables
 *********************
 
+You can set environment variables on the host to influence the behaviour of a
+build. Note that environment variables are not passed into the build itself, and
+cannot be accessed in the ``%post`` section of a definition file. To pass values
+into a build, use the :ref:`templating / build-args support <sec:templating>`.
+
+Environment variables that control a build are generally associated with an
+equivalent CLI option. The order of precendence is:
+
 #. If a flag is represented by both a CLI option and an environment variable,
    and both are set, the CLI option will take precedence. This is true for all
    environment variables with the exception for ``{ENVPREFIX}_BIND`` and

public/docs/user/main/_sources/definition_files.rst.txt

@@ -344,26 +344,37 @@ This section is where you can download files from the internet with
 tools like ``git`` and ``wget``, install new software and libraries,
 write configuration files, create new directories, etc.
 
+The commands in the ``%post`` section run in a clean environment. Environment
+variables from the host are not passed into the build. To pass values into a
+build you should use the :ref:`templating / build-args support <sec:templating>`.
+
 Consider the ``%post`` section from the example definition file above:
 
 .. code:: {command}
 
    %post
        apt-get update && apt-get install -y netcat
+
        NOW=`date`
        echo "export NOW=\"${NOW}\"" >> ${ENVPREFIX}_ENVIRONMENT
 
 This ``%post`` scriptlet uses the Ubuntu package manager ``apt`` to
 update the container and install the program ``netcat`` (that will be
 used in the ``%startscript`` section below).
 
-The script also sets an environment variable at build time. Note that
-the value of this variable cannot be anticipated, and therefore cannot
-be set earlier in the ``%environment`` section. For situations like
-this, the ``${ENVPREFIX}_ENVIRONMENT`` variable is provided. Assigning a
-value to this variable will cause it to be written to a file called
-``/.singularity.d/env/91-environment.sh`` that will be sourced by the
-container at runtime.
+The scriptlet also sets an environment variable called ``NOW`` to the current
+date and time. It then writes an ``export`` statement for ``NOW`` into the file
+that is pointed to by ``${ENVPREFIX}_ENVIRONMENT``. This demonstrates how to set
+container environment variables (available when the container is run), that are
+not known when the definition file is written. Because the value of ``$NOW`` is
+only known when the ``date`` command in the ``%post`` scriptlet is run, it
+cannot be added to the ``%environment`` section.
+
+Directing output into ``${ENVPREFIX}_ENVIRONMENT`` will cause it to be written
+to a shell script file called ``/.singularity.d/env/91-environment.sh`` that
+will be sourced by the container at runtime. The ``export NAME=VALUE`` syntax is
+needed to make the environment variable available to all processes that are
+started in the container.
 
 .. note::
 

public/docs/user/main/build_env.html

@@ -361,6 +361,12 @@ <h2>Encrypted Containers<a class="headerlink" href="#encrypted-containers" title
 </div>
 <div class="section" id="environment-variables">
 <h2>Environment Variables<a class="headerlink" href="#environment-variables" title="Permalink to this heading"></a></h2>
+<p>You can set environment variables on the host to influence the behaviour of a
+build. Note that environment variables are not passed into the build itself, and
+cannot be accessed in the <code class="docutils literal notranslate"><span class="pre">%post</span></code> section of a definition file. To pass values
+into a build, use the <span class="xref std std-ref">templating / build-args support</span>.</p>
+<p>Environment variables that control a build are generally associated with an
+equivalent CLI option. The order of precendence is:</p>
 <ol class="arabic simple">
 <li><p>If a flag is represented by both a CLI option and an environment variable,
 and both are set, the CLI option will take precedence. This is true for all

public/docs/user/main/definition_files.html

@@ -455,23 +455,32 @@ <h3>%post<a class="headerlink" href="#post" title="Permalink to this heading">
 <p>This section is where you can download files from the internet with
 tools like <code class="docutils literal notranslate"><span class="pre">git</span></code> and <code class="docutils literal notranslate"><span class="pre">wget</span></code>, install new software and libraries,
 write configuration files, create new directories, etc.</p>
+<p>The commands in the <code class="docutils literal notranslate"><span class="pre">%post</span></code> section run in a clean environment. Environment
+variables from the host are not passed into the build. To pass values into a
+build you should use the <span class="xref std std-ref">templating / build-args support</span>.</p>
 <p>Consider the <code class="docutils literal notranslate"><span class="pre">%post</span></code> section from the example definition file above:</p>
 <div class="highlight-apptainer notranslate"><div class="highlight"><pre><span></span><span class="gh">%post</span>
 <span class="w">    </span>apt-get<span class="w"> </span>update<span class="w"> </span><span class="o">&amp;&amp;</span><span class="w"> </span>apt-get<span class="w"> </span>install<span class="w"> </span>-y<span class="w"> </span>netcat
+
 <span class="w">    </span><span class="nv">NOW</span><span class="o">=</span><span class="sb">`</span>date<span class="sb">`</span>
 <span class="w">    </span><span class="nb">echo</span><span class="w"> </span><span class="s2">&quot;export NOW=\&quot;</span><span class="si">${</span><span class="nv">NOW</span><span class="si">}</span><span class="s2">\&quot;&quot;</span><span class="w"> </span>&gt;&gt;<span class="w"> </span><span class="nv">$APPTAINER_ENVIRONMENT</span>
 </pre></div>
 </div>
 <p>This <code class="docutils literal notranslate"><span class="pre">%post</span></code> scriptlet uses the Ubuntu package manager <code class="docutils literal notranslate"><span class="pre">apt</span></code> to
 update the container and install the program <code class="docutils literal notranslate"><span class="pre">netcat</span></code> (that will be
 used in the <code class="docutils literal notranslate"><span class="pre">%startscript</span></code> section below).</p>
-<p>The script also sets an environment variable at build time. Note that
-the value of this variable cannot be anticipated, and therefore cannot
-be set earlier in the <code class="docutils literal notranslate"><span class="pre">%environment</span></code> section. For situations like
-this, the <code class="docutils literal notranslate"><span class="pre">$APPTAINER_ENVIRONMENT</span></code> variable is provided. Assigning a
-value to this variable will cause it to be written to a file called
-<code class="docutils literal notranslate"><span class="pre">/.singularity.d/env/91-environment.sh</span></code> that will be sourced by the
-container at runtime.</p>
+<p>The scriptlet also sets an environment variable called <code class="docutils literal notranslate"><span class="pre">NOW</span></code> to the current
+date and time. It then writes an <code class="docutils literal notranslate"><span class="pre">export</span></code> statement for <code class="docutils literal notranslate"><span class="pre">NOW</span></code> into the file
+that is pointed to by <code class="docutils literal notranslate"><span class="pre">$APPTAINER_ENVIRONMENT</span></code>. This demonstrates how to set
+container environment variables (available when the container is run), that are
+not known when the definition file is written. Because the value of <code class="docutils literal notranslate"><span class="pre">$NOW</span></code> is
+only known when the <code class="docutils literal notranslate"><span class="pre">date</span></code> command in the <code class="docutils literal notranslate"><span class="pre">%post</span></code> scriptlet is run, it
+cannot be added to the <code class="docutils literal notranslate"><span class="pre">%environment</span></code> section.</p>
+<p>Directing output into <code class="docutils literal notranslate"><span class="pre">$APPTAINER_ENVIRONMENT</span></code> will cause it to be written
+to a shell script file called <code class="docutils literal notranslate"><span class="pre">/.singularity.d/env/91-environment.sh</span></code> that
+will be sourced by the container at runtime. The <code class="docutils literal notranslate"><span class="pre">export</span> <span class="pre">NAME=VALUE</span></code> syntax is
+needed to make the environment variable available to all processes that are
+started in the container.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>Variables set in the <code class="docutils literal notranslate"><span class="pre">%post</span></code> section through