add captures docs

diff --git a/docs/Overview/Capture_Lists.mdr b/docs/Overview/Capture_Lists.mdr
new file mode 100644 (file)
index 0000000..34e9299
--- /dev/null
+++ b/docs/Overview/Capture_Lists.mdr
@@ -0,0 +1,39 @@
+# Capture List
+
+Sometimes in a spork/fork or a lambda expression, there is the need to capture one or more variables.
+Here's how it's done in Gwion:
+
+```gwion,editable
+var int foo, bar;
+
+#! for lambdas
+\ arg0 arg 1 : foo bar : {}
+
+#! for spork
+spork : foo bar : {}
+
+#! for fork
+fork : foo bar : {}
+```
+
+If you want to capture by reference, just prepend the variable name with `&`.
+For example capturing `foo` by reference and `bar` by value:
+
+```gwion,editable
+var int foo, bar;
+
+#! for lambdas
+\ arg0 arg 1 : &foo bar : {}
+
+#! for spork
+spork : &foo bar : {}
+
+#! for fork
+fork : &foo bar : {}
+```
+
+## Why explicit captures?
+
+In some cases you may want to track the value of variable, even a primitive, over time.
+If you capture by value, it would stay the same as when the variable was captured,
+hence sometimes the need to use capture by reference.

diff --git a/docs/Overview/list b/docs/Overview/list
index cf913c70ba13dd0624d13359ae72b9cee3cce792..8e4e4d9bfff1fb5ad55e803d6d61051f28e963b5 100644 (file)
--- a/docs/Overview/list
+++ b/docs/Overview/list
@@ -6,4 +6,5 @@ globalvalues.md
 Keywords.md
 Make.md
 SpecialWords.md
+Capture_Lists
 Testing.md