From 15457c56731537e0d424d5feb3f3fcacba39b99b Mon Sep 17 00:00:00 2001
From: Orivej Desh <orivej@gmx.fr>
Date: Thu, 26 Oct 2017 18:50:30 +0000
Subject: [PATCH] Describe "with" scoping precedence

---
 doc/manual/expressions/language-constructs.xml | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/doc/manual/expressions/language-constructs.xml b/doc/manual/expressions/language-constructs.xml
index fe69dba83..2f0027d47 100644
--- a/doc/manual/expressions/language-constructs.xml
+++ b/doc/manual/expressions/language-constructs.xml
@@ -333,7 +333,20 @@ with (import ./definitions.nix); ...</programlisting>
 
 makes all attributes defined in the file
 <filename>definitions.nix</filename> available as if they were defined
-locally in a <literal>rec</literal>-expression.</para>
+locally in a <literal>let</literal>-expression.</para>
+
+<para>The bindings introduced by <literal>with</literal> do not shadow bindings
+introduced by other means, e.g.
+
+<programlisting>
+let a = 3; in with { a = 1; }; let a = 4; in with { a = 2; }; ...</programlisting>
+
+establishes the same scope as
+
+<programlisting>
+let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...</programlisting>
+
+</para>
 
 </simplesect>