language: Link examples to detail explanations.

Also, warn of the scoping caveats of `with`.

doc/manual/src/language/constructs.md

@@ -402,7 +402,35 @@ establishes the same scope as
 let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...
 ```
 
+Variables coming from outer `with` expressions *are* shadowed:
+
+```nix
+with { a = "outer"; };
+with { a = "inner"; };
+a
+```
+
+Does evaluate to `"inner"`.
+
 ## Comments
 
 Comments can be single-line, started with a `#` character, or
 inline/multi-line, enclosed within `/* ... */`.
+
+`#` comments last until the end of the line.
+
+`/*` comments run until the next occurrence of `*/`; this cannot be escaped.
+
+## Scoping rules
+
+Nix has constructs with
+
+* dynamic scope
+  * [`with`](#with-expressions)
+* static scope
+  * [`let`](#let-expressions)
+  * [`inherit`](#inheriting-attributes)
+  * function arguments
+
+Static scope takes precedence over dynamic scope.
+See [`with`](#with-expressions) for a detailed example.

doc/manual/src/language/index.md

@@ -53,7 +53,7 @@ This is an incomplete overview of language features, by example.
   <td>
 
 
-   *Basic values*
+   *Basic values ([primitives](@docroot@/language/values.md#primitives))*
 
 
   </td>
@@ -71,7 +71,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A string
+   A [string](@docroot@/language/values.md#type-string)
 
   </td>
  </tr>
@@ -94,6 +94,18 @@ This is an incomplete overview of language features, by example.
 
   </td>
  </tr>
+ <tr>
+  <td>
+
+   `# Explanation`
+
+  </td>
+  <td>
+
+   A [comment](@docroot@/language/constructs.md#comments).
+
+  </td>
+ </tr>
  <tr>
   <td>
 
@@ -106,7 +118,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   String interpolation (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
+   [String interpolation](@docroot@/language/string-interpolation.md) (expands to `"hello world"`, `"1 2 3"`, `"/nix/store/<hash>-bash-<version>/bin/sh"`)
 
   </td>
  </tr>
@@ -118,7 +130,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Booleans
+   [Booleans](@docroot@/language/values.md#type-boolean)
 
   </td>
  </tr>
@@ -130,7 +142,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Null value
+   [Null](@docroot@/language/values.md#type-null) value
 
   </td>
  </tr>
@@ -142,7 +154,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   An integer
+   An [integer](@docroot@/language/values.md#type-number)
 
   </td>
  </tr>
@@ -154,7 +166,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A floating point number
+   A [floating point number](@docroot@/language/values.md#type-number)
 
   </td>
  </tr>
@@ -166,7 +178,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   An absolute path
+   An absolute [path](@docroot@/language/values.md#type-path)
 
   </td>
  </tr>
@@ -178,7 +190,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A path relative to the file containing this Nix expression
+   A [path](@docroot@/language/values.md#type-path) relative to the file containing this Nix expression
 
   </td>
  </tr>
@@ -190,7 +202,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A home path. Evaluates to the `"<user's home directory>/.config"`.
+   A home [path](@docroot@/language/values.md#type-path). Evaluates to the `"<user's home directory>/.config"`.
 
   </td>
  </tr>
@@ -202,7 +214,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Search path for Nix files. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
+   A [lookup path](@docroot@/language/constructs/lookup-path.md) for Nix files. Value determined by [`$NIX_PATH` environment variable](../command-ref/env-common.md#env-NIX_PATH).
 
   </td>
  </tr>
@@ -226,7 +238,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A set with attributes named `x` and `y`
+   An [attribute set](@docroot@/language/values.md#attribute-set) with attributes named `x` and `y`
 
   </td>
  </tr>
@@ -250,7 +262,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A recursive set, equivalent to `{ x = "foo"; y = "foobar"; }`
+   A [recursive set](@docroot@/language/constructs.md#recursive-sets), equivalent to `{ x = "foo"; y = "foobar"; }`.
 
   </td>
  </tr>
@@ -266,7 +278,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Lists with three elements.
+   [Lists](@docroot@/language/values.md#list) with three elements.
 
   </td>
  </tr>
@@ -350,7 +362,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Attribute selection (evaluates to `1`)
+   [Attribute selection](@docroot@/language/values.md#attribute-set) (evaluates to `1`)
 
   </td>
  </tr>
@@ -362,7 +374,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Attribute selection with default (evaluates to `3`)
+   [Attribute selection](@docroot@/language/values.md#attribute-set) with default (evaluates to `3`)
 
   </td>
  </tr>
@@ -398,7 +410,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Conditional expression
+   [Conditional expression](@docroot@/language/constructs.md#conditionals).
 
   </td>
  </tr>
@@ -410,7 +422,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Assertion check (evaluates to `"yes!"`).
+   [Assertion](@docroot@/language/constructs.md#assertions) check (evaluates to `"yes!"`).
 
   </td>
  </tr>
@@ -422,7 +434,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Variable definition
+   Variable definition. See [`let`-expressions](@docroot@/language/constructs.md#let-expressions).
 
   </td>
  </tr>
@@ -434,7 +446,9 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Add all attributes from the given set to the scope (evaluates to `1`)
+   Add all attributes from the given set to the scope (evaluates to `1`).
+
+   See [`with`-expressions](@docroot@/language/constructs.md#with-expressions) for details and shadowing caveats.
 
   </td>
  </tr>
@@ -447,7 +461,8 @@ This is an incomplete overview of language features, by example.
   <td>
 
    Adds the variables to the current scope (attribute set or `let` binding).
-   Desugars to `pkgs = pkgs; src = src;`
+   Desugars to `pkgs = pkgs; src = src;`.
+   See [Inheriting attributes](@docroot@/language/constructs.md#inheriting-attributes).
 
   </td>
  </tr>
@@ -460,14 +475,15 @@ This is an incomplete overview of language features, by example.
   <td>
 
    Adds the attributes, from the attribute set in parentheses, to the current scope (attribute set or `let` binding).
-   Desugars to `lib = pkgs.lib; stdenv = pkgs.stdenv;`
+   Desugars to `lib = pkgs.lib; stdenv = pkgs.stdenv;`.
+   See [Inheriting attributes](@docroot@/language/constructs.md#inheriting-attributes).
 
   </td>
  </tr>
  <tr>
   <td>
 
-   *Functions (lambdas)*
+   *[Functions](@docroot@/language/constructs.md#functions) (lambdas)*
 
   </td>
   <td>
@@ -484,7 +500,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A function that expects an integer and returns it increased by 1
+   A [function](@docroot@/language/constructs.md#functions) that expects an integer and returns it increased by 1.
 
   </td>
  </tr>
@@ -496,7 +512,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Curried function, equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
+   Curried [function](@docroot@/language/constructs.md#functions), equivalent to `x: (y: x + y)`. Can be used like a function that takes two arguments and returns their sum.
 
   </td>
  </tr>
@@ -508,7 +524,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A function call (evaluates to 101)
+   A [function](@docroot@/language/constructs.md#functions) call (evaluates to 101)
 
   </td>
  </tr>
@@ -520,7 +536,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A function bound to a variable and subsequently called by name (evaluates to 103)
+   A [function](@docroot@/language/constructs.md#functions) bound to a variable and subsequently called by name (evaluates to 103)
 
   </td>
  </tr>
@@ -532,7 +548,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A function that expects a set with required attributes `x` and `y` and concatenates them
+   A [function](@docroot@/language/constructs.md#functions) that expects a set with required attributes `x` and `y` and concatenates them
 
   </td>
  </tr>
@@ -544,7 +560,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A function that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
+   A [function](@docroot@/language/constructs.md#functions) that expects a set with required attribute `x` and optional `y`, using `"bar"` as default value for `y`
 
   </td>
  </tr>
@@ -556,7 +572,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A function that expects a set with required attributes `x` and `y` and ignores any other attributes
+   A [function](@docroot@/language/constructs.md#functions) that expects a set with required attributes `x` and `y` and ignores any other attributes
 
   </td>
  </tr>
@@ -570,7 +586,7 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   A function that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
+   A [function](@docroot@/language/constructs.md#functions) that expects a set with required attributes `x` and `y`, and binds the whole set to `args`
 
   </td>
  </tr>
@@ -594,7 +610,8 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Load and return Nix expression in given file
+   Load and return Nix expression in given file.
+   See [import](@docroot@/language/builtins.md#builtins-import).
 
   </td>
  </tr>
@@ -606,7 +623,8 @@ This is an incomplete overview of language features, by example.
   </td>
   <td>
 
-   Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`)
+   Apply a function to every element of a list (evaluates to `[ 2 4 6 ]`).
+   See [`map`](@docroot@/language/builtins.md#builtins-map).
 
   </td>
  </tr>