From c6cfa7a4123587b6678daa74b387525a265c52e0 Mon Sep 17 00:00:00 2001
From: Profpatsch <mail@profpatsch.de>
Date: Sat, 7 May 2016 13:10:09 +0200
Subject: [PATCH] manual/substituteAll: document filtered variables

Some variables are filtered out as of #14907.
---
 doc/stdenv.xml | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/doc/stdenv.xml b/doc/stdenv.xml
index 136e83ee0cd..d5f37aee15e 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>