Updating the documentation to match changes in Fate.

6 files changed, 168 insertions, 69 deletions

diff --git a/content/fate_v1/instructions/_index.md b/content/fate_v1/instructions/_index.md
index 70e3987..1f28036 100644
--- a/content/fate_v1/instructions/_index.md
+++ b/content/fate_v1/instructions/_index.md
@@ -23,7 +23,7 @@ Completes the execution of the current sequence.
 Completes the execution of the script.
 
 ### SET VALUE
-{{< fatecode >}}(set! [REFERENCE] [COMPUTATION]){{< /fatecode >}}
+{{< fatecode >}}(set! [X REFERENCE] [X COMPUTATION]){{< /fatecode >}}
 
 Gives the value `[COMPUTATION]` to `[REFERENCE]`.
 
@@ -39,7 +39,6 @@ once the visited sequence has completed.
 
 ### JUMP TO SEQUENCE
 {{< fatecode >}}(jump_to! {String} [C0 = COMPUTATION] ... [CN = COMPUTATION]){{< /fatecode >}}
-
 {{< fatecode >}}(jump_to! [SEQUENCE] [C0 = COMPUTATION] ... [CN = COMPUTATION]){{< /fatecode >}}
 
 Jumps to the sequence named `{String}` (or stored in `[SEQUENCE]`), with `C0`
@@ -48,6 +47,6 @@ defined. Jumping to a sequence means that the execution of the current sequence
 is replaced by that of the target sequence.
 
 ### INSTRUCTION LIST
-{{< fatecode >}}( [C0 = INSTRUCTION] ... [CN = INSTRUCTION]){{< /fatecode >}}
+{{< fatecode >}}([C0 = INSTRUCTION] ... [CN = INSTRUCTION]){{< /fatecode >}}
 
 Instruction corresponding to the execution of `[C0]` ... `[CN]` in order.
diff --git a/content/fate_v1/instructions/addresses/_index.md b/content/fate_v1/instructions/addresses/_index.md
index 1b9cdc1..cf5143b 100644
--- a/content/fate_v1/instructions/addresses/_index.md
+++ b/content/fate_v1/instructions/addresses/_index.md
@@ -1,6 +1,12 @@
 ---
 title: Addresses
 ---
+### ALLOCATION
+{{< fatecode >}}(allocate! [POINTER REFERENCE]){{< /fatecode >}}
+
+Set `[POINTER REFERENCE]` to the address of a new memory location of type
+`[TYPE]`. Don't forget to call `free` on it once you're done.
+
 ### DE-ALLOCATION
 {{< fatecode >}}(free! [POINTER]){{< /fatecode >}}
 
diff --git a/content/fate_v1/instructions/collections/_index.md b/content/fate_v1/instructions/collections/_index.md
index fb557c2..0922b3e 100644
--- a/content/fate_v1/instructions/collections/_index.md
+++ b/content/fate_v1/instructions/collections/_index.md
@@ -6,85 +6,133 @@ lists; and `[SET]`, which are ordered lists, but only useable with
 `[COMPARABLE]` elements.
 
 ### ADDING A MEMBER
