Merge remote-tracking branch 'upstream/master' into best-effort-supplementary-groups

4 files changed, 32 insertions, 29 deletions

diff --git a/doc/manual/src/language/builtin-constants.md b/doc/manual/src/language/builtin-constants.md
index 78d066a82..c6bc9b74c 100644
--- a/doc/manual/src/language/builtin-constants.md
+++ b/doc/manual/src/language/builtin-constants.md
@@ -1,20 +1,19 @@
 # Built-in Constants
 
-Here are the constants built into the Nix expression evaluator:
+These constants are built into the Nix language evaluator:
 
-  - `builtins`\
-    The set `builtins` contains all the built-in functions and values.
-    You can use `builtins` to test for the availability of features in
-    the Nix installation, e.g.,
-    
-    ```nix
-    if builtins ? getEnv then builtins.getEnv "PATH" else ""
-    ```
-    
-    This allows a Nix expression to fall back gracefully on older Nix
-    installations that don’t have the desired built-in function.
+- [`builtins`]{#builtins-builtins} (attribute set)
 
-  - [`builtins.currentSystem`]{#builtins-currentSystem}\
-    The built-in value `currentSystem` evaluates to the Nix platform
-    identifier for the Nix installation on which the expression is being
-    evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
+  Contains all the [built-in functions](./builtins.md) and values, in order to avoid polluting the global scope.
+
+  Since built-in functions were added over time, [testing for attributes](./operators.md#has-attribute) in `builtins` can be used for graceful fallback on older Nix installations:
+
+  ```nix
+  if builtins ? getEnv then builtins.getEnv "PATH" else ""
+  ```
+
+- [`builtins.currentSystem`]{#builtins-currentSystem} (string)
+
+  The built-in value `currentSystem` evaluates to the Nix platform
+  identifier for the Nix installation on which the expression is being
+  evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
diff --git a/doc/manual/src/language/builtins-prefix.md b/doc/manual/src/language/builtins-prefix.md
index c631a8453..35e3dccc3 100644
--- a/doc/manual/src/language/builtins-prefix.md
+++ b/doc/manual/src/language/builtins-prefix.md
@@ -1,16 +1,16 @@
 # Built-in Functions
 
-This section lists the functions built into the Nix expression
-evaluator. (The built-in function `derivation` is discussed above.)
-Some built-ins, such as `derivation`, are always in scope of every Nix
-expression; you can just access them right away. But to prevent
-polluting the namespace too much, most built-ins are not in
-scope. Instead, you can access them through the `builtins` built-in
-value, which is a set that contains all built-in functions and values.
-For instance, `derivation` is also available as `builtins.derivation`.
+This section lists the functions built into the Nix language evaluator.
+All built-in functions are available through the global [`builtins`](./builtin-constants.md#builtins-builtins) constant.
+
+For convenience, some built-ins are can be accessed directly:
+
+- [`derivation`](#builtins-derivation)
+- [`import`](#builtins-import)
+- [`abort`](#builtins-abort)
+- [`throw`](#builtins-throw)
 
 <dl>
-  <dt><code>derivation <var>attrs</var></code>;
-      <code>builtins.derivation <var>attrs</var></code></dt>
+  <dt id="builtins-derivation"><a href="#builtins-derivation"><code>derivation <var>attrs</var></code></a></dt>
   <dd><p><var>derivation</var> is described in
          <a href="derivations.md">its own section</a>.</p></dd>
diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index a07d976ad..3e929724d 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -36,7 +36,7 @@
 ## Attribute selection
 
 Select the attribute denoted by attribute path *attrpath* from [attribute set] *attrset*.
-If the attribute doesn’t exist, return *value* if provided, otherwise abort evaluation.
+If the attribute doesn’t exist, return the *expr* after `or` if provided, otherwise abort evaluation.
 
 <!-- FIXME: the following should to into its own language syntax section, but that needs more work to fit in well -->
 
diff --git a/doc/manual/src/language/values.md b/doc/manual/src/language/values.md
index c85124278..9d0301753 100644
--- a/doc/manual/src/language/values.md
+++ b/doc/manual/src/language/values.md
@@ -190,13 +190,17 @@ instance,
 ```
 
 evaluates to `"Foo"`. It is possible to provide a default value in an
-attribute selection using the `or` keyword. For example,
+attribute selection using the `or` keyword:
 
 ```nix
 { a = "Foo"; b = "Bar"; }.c or "Xyzzy"
 ```
 
-will evaluate to `"Xyzzy"` because there is no `c` attribute in the set.
+```nix
+{ a = "Foo"; b = "Bar"; }.c.d.e.f.g or "Xyzzy"
+```
+
+will both evaluate to `"Xyzzy"` because there is no `c` attribute in the set.
 
 You can use arbitrary double-quoted strings as attribute names: