From 969e5ad5bfc6527b8205182e50ba4ec216f218a0 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Thu, 22 Dec 2022 22:11:17 +0100
Subject: [PATCH] add semantics of overloaded `+` operator

---
 doc/manual/src/language/operators.md | 58 +++++++++++++++++++++++-----
 1 file changed, 48 insertions(+), 10 deletions(-)

diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md
index e3a00d32b..0c8cc6f57 100644
--- a/doc/manual/src/language/operators.md
+++ b/doc/manual/src/language/operators.md
@@ -70,16 +70,6 @@ Associativity: left
 
 Precedence: 6
 
-## Addition
-
-> *e1* `+` *e2*
-
-Add numbers *e1* and *e2*.
-
-Associativity: left
-
-Precedence: 7
-
 ## Subtraction
 
 > *e1* `-` *e2*
@@ -90,6 +80,16 @@ Associativity: left
 
 Precedence: 7
 
+## Addition
+
+> *e1* `+` *e2*
+
+Add numbers *e1* and *e2*.
+
+Associativity: left
+
+Precedence: 7
+
 ## String concatenation
 
 > *string1* `+` *string2*
@@ -100,6 +100,44 @@ Associativity: left
 
 Precedence: 7
 
+## Path concatenation
+
+> *path1* `+` *path2*
+
+Concatenate two paths.
+The result is a path.
+
+## Path and string concatenation
+
+> *path* `+` *string*
+
+Concatenate *path* with *string*.
+The result is a path.
+
+> **Note**
+>
+> The string must not have a string context that refers to a store path.
+
+Associativity: left
+
+Precedence: 7
+
+## String and path concatenation
+
+> *string* `+` *path*
+
+Concatenate *string* with *path*.
+The result is a string.
+
+> **Important**
+>
+> The file or directory at *path* must exist and is copied to the store
+> The path appears in the result as the corresponding store path.
+
+Associativity: left
+
+Precedence: 7
+
 ## Logical negation (`NOT`)
 
 > `!` *e*