1 files changed, 32 insertions, 15 deletions

diff --git a/doc/manual/src/language/constructs.md b/doc/manual/src/language/constructs.md
index 1c01f2cc7..c53eb8889 100644
--- a/doc/manual/src/language/constructs.md
+++ b/doc/manual/src/language/constructs.md
@@ -2,8 +2,11 @@
 
 ## Recursive sets
 
-Recursive sets are just normal sets, but the attributes can refer to
-each other. For example,
+Recursive sets are like normal [attribute sets](./values.md#attribute-set), but the attributes can refer to each other.
+
+> *rec-attrset* = `rec {` [ *name* `=` *expr* `;` `]`... `}`
+
+Example:
 
 ```nix
 rec {
@@ -12,7 +15,9 @@ rec {
 }.x
 ```
 
-evaluates to `123`. Note that without `rec` the binding `x = y;` would
+This evaluates to `123`.
+
+Note that without `rec` the binding `x = y;` would
 refer to the variable `y` in the surrounding scope, if one exists, and
 would be invalid if no such variable exists. That is, in a normal
 (non-recursive) set, attributes are not added to the lexical scope; in a
@@ -33,7 +38,10 @@ will crash with an `infinite recursion encountered` error message.
 ## Let-expressions
 
 A let-expression allows you to define local variables for an expression.
-For instance,
+
+> *let-in* = `let` [ *identifier* = *expr* ]... `in` *expr*
+
+Example:
 
 ```nix
 let
@@ -42,18 +50,19 @@ let
 in x + y
 ```
 
-evaluates to `"foobar"`.
+This evaluates to `"foobar"`.
 
 ## Inheriting attributes
 
-When defining a set or in a let-expression it is often convenient to
-copy variables from the surrounding lexical scope (e.g., when you want
-to propagate attributes). This can be shortened using the `inherit`
-keyword. For instance,
+When defining an [attribute set](./values.md#attribute-set) or in a [let-expression](#let-expressions) it is often convenient to copy variables from the surrounding lexical scope (e.g., when you want to propagate attributes).
+This can be shortened using the `inherit` keyword.
+
+Example:
 
 ```nix
 let x = 123; in
-{ inherit x;
+{
+  inherit x;
   y = 456;
 }
 ```
@@ -62,15 +71,23 @@ is equivalent to
 
 ```nix
 let x = 123; in
-{ x = x;
+{
+  x = x;
   y = 456;
 }
 ```
 
-and both evaluate to `{ x = 123; y = 456; }`. (Note that this works
-because `x` is added to the lexical scope by the `let` construct.) It is
-also possible to inherit attributes from another set. For instance, in
-this fragment from `all-packages.nix`,
+and both evaluate to `{ x = 123; y = 456; }`.
+
+> **Note**
+>
+> This works because `x` is added to the lexical scope by the `let` construct.
+
+It is also possible to inherit attributes from another attribute set.
+
+Example:
+
+In this fragment from `all-packages.nix`,
 
 ```nix
 graphviz = (import ../tools/graphics/graphviz) {