Merge remote-tracking branch 'origin/master' into lazy-trees

doc/manual/src/SUMMARY.md.in

@@ -27,6 +27,7 @@
   - [Language Constructs](language/constructs.md)
     - [String interpolation](language/string-interpolation.md)
     - [Lookup path](language/constructs/lookup-path.md)
+    - [String context](language/string-context.md)
   - [Operators](language/operators.md)
   - [Derivations](language/derivations.md)
     - [Advanced Attributes](language/advanced-attributes.md)

doc/manual/src/command-ref/conf-file-prefix.md

@@ -66,5 +66,12 @@ Configuration options can be set on the command line, overriding the values set
 
 The `extra-` prefix is supported for settings that take a list of items (e.g. `--extra-trusted users alice` or `--option extra-trusted-users alice`).
 
+## Integer settings
+
+Settings that have an integer type support the suffixes `K`, `M`, `G`
+and `T`. These cause the specified value to be multiplied by 2^10,
+2^20, 2^30 and 2^40, respectively. For instance, `--min-free 1M` is
+equivalent to `--min-free 1048576`.
+
 # Available settings
 

doc/manual/src/glossary.md

@@ -218,6 +218,17 @@
 - [output closure]{#gloss-output-closure}\
   The [closure] of an [output path]. It only contains what is [reachable] from the output.
 
+- [deriving path]{#gloss-deriving-path}
+
+  Deriving paths are a way to refer to [store objects][store object] that ar not yet [realised][realise].
+  This is necessary because, in general and particularly for [content-addressed derivations][content-addressed derivation], the [output path] of an [output] is not known in advance.
+  There are two forms:
+
+  - *constant*: just a [store path]
+    It can be made [valid][validity] by copying it into the store: from the evaluator, command line interface or another store.
+
+  - *output*: a pair of a [store path] to a [derivation] and an [output] name.
+
 - [deriver]{#gloss-deriver}
 
   The [store derivation] that produced an [output path].

doc/manual/src/language/constructs.md

@@ -402,7 +402,36 @@ 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 is [statically scoped](https://en.wikipedia.org/wiki/Scope_(computer_science)#Lexical_scope), but with multiple scopes and shadowing rules.
+
+* primary scope --- explicitly-bound variables
+  * [`let`](#let-expressions)
+  * [`inherit`](#inheriting-attributes)
+  * function arguments
+
+* secondary scope --- implicitly-bound variables
+  * [`with`](#with-expressions)
+
+Primary scope takes precedence over secondary 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>