doc/stdenv.xml document substitution env variables

The filtering of environment variables that start with an uppercase
letter is documented in the manual.

doc/stdenv.xml

@@ -1169,7 +1169,15 @@ PATH=/nix/store/68afga4khv0w...-coreutils-6.12/bin
 echo @foo@
 </programlisting>
 
-    That is, no substitution is performed for undefined variables.</para></listitem>
+    That is, no substitution is performed for undefined variables.</para>
+
+    <para>Environment variables that start with an uppercase letter are filtered out,
+    to prevent global variables (like <literal>HOME</literal>) from accidentally
+    getting substituted.
+    The variables also have to be valid bash “names”, as
+    defined in the bash manpage (alphanumeric or <literal>_</literal>, must not
+    start with a number).</para>
+  </listitem>
   </varlistentry>
 
 

pkgs/build-support/substitute/substitute-all.nix

@@ -2,6 +2,7 @@
 
 args:
 
+# see the substituteAll in the nixpkgs documentation for usage and constaints
 stdenv.mkDerivation ({
   name = if args ? name then args.name else baseNameOf (toString args.src);
   builder = ./substitute-all.sh;