diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index 136e83ee0cda..d5f37aee15ee 100644
--- a/doc/stdenv.xml
+++ b/doc/stdenv.xml
@@ -1169,7 +1169,17 @@ 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 or an
+    underscore are filtered out,
+    to prevent global variables (like <literal>HOME</literal>) or private
+    variables (like <literal>__ETC_PROFILE_DONE</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>