From 748a975aa0386fb3fb74bffff667c3f63ed0649e Mon Sep 17 00:00:00 2001
From: Tom Hubrecht <github@mail.hubrecht.ovh>
Date: Thu, 20 Nov 2025 22:35:19 +0100
Subject: [PATCH] libexpr/builtins: Fixup scopedImport documentation

Change-Id: I01cbc628a0334a1d1e6347d987089262c08e7cee
---
 lix/libexpr/builtins/scopedImport.md | 41 +++++++---------------------
 1 file changed, 10 insertions(+), 31 deletions(-)

diff --git a/lix/libexpr/builtins/scopedImport.md b/lix/libexpr/builtins/scopedImport.md
index 44d1b1796..e2627ca3e 100644
--- a/lix/libexpr/builtins/scopedImport.md
+++ b/lix/libexpr/builtins/scopedImport.md
@@ -5,7 +5,12 @@ args: [scope, path]
 renameInGlobalScope: false
 ---
 
-Functions like [`import`](#builtins-import) with the exceptions that
+> **Warning**
+>
+> This builtin's use is heavily discouraged, it has many drawbacks and may be removed
+> in a future version of Lix.
+
+Functions like [`import`](#builtins-import) with the exception that
 it takes a `scope`, which is a set of attributes to be added to the
 lexical scope of the expression.
 
@@ -25,29 +30,6 @@ scopedImport { x = 1; } ./foo.nix
 
 will evaluate to `1`.
 
-This allows removing function arguments specifications in nix expressions,
-for example, a package definition `bar.nix`:
-
-```nix
-{ stdenv, fetchurl, libfoo }:
-
-stdenv.mkDerivation { ... buildInputs = [ libfoo ]; }
-```
-
-can be rewritten as:
-
-```nix
-stdenv.mkDerivation { ... buildInputs = [ libfoo ]; }
-```
-
-and imported via:
-
-```nix
-bar = scopedImport pkgs ./bar.nix;
-```
-
-which remove some duplication of code.
-
 Another application is overriding builtin functions or constants, e.g. to
 trace all calls to `map`, one can do:
 
@@ -68,13 +50,10 @@ let
 in scopedImport overrides ./bla.nix
 ```
 
-Similarly, one can simply extend the set of builtin functions.
+Similarly, it can be used to extend the set of builtin functions.
 
 > **Warning**
 >
-> A downside of using `scopedImport` is that it bypasses the evaluation cache.
-> This means that importing a file multiple times will lead to multiple parsings
-> and evaluations.
->
-> Please note also that the files imported via `scopedImport` contain free variables
-> and thus cannot be imported using the regular `import`.
+> One of the downsides of `scopedImport` is that it bypasses the evaluation cache.
+> This means that importing a file multiple times will lead to multiple expensive
+> parsings and evaluations.