Merge pull request #1633 from orivej/doc

Update the language documentation

3 files changed, 54 insertions, 15 deletions

diff --git a/doc/manual/expressions/language-constructs.xml b/doc/manual/expressions/language-constructs.xml
index fe69dba837a1..2f0027d479cd 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>
 
diff --git a/doc/manual/expressions/language-operators.xml b/doc/manual/expressions/language-operators.xml
index a3323ced4c50..f1f75093461b 100644
--- a/doc/manual/expressions/language-operators.xml
+++ b/doc/manual/expressions/language-operators.xml
@@ -41,6 +41,11 @@ weakest binding).</para>
         argument <replaceable>e2</replaceable>.</entry>
       </row>
       <row>
+        <entry><literal>-</literal> <replaceable>e</replaceable></entry>
+        <entry>none</entry>
+        <entry>Arithmetic negation.</entry>
+      </row>
+      <row>
         <entry><replaceable>e</replaceable> <literal>?</literal>
         <replaceable>attrpath</replaceable></entry>
         <entry>none</entry>
@@ -55,13 +60,24 @@ weakest binding).</para>
         <entry>List concatenation.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable></entry>
+        <entry>
+          <replaceable>e1</replaceable> <literal>*</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>/</literal> <replaceable>e2</replaceable>
+        </entry>
         <entry>left</entry>
-        <entry>String or path concatenation.</entry>
+        <entry>Arithmetic multiplication and division.</entry>
       </row>
       <row>
-        <entry><literal>!</literal> <replaceable>e</replaceable></entry>
+        <entry>
+          <replaceable>e1</replaceable> <literal>+</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>-</literal> <replaceable>e2</replaceable>
+        </entry>
         <entry>left</entry>
+        <entry>Arithmetic addition and subtraction.  String or path concatenation (only by <literal>+</literal>).</entry>
+      </row>
+      <row>
+        <entry><literal>!</literal> <replaceable>e</replaceable></entry>
+        <entry>none</entry>
         <entry>Boolean negation.</entry>
       </row>
       <row>
@@ -75,16 +91,22 @@ weakest binding).</para>
         attributes).</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> <literal>==</literal>
-        <replaceable>e2</replaceable></entry>
+        <entry>
+          <replaceable>e1</replaceable> <literal>&lt;</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>&gt;</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>&lt;=</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>&gt;=</literal> <replaceable>e2</replaceable>
+        </entry>
         <entry>none</entry>
-        <entry>Equality.</entry>
+        <entry>Arithmetic comparison.</entry>
       </row>
       <row>
-        <entry><replaceable>e1</replaceable> <literal>!=</literal>
-        <replaceable>e2</replaceable></entry>
+        <entry>
+          <replaceable>e1</replaceable> <literal>==</literal> <replaceable>e2</replaceable>,
+          <replaceable>e1</replaceable> <literal>!=</literal> <replaceable>e2</replaceable>
+        </entry>
         <entry>none</entry>
-        <entry>Inequality.</entry>
+        <entry>Equality and inequality.</entry>
       </row>
       <row>
         <entry><replaceable>e1</replaceable> <literal>&amp;&amp;</literal>
diff --git a/doc/manual/expressions/language-values.xml b/doc/manual/expressions/language-values.xml
index 67da688a4fc5..bb2090c881fd 100644
--- a/doc/manual/expressions/language-values.xml
+++ b/doc/manual/expressions/language-values.xml
@@ -98,13 +98,17 @@ configureFlags = "
 
     <para>Since <literal>${</literal> and <literal>''</literal> have
     special meaning in indented strings, you need a way to quote them.
-    <literal>${</literal> can be escaped by prefixing it with
+    <literal>$</literal> can be escaped by prefixing it with
     <literal>''</literal> (that is, two single quotes), i.e.,
-    <literal>''${</literal>.  <literal>''</literal> can be escaped by
+    <literal>''$</literal>. <literal>''</literal> can be escaped by
     prefixing it with <literal>'</literal>, i.e.,
-    <literal>'''</literal>.  Finally, linefeed, carriage-return and
-    tab characters can be written as <literal>''\n</literal>,
-    <literal>''\r</literal>, <literal>''\t</literal>.</para>
+    <literal>'''</literal>. <literal>$</literal> removes any special meaning
+    from the following <literal>$</literal>. Linefeed, carriage-return and tab
+    characters can be written as <literal>''\n</literal>,
+    <literal>''\r</literal>, <literal>''\t</literal>, and <literal>''\</literal>
+    escapes any other character.
+
+    </para>
 
     <para>Indented strings are primarily useful in that they allow
     multi-line string literals to follow the indentation of the