-{{< fatecode >}}(add_element! [C0 = COMPUTATION*] ... [CN = COMPUTATION*] [COLLECTION VAR]){{< /fatecode >}}
+{{< fatecode >}}(list:add_element! [C0 = X COMPUTATION*] ... [CN = X COMPUTATION*] [X LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:add_element! [C0 = X COMPUTATION*] ... [CN = X COMPUTATION*] [X SET REFERENCE]){{< /fatecode >}}
 
-Adds `C0` ... `CN` to `[COLLECTION VAR]`. If `[COLLECTION VAR]` is a `[LIST]`,
-the new members are added at the end of the list, in order (meaning that the
-list then ends with `CN`). Note that `[COMPUTATION*]` does not support use of
-the variable shorthand.
+Adds `C0` ... `CN` to the `[X LIST]` or `[X SET]` collection reference. If the
+collection is a `[LIST]`, the new members are added at the end of the list, in
+order (meaning that the list then ends with `CN`). Note that `[COMPUTATION*]`
+does not support use of the variable shorthand if this is a collection of
+strings or text.
 
 ### ADDING A MEMBER AT INDEX
-{{< fatecode >}}(add_element_at! [INT] [COMPUTATION*] [LIST VAR]){{< /fatecode >}}
+{{< fatecode >}}(list:add_element_at! [INT] [X COMPUTATION*] [X LIST REFERENCE]){{< /fatecode >}}
 
-Adds `[COMPUTATION*]` to `[LIST VAR]` at index `[INT]`. If `[INT]` is less than
-0, the element is added at the start of the list, and if `[INT]` is greater or
-equal to the size of the list, the element is added at the end of the list. Note
-that `[COMPUTATION*]` does not support use of the variable shorthand.
+Adds `[COMPUTATION*]` to `[X LIST REFERENCE]` at index `[INT]`. If `[INT]` is
+less than 0, the element is added at the start of the list, and if `[INT]` is
+greater or equal to the size of the list, the element is added at the end of
+the list. Note that `[COMPUTATION*]` does not support use of the variable
+shorthand if this is a collection of string or text.
 
 ### ADDING MEMBERS
-{{< fatecode >}}(add_all_elements! [COLLECTION] [COLLECTION VAR]){{< /fatecode >}}
+{{< fatecode >}}(list:add_all_elements! [X COLLECTION] [X LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:add_all_elements! [X COLLECTION] [X SET REFERENCE]){{< /fatecode >}}
 
-Adds all the elements of `[COLLECTION]` to `[COLLECTION VAR]`. If
-`[COLLECTION VAR]` is a `[LIST]`, the new members are added at the end of the
-list.
+Adds all the elements of `[COLLECTION]` to the `[X LIST]` or `[X SET]`
+collection reference. In the case of `[X LIST]`, the new members are added at
+the end of the list.
 
 ### EMPTYING COLLECTIONS
-{{< fatecode >}}(clear! [COLLECTION]){{< /fatecode >}}
+{{< fatecode >}}(list:clear! [LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:clear! [SET REFERENCE]){{< /fatecode >}}
 
-Removes all members of `[COLLECTION]`.
+Removes all members of the `[LIST]` or `[SET]` collection reference.
 
 ### REMOVING MEMBER
-{{< fatecode >}}(remove! [COMPUTATION] [COLLECTION]){{< /fatecode >}}
+{{< fatecode >}}(list:remove! [X COMPUTATION*] [X LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:remove! [X COMPUTATION*] [X SET REFERENCE]){{< /fatecode >}}
 
-Removes the first member of `[COLLECTION]` equal to `[COMPUTATION]`.
+Removes the first member of the `[X LIST]` or `[X SET]` collection reference
+equal to `[COMPUTATION]`.  Note that `[COMPUTATION*]` does not support use of
+the variable shorthand if this is a collection of string or text.
 
 ### REMOVING MEMBERS
-{{< fatecode >}}(remove_all! [COMPUTATION] [COLLECTION]){{< /fatecode >}}
+{{< fatecode >}}(list:remove_all! [X COMPUTATION*] [X LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:remove_all! [X COMPUTATION*] [X SET REFERENCE]){{< /fatecode >}}
 
-Removes all instances of  `[COMPUTATION]` from `[COLLECTION]`.
+Removes all values equal to `[COMPUTATION]` from the `[X LIST]` or `[X SET]`
+collection reference.  Note that `[COMPUTATION*]` does not support use of the
+variable shorthand if this is a collection of string or text.
 
 ### REMOVING AT INDEX
-{{< fatecode >}}(remove_at! [INT] [COLLECTION]){{< /fatecode >}}
+{{< fatecode >}}(list:remove_at! [INT] [LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:remove_at! [INT] [SET REFERENCE]){{< /fatecode >}}
 
-Removes the element of `[COLLECTION]` at `[INT]`.
+Removes from the collection reference the element at index `[INT]`.
 
 ### REVERSING LISTS
-{{< fatecode >}}(reverse! [LIST]){{< /fatecode >}}
+{{< fatecode >}}(list:reverse! [LIST REFERENCE]){{< /fatecode >}}
 
-Reverses the order of the members of `[LIST]`.
+Reverses the order of the members of `[LIST REFERENCE]`.
 
 ### FILTER ELEMENTS
-{{< fatecode >}}(filter! [LAMBDA BOOL (X)] [X COLLECTION VAR]){{< /fatecode >}}
-{{< fatecode >}}(filter! [LAMBDA BOOL (X Y0 ... YN)] [X COLLECTION VAR] [Y0 COMPUTATION*] ... [YN COMPUTATION*]){{< /fatecode >}}
-Modifies `[X COLLECTION VAR]` so that only the elements for which
-`[LAMBDA BOOL (X)]` returns `true` remain. If the lambda function needs extra
-parameters, use the second syntax, which adds those parameters at the end of the
-`(filter! ...)` call. Note that the variable shorthand cannot be used for these
-extra parameters.
+{{< fatecode >}}(list:filter! [LAMBDA BOOL (X)] [X LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:filter! [LAMBDA BOOL (X)] [X SET REFERENCE]){{< /fatecode >}}
+Modifies the collection reference so that only the elements for which
+`[LAMBDA BOOL (X)]` returns `true` remain.
 
 ### FILTER ELEMENTS (INDEXED)
-{{< fatecode >}}(indexed_filter! [LAMBDA BOOL (INT X)] [X COLLECTION VAR]){{< /fatecode >}}
-{{< fatecode >}}(indexed_filter! [LAMBDA BOOL (INT X Y0 ... YN)] [X COLLECTION VAR] [Y0 COMPUTATION*] ... [YN COMPUTATION*]){{< /fatecode >}}
-Modifies `[X COLLECTION VAR]` so that only the elements for which
-`[LAMBDA BOOL (INT X)]` (with the `INT` being the element's index) returns
-`true` remain. If the lambda function needs extra parameters, use the second
-syntax, which adds those parameters at the end of the `(indexed_filter! ...)`
-call.  Note that the variable shorthand cannot be used for these extra
-parameters.
-
-### MERGE COLLECTIONS
-{{< fatecode >}}(merge! [LAMBDA Y (X Y)] [X COLLECTION] [Y COLLECTION VAR]){{< /fatecode >}}
-{{< fatecode >}}(merge! [LAMBDA Y (X Y Z0 ... ZN)] [X COLLECTION] [Y COLLECTION VAR] [Z0 COMPUTATION*] ... [ZN COMPUTATION*]){{< /fatecode >}}
-
-
-### SAFE-MERGE COLLECTIONS
-{{< fatecode >}}(safe_merge! [LAMBDA Y (X Y)] [X COMPUTATION*] [X COLLECTION] [Y COMPUTATION*] [Y COLLECTION VAR]){{< /fatecode >}}
-{{< fatecode >}}(safe_merge! [LAMBDA Y (X Y Z0 ... ZN)] [X COLLECTION] [X COMPUTATION*] [Y COMPUTATION*] [Y COLLECTION VAR] [Z0 COMPUTATION*] ... [ZN COMPUTATION*]){{< /fatecode >}}
-
-### MERGE COLLECTIONS (INDEXED)
-{{< fatecode >}}(indexed_merge! [LAMBDA Y (INT X Y)] [X COLLECTION] [Y COLLECTION VAR]){{< /fatecode >}}
-{{< fatecode >}}(indexed_merge! [LAMBDA Y (INT X Y Z0 ... ZN)] [X COLLECTION] [Y COLLECTION VAR] [Z0 COMPUTATION*] ... [ZN COMPUTATION*]){{< /fatecode >}}
-
-### SAFE-MERGE COLLECTIONS (INDEXED)
-{{< fatecode >}}(safe_indexed_merge! [LAMBDA Y (INT X INT Y)] [X COMPUTATION*] [X COLLECTION] [Y COMPUTATION*] [Y COLLECTION VAR]){{< /fatecode >}}
-{{< fatecode >}}(safe_indexed_merge! [LAMBDA Y (INT X INT Y Z0 ... ZN)] [X COMPUTATION*] [X COLLECTION] [Y COMPUTATION*] [Y COLLECTION VAR] [Z0 COMPUTATION*] ... [ZN COMPUTATION*]){{< /fatecode >}}
+{{< fatecode >}}(list:indexed_filter! [LAMBDA BOOL (INT X)] [X LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:indexed_filter! [LAMBDA BOOL (INT X)] [X SET REFERENCE]){{< /fatecode >}}
+Modifies the collection reference so that only the elements for which
+`[LAMBDA BOOL (INT X)]` returns `true` remain, with the `[INT]` value being the
+index of the element in the collection.
+
+### SUBLIST
+{{< fatecode >}}(list:sublist! [start_at = INT] [end_before = INT] [LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:sublist! [start_at = INT] [end_before = INT] [SET REFERENCE]){{< /fatecode >}}
+
+Only keep in the collection reference the elements with indexes equal or
+greater than `[start_at]` and strictly lower than `[end_before]`.
+
+### SORT
+{{< fatecode >}}(list:sort! [LAMBDA INT (X X)] [X LIST REFERENCE]){{< /fatecode >}}
+
+Reorders the elements of the list reference according to the `[LAMBDA]`
+function. The resulting order is ascending. To compare two elements, the lambda
+function should return:
+- a negative number if the first argument is lower than the second.
+- zero if the first argument is equal to the second.
+- a non-null positive number otherwise.
+
+### SHUFFLE
+{{< fatecode >}}(list:shuffle! [LIST REFERENCE]+){{< /fatecode >}}
+
+Randomly changes the order of the elements in `[LIST REFERENCE]`. As a
+shorthand, multiple calls to the `list:shuffle!` instruction can be merged by
+passing more lists as arguments.
+
+### PUSH ELEMENT
+{{< fatecode >}}(list:push_right! [X COMPUTATION] [X LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(list:push_left! [X COMPUTATION] [X LIST REFERENCE]){{< /fatecode >}}
+
+Adds an element `[X]` at the start (`list:push_left`) or the end
+(`list:push_right`) of a list reference.
+
+### POP ELEMENT
+{{< fatecode >}}(list:pop_right! [X LIST REFERENCE] [X REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(list:pop_left! [X LIST REFERENCE] [X REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:pop_right! [X SET REFERENCE] [X REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:pop_left! [X SET REFERENCE] [X REFERENCE]){{< /fatecode >}}
+
+
+Removes and retrieves the element at the start (`pop_left`) or the end
+(`pop_right`) of a list. The removed element is stored in `[X REFERENCE]`.
+
+### PARTITION
+{{< fatecode >}}(list:partition! [LAMBDA BOOL (X)] [if_true = X LIST REFERENCE] [if_false = X LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:partition! [LAMBDA BOOL (X)] [if_true = X SET REFERENCE] [if_false = X SET REFERENCE]){{< /fatecode >}}
+
+Partitions a collection reference `[if_true]`, leaving in the collection all elements
+for which the lambda function returns `(true)` and moving to the collection reference
+`[if_false]` all elements for which the lambda function returns `(false)`.
+
+### PARTITION (INDEXED)
+{{< fatecode >}}(list:partition! [LAMBDA BOOL (INT X)] [if_true = X LIST REFERENCE] [if_false = X LIST REFERENCE]){{< /fatecode >}}
+{{< fatecode >}}(set:partition! [LAMBDA BOOL (INT X)] [if_true = X SET REFERENCE] [if_false = X SET REFERENCE]){{< /fatecode >}}
+
+Partitions a collection reference `[if_true]`, leaving in the collection all elements
+for which the lambda function returns `(true)` and moving to the collection reference
+`[if_false]` all elements for which the lambda function returns `(false)`. The first
+argument given to the lambda function corresponds to the index of the element in
+the collection (prior to the partitioning).
diff --git a/content/fate_v1/instructions/conditionals/_index.md b/content/fate_v1/instructions/conditionals/_index.md
index 39a51b3..f99a1cf 100644
--- a/content/fate_v1/instructions/conditionals/_index.md
+++ b/content/fate_v1/instructions/conditionals/_index.md
@@ -6,22 +6,36 @@ computation. Every conditional branch defines its hierarchy level, from the
 local variables' point of view.
 
 ### IF
-{{< fatecode >}}(if [BOOL] [INSTRUCTION]){{< /fatecode >}}
+{{< fatecode >}}(if [BOOL]
+   [INSTRUCTION]
+){{< /fatecode >}}
 
 Executes `[INSTRUCTION]` if, and only if, `[BOOL]` yields true.
 
 ### IF-ELSE
-{{< fatecode >}}(if_else [BOOL] [IF_TRUE = INSTRUCTION] [IF_FALSE = INSTRUCTION]){{< /fatecode >}}
+{{< fatecode >}}(if_else [BOOL]
+   [IF_TRUE = INSTRUCTION]
+   [IF_FALSE = INSTRUCTION]
+){{< /fatecode >}}
 
 Executes `[IF_TRUE]` if `[BOOL]` yields true, but `[IF_FALSE]` if it does not.
 
 ### COND
-{{< fatecode >}}(cond ([C0 = BOOL] [I0 = INSTRUCTION]) ... ([CN = BOOL] [IN = INSTRUCTION])){{< /fatecode >}}
+{{< fatecode >}}(cond
+   ([C0 = BOOL] [I0 = INSTRUCTION])
+   ...
+   ([CN = BOOL] [IN = INSTRUCTION])
+){{< /fatecode >}}
 
 Executes `[II]`, such that `[CI]` is the first listed boolean to yield true.
 
 ### SWITCH
-{{< fatecode >}}(switch [T = COMPUTATION] ([C0 = COMPUTATION] [I0 = INSTRUCTION]) ... ([CN = COMPUTATION] [IN = INSTRUCTION]) [DEFAULT = INSTRUCTION]){{< /fatecode >}}
+{{< fatecode >}}(switch [T = COMPUTATION]
+   ([C0 = COMPUTATION] [I0 = INSTRUCTION])
+   ...
+   ([CN = COMPUTATION] [IN = INSTRUCTION])
+   [DEFAULT = INSTRUCTION]
+){{< /fatecode >}}
 
 Executes `[II]`, such that `[CI]` is the first listed computation to be equal
 to `[T]`. Executes `[DEFAULT]` if there is no such `[CI]`.
diff --git a/content/fate_v1/instructions/loops/_index.md b/content/fate_v1/instructions/loops/_index.md
index 5aa14ac..82acb28 100644
--- a/content/fate_v1/instructions/loops/_index.md
+++ b/content/fate_v1/instructions/loops/_index.md
@@ -6,24 +6,44 @@ Every loop body defines its hierarchy level, from the local variables' point of
 view.
 
 ### WHILE
-{{< fatecode >}}(while [BOOL] [I0 = INSTRUCTION] ... [IM = INSTRUCTION]){{< /fatecode >}}
+{{< fatecode >}}(while [BOOL]
+   [I0 = INSTRUCTION]
+   ...
+   [IM = INSTRUCTION]
+){{< /fatecode >}}
 
 Executes `[I0]` ... `[IM]` if, and as long as, `[BOOL]` yields true.
 
 ### DO WHILE
-{{< fatecode >}}(do_while [BOOL] [I0 = INSTRUCTION] ... [IM = INSTRUCTION]){{< /fatecode >}}
+{{< fatecode >}}(do_while [BOOL]
+   [I0 = INSTRUCTION]
+   ...
+   [IM = INSTRUCTION]
+){{< /fatecode >}}
 
 Executes `[I0]` ... `[IM]`,  and does so again as long as, `[BOOL]` yields
 true.
 
 ### FOR
-{{< fatecode >}}(for [PRE = INSTRUCTION] [BOOL] [POST = INSTRUCTION] [I0 = INSTRUCTION] ... [IM = INSTRUCTION]){{< /fatecode >}}
+{{< fatecode >}}(for
+   [PRE = INSTRUCTION]
+   [BOOL]
+   [POST = INSTRUCTION]
+
+   [I0 = INSTRUCTION]
+   ...
+   [IM = INSTRUCTION]
+){{< /fatecode >}}
 
 Executes `[PRE]`, then, if and as long as `[BOOL]` yields true, executes
 `[I0]` ... `[IM]` followed by `[POST]`.
 
 ### FOR EACH
-{{< fatecode >}}(foreach [COLLECTION] {String} [I0 = INSTRUCTION] ... [IM = INSTRUCTION]){{< /fatecode >}}
+{{< fatecode >}}(foreach [COLLECTION] {String}
+   [I0 = INSTRUCTION]
+   ...
+   [IM = INSTRUCTION]
+){{< /fatecode >}}
 
 Executes `[I0]` ... `[IM]` for each member of `[COLLECTION]`, in order. The current
 member is stored in a new local variable named `{String}`.
diff --git a/content/fate_v1/instructions/player_choices/_index.md b/content/fate_v1/instructions/player_choices/_index.md
index 9ead97c..4b54789 100644
--- a/content/fate_v1/instructions/player_choices/_index.md
+++ b/content/fate_v1/instructions/player_choices/_index.md
@@ -6,17 +6,29 @@ with a list of `[TEXT]` choices, and executing a list of instructions
 associated to the choice they have made.
 
 ### CHOICE OPTION
-{{< fatecode >}}(option [TEXT] [I0 = INSTRUCTION] ... [IN = INSTRUCTION]){{< /fatecode >}}
+{{< fatecode >}}(option [TEXT]
+   [I0 = INSTRUCTION]
+   ...
+   [IN = INSTRUCTION]
+){{< /fatecode >}}
 
 Adds a choice showing `[TEXT]` to the user, and executing `[I0]` ... `[IN]`
 if chosen.
 
 ### CHOICE PROMPT
-{{< fatecode >}}(player_choice! [C0 = CHOICE] ... [C1 = CHOICE]){{< /fatecode >}}
+{{< fatecode >}}(player_choice!
+   [C0 = CHOICE]
+   ...
+   [C1 = CHOICE]
+){{< /fatecode >}}
 
 Prompts the user to choose between `C0` ... `C1`. `[CHOICE]`. `[CHOICE]` is
 either an option as shown above, a [conditional](../conditionals), or a
 `for_each` (see [loops](../loops)) with `[CHOICE]` instead of `[INSTRUCTION]`.
+A special version of the `for` loop is also possible, as described below:
+
+### USER CHOICE - FOR
+TODO
 
 ### INTEGER PROMPT
 {{< fatecode >}}(prompt_integer! [INT REFERENCE] [MIN = INT] [MAX = INT] [TEXT]){{< /fatecode >}}