From fa34d1aa1bd893a9bc1b2a38abbd149972cc9a05 Mon Sep 17 00:00:00 2001
From: Jakub Jankiewicz <jcubic@onet.pl>
Date: Sun, 24 Mar 2024 18:01:08 +0100
Subject: [PATCH] add docs about global env

---
 docs/docs/lips/environments.md | 39 ++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/docs/lips/environments.md b/docs/docs/lips/environments.md
index bfa5bd384..c7334f6bc 100644
--- a/docs/docs/lips/environments.md
+++ b/docs/docs/lips/environments.md
@@ -150,3 +150,42 @@ You can mix lexical scope chain with frames:
 ;; ==> let ==> #(y)
 ;; ==> lambda ==> #(arguments parent.frame x)
 ```
+
+## Global environment
+
+in `lips.env` is user global environment but real global environment where all functions and macros that are
+located (it's also a place where names from bootstraping are saved) is `lips.env.__parent__`.
+
+If you want to really overwrite builtin function.
+
+```scheme
+(define-macro (define x)
+  `(print ,x))
+
+(define 10)
+;; ==> 10
+(unset! define)
+(define foo 10)
+(print foo)
+;; ==> 10
+```
+
+If you execute this code in REPL or in a script it will only add `define` into `interaction-environment`.
+If you really want to overwrite `define` you can (not that you should):
+
+```scheme
+(let-env lips.env.__parent__
+  (define-macro (define x)
+    `(print ,x)))
+
+(unset! define)
+(define foo 10)
+;; ==> Unbound variable `define'
+```
+
+The only time you may want to use `lips.env.__parent__` when you bootstrap the LIPS Scheme system.
+
+```scheme
+(let-env lips.env.__parent__
+  (load "<path or URL>/dist/std.xcb"))
+```