From d8e452a91b4440a049c03dec118c439fa773e323 Mon Sep 17 00:00:00 2001
From: stuebinm <stuebinm@disroot.org>
Date: Tue, 28 May 2024 15:58:13 +0200
Subject: [PATCH] document context-dependent keywords

Documents some of the weirdness of __curPos and the or keyword.
This does not fit well into any existing section for either of
them, though the use of or as a quasi-operator is mentioned in
the section on operators.

Addresses https://git.lix.systems/lix-project/lix/issues/353

Change-Id: I7c906c8368843dca6944e8b22573b6d201cd9a76
---
 doc/manual/src/language/builtin-constants.md | 11 ++++
 doc/manual/src/language/constructs.md        | 67 ++++++++++++++++++++
 2 files changed, 78 insertions(+)

diff --git a/doc/manual/src/language/builtin-constants.md b/doc/manual/src/language/builtin-constants.md
index 74e87146f..970bf6c5a 100644
--- a/doc/manual/src/language/builtin-constants.md
+++ b/doc/manual/src/language/builtin-constants.md
@@ -7,3 +7,14 @@ These constants are built into the Nix language evaluator:
 {{#include @generated@/language/builtin-constants.md}}
 
 </dl>
+
+## Things which might be mistaken for constants
+
+<dl>
+<dt><code>__curPos</code></dt>
+<dd>
+
+This is not a constant but a [context-dependent keyword](@docroot@/language/constructs.md#keywords-__curPos)
+
+</dd>
+</dl>
diff --git a/doc/manual/src/language/constructs.md b/doc/manual/src/language/constructs.md
index 2a527770a..67fd0126d 100644
--- a/doc/manual/src/language/constructs.md
+++ b/doc/manual/src/language/constructs.md
@@ -380,3 +380,70 @@ let a = 1; in let a = 2; in let a = 3; in let a = 4; in ...
 
 Comments can be single-line, started with a `#` character, or
 inline/multi-line, enclosed within `/* ... */`.
+
+## Context-dependent keywords
+
+<dl>
+<dt id="keywords-__curPos">
+  <a href="#keywords-__curPos"><code>__curPos</code></a>
+</dt>
+<dd>
+
+A quasi-constant which will be replaced with an attribute set describing
+the location where `__curPos` was used, with attributes `file`, `line`,
+and `column`. For example, `import ./file.nix` will result in
+
+```nix
+{
+  column = 1;
+  file = "/path/to/some/file.nix";
+  line = 1;
+}
+```
+
+assuming `file.nix` contains nothing but `__curPos`.
+
+In context without a source file (such as `nix-repl`), it will always
+be replaced with `null`:
+
+```nix-repl
+nix-repl> __curPos
+null
+```
+
+While it may vaguely look like a builtin, this is a very different beast
+that is handled directly by the parser. It thus cannot be shadowed,
+bound to a different name, and is also not available under
+[`builtins`](@docroot@/language/builtin-constants.md#builtins-builtins).
+
+```nix-repl
+nix-repl> let __curPos = "no"; in __curPos
+null
+```
+
+Despite this `__curPos`, much like `or`, may still be used as an identifier,
+it is only treated specially when it appears as an unqualified name:
+
+```nix-repl
+nix-repl> { __curPos = 1; }.__curPos
+1
+```
+
+</dd>
+
+<dt id="keywords-or">
+  <a href="#keywords-or"><code>or</code></a>
+</dt>
+<dd>
+
+`or` is used in [Attribute selection](@docroot@/language/operators.html#attribute-selection),
+where it is a keyword.
+
+However, it is not a keyword in some other contexts, and can be used as
+a binding name in attribute sets, let-bindings, non-initial function
+application position, and as a label in attribute paths.
+
+Its use as anything other than a keyword is discouraged.
+
+</dd>
+</dl>