Improves how topics collapse on the menu.

13 files changed, 187 insertions, 167 deletions

diff --git a/config.toml b/config.toml
index 05b4ec1..2eb15bb 100644
--- a/config.toml
+++ b/config.toml
@@ -4,7 +4,7 @@ title = "Tonkadur"
 theme = "hugo-theme-learn"
 
 [params]
-   custom_css = ["css/prism.css"]
+   custom_css = ["css/prism.css", "css/collapse.css"]
    disableShortcutsTitle=true
    disableInlineCopyToClipBoard=true
    themeVariant = "glauque"
diff --git a/content/fate_v1/_index.md b/content/fate_v1/_index.md
index 29e595d..3f20dc4 100644
--- a/content/fate_v1/_index.md
+++ b/content/fate_v1/_index.md
@@ -9,155 +9,38 @@ meant to provide the writer with as many tools as possible, so that they do not
 feel constrained by the limitations of the language, nor find writing complex
 narratives tedious.
 
-## A few warnings first
-
-Fate uses strong typing. This is intended to make detection of mistakes easier,
-but may lead to some frustrations for authors only used to languages using
-dynamic typing.
-
-Fate does not have any special features for multi-seating/multi-player
-narratives. This is by design, as adding proper support for this would make the
-underlying language more complex, and thus would make it harder to create an
-interpreter for it. This is however something considered for an extension
-(see
-[this GitHub issue about it](https://github.com/nsensfel/tonkadur/issues/5)).
-
-You'll need to learn parentheses management, if you make anything complex. Fate
-uses a LISP inspired syntax, so parentheses are everywhere. The syntax gives you
-free reign over indentation, but so many parentheses does require at least some
-discipline in order to be readable.
-
-Fate is meant to be compiled. This does add an extra step to your existing
-process.
-
-Fate is very much a new language. There isn't many (any?) tools for it.
-
-If for some reason you want to perform memory allocation, there is no automatic
-garbage collection, so you will have to free whatever you allocate.
-
-In what may seem weird for narrative scripting, Fate does not feature string
-manipulation operations. Strings can be made into rich text, with complex
-attributes, but you will not be able to use things like regular expressions
-(or anything other than simple concatenation, really) with just the base
-language. This is because of these operations would need to be implemented
-directly by the interpreter anyway, and their use isn't actually common in
-a narrative description, which would make requiring support for them of
-any Tonkadur interpreter problematic.
-
-## Some nice features
-
-If you haven't closed the tab yet, here are some reasons why you *might* want
-to use Fate.
-
-It *is* a LISP inspired syntax. If that's what you like, you might even enjoy
-this take on it. There's no fiddling with indentation, no wondering what symbol
-does what. It's all about parentheses indicating something is performed on a
-list of other things. It's not a purely functional language, though. In fact,
-it's a mix of both declarative and imperative programming: sequences (or
-procedures) are imperative. Computations are functional. There are lambda
-functions, but they're strongly typed. Collections and structures can only be
-modified through specific instructions, so it's not quite really a LISP-like
-language.
-
-There are pointers. Oh, come on, it's a plus, *right?* This makes it a lot
-easier to refer to things. There's no pointer arithmetic, so you don't have to
-worry about the scary stuff. Also, this lets you allocate memory, which is
-useful when you want a unspecified amount of distinct instances of something.
-Want to describe a story where the player can push a button as many time as
-they choose, create a clone of a creature every time they do so, yet let them
-fight any of these creature as their distinct instance? Well, with memory
-allocation and pointers, it's easily done. Didn't you know? When writing a
-narrative, the RAM's the limit. So yeah, maybe don't forget to `free` the
-thousands of monster the player will no doubt create.
-
-You can do recursion. Wait! I *am* listing the nice features! Do people really
-not like recursion and pointers? Oh, well... Still, you can do recursions with
-both procedures and lambda functions. Not a fan of recursion? That's alright,
-you also have imperative loops: `for`, `while`, `do_while`, and even
-`for_each`.
-
-## The basics
-
-#### Procedures (or Sequences) and Instructions
-Procedures are lists of instructions and things to display. Instructions can be
-applied to values, but they themselves do not return any value.  Any value not
-part of an instruction found in a procedure is displayed. Any value being part
-of an instruction is **not** displayed.
-
-One way to think about it is to consider procedures as being actually two types
-of things: sequences and procedures. A sequence is then a scene in the story,
-and a procedure is just a construct called upon to perform instructions.
-
-Procedures can take arguments. Values are passed by copy.
-
-Procedures can be called in two ways: a `call` or a `jump`. A `call` will
-perform the procedure before continuing with the current sequence of
-instructions. A `jump` will perform the procedure **instead of** the
-**current** sequence of instructions.
-
-Procedures can be called before their definition. The compiler will simply tell
-you if the definition ends up being incompatible or missing.
-
-#### Computations
-Computations are operations returning a value. Computations do not modify
-anything, they simply return the result of an operation.
-
-A special type of computation, called *lambda function*, allows the creation of
-a computation that will be performed only when called upon. Those can take
-parameters. What's the use of something as advanced in a narrative scripting
-language? It's convenient when you want to express something like a character's
-name who depends on what the player figured out. Sure, you *could* make each
-instance of the name feature a series of tests to find which value to use, or
-you could just use a lambda function and just put
-`(eval name_of_mysterious_character)` to get the right value.
-
-One last thing about lambda functions, which really are the only potentially
-complicated thing about computations: these *are* computations, so you can use
-them as such. They also cannot modify anything, as they only contain
-computations and not instructions.
-
-#### Declarations and First Level Instructions
-Declarations and First Level Instructions are a special type of instruction
-which can only be done from outside a procedure. This distinction means that,
-for example, you cannot define a procedure from within a procedure.
-
-#### Events
-Sometimes, you might need to communicate something to the interpreter which
-cannot be expressed in Fate. For example, you might want to say: "pause for 30
-seconds", or "play this music". This kind of thing has been considered to not
-be generic enough to mandate every interpreter supports it. Instead, events are
-used.
-
-Events are first declared, by being given a name and a list of types
-corresponding to the parameters they take. Then, the `(event ...)` instruction
-can be used to indicate that a certain event should occur. This will pause the
-execution, and make the interpreter react to the event before continuing.
-
-The effect of an event is purely the interpreter's responsibility. It cannot be
-described in Fate. Thus, you will need to refer to the interpreter you use to
-see what events are available.
-
-#### Types
-The basic `string`, `int`, `float`, and `bool` types are what one would expect.
-
-`text` corresponds to text with decorations, see the text effect sub-section.
-
-Two collection types are available: `(list [TYPE])` is a list of `[TYPE]`
-elements, and `(set [COMPARABLE])` is a set of `[COMPARABLE]` elements.
-
-`(ptr [TYPE])` is an address to a value of type `[TYPE]`.
-
-Structures can be defined. They may contain other structures, but cannot be
-recursive: only already defined types can be used. Pointers cannot be used to
-resolve this conundrum in this version of Fate, but it may be added in the next
-version (see [this GitHub
-issue](https://github.com/nsensfel/tonkadur/issues/6)).
-
-#### Player Choices
-Inputs from the players are limited to the `(player_choice ...)` instruction.
-It presents the player with `text` options to choose from, which execute
-an associated list of instructions if chosen.
-
-More complicated inputs, such as retrieving a `string` or an `int` from the
-player require the definition and use of events.
-
+To write in Fate, simply open your favorite text editor and create a new file
+that starts with the following line:
+{{< fatecode >}}(fate_version 1){{< /fatecode >}}
+
+Before going any further into the documentation, you should familiarize yourself
+with the [notations](/fate_v1/notations/).
+
+Fate files are composed of three types of constructs:
+* [Computations](/fate_v1/computations/), operations that do not modify the
+  memory and return a value.
+* [Instructions](/fate_v1/instructions/), constructs that can modify the memory
+  but do not return any values.
+* [Declarations](/fate_v1/declarations/), special instructions that are
+  performed during compilation instead of during the execution.
+
+Other concepts in Fate include:
+* [Variables](/fate_v1/declarations/variables/): named memory element.
+* [Types](/fate_v1/declarations/types/): every memory element is assigned a
+  specific type. Fate uses static and strong typing, meaning that types are
+  determined at compilation time and typing
+* [Procedures/Sequences](/fate_v1/declarations/sequences/): named list of
+  instructions, which can take parameters.
+* [Lambda Functions](/fate_v1/computations/lambda_functions/): computations
+  which are not performed immediately but are instead stored for future use.
+* [Addresses/Pointers](/fate_v1/computations/addresses/): value that
+  corresponds to a memory element (not to be confused with the value *of* that
+  memory element).
+* Conditionals: selection of
+  [computations](/fate_v1/computations/conditionals/) or
+  [instructions](/fate_v1/instructions/conditionals/) depending on a
+  computation.
+* [Loops](/fate_v1/instructions/loops/): repetition of instructions controlled
+  by computations.
+* [Choices](/fate_v1/instructions/player_choices/): prompt the user to select an
+  option.
diff --git a/content/fate_v1/computations/_index.md b/content/fate_v1/computations/_index.md
index e8a8816..9b835de 100644
--- a/content/fate_v1/computations/_index.md
+++ b/content/fate_v1/computations/_index.md
@@ -1,9 +1,8 @@
 ---
 title: Computations
-weight: 2
+weight: 3
 ---
-Computations are values. They may read from the memory, but do not modify it
-(with a single exception).
+Computations are operations returning values. They do not modify the memory.
 
 ### TEXT
 {{< fatecode >}}(text [C0 = COMPUTATION] ... [CN = COMPUTATION]){{< /fatecode >}}
@@ -36,7 +35,8 @@ Returns the value of the `{String}` field of the structure `[STRUCTURE]`.
 ### TEMPORARY VARIABLES
 {{< fatecode >}}(let (({V0 = String} [C0 = COMPUTATION]) ... ({VN = String} [CN = COMPUTATION])) [R = COMPUTATION]){{< /fatecode >}}
 
-Defines a hierarchical level and local variables `V0` ... `VN` with values `C0` ... `CN`, and returns the value of `[R]`.
+Defines a hierarchical level and local variables `{V0}` ... `{VN}` with values
+`[C0]` ... `[CN]`, and returns the value of `[R]`.
 
 ### CAST
 {{< fatecode >}}(cast [TYPE] [COMPUTATION*]){{< /fatecode >}}
diff --git a/content/fate_v1/computations/references/_index.md b/content/fate_v1/computations/addresses/_index.md
index ba5716a..aafd0f1 100644
--- a/content/fate_v1/computations/references/_index.md
+++ b/content/fate_v1/computations/addresses/_index.md
@@ -1,5 +1,5 @@
 ---
-title: References
+title: Addresses
 ---
 ### VALUE ACCESS
 {{< fatecode >}}(at [ADDRESS]){{< /fatecode >}}
diff --git a/content/fate_v1/declarations/_index.md b/content/fate_v1/declarations/_index.md
index c079924..97a982e 100644
--- a/content/fate_v1/declarations/_index.md
+++ b/content/fate_v1/declarations/_index.md
@@ -2,5 +2,5 @@
 title: "Declarations"
 menuTitle: "Declarations"
 chapter: true
-weight: 1
+weight: 2
 ---
diff --git a/content/fate_v1/extensions/_index.md b/content/fate_v1/extensions/_index.md
index c0598ea..6189745 100644
--- a/content/fate_v1/extensions/_index.md
+++ b/content/fate_v1/extensions/_index.md
@@ -1,5 +1,5 @@
 ---
 title: Extensions
-weight: 5
+weight: 6
 ---
 This page not available yet, sorry.
diff --git a/content/fate_v1/instructions/_index.md b/content/fate_v1/instructions/_index.md
index 95ee992..3f86e2e 100644
--- a/content/fate_v1/instructions/_index.md
+++ b/content/fate_v1/instructions/_index.md
@@ -1,6 +1,6 @@
 ---
 title: Instructions
-weight: 3
+weight: 4
 ---
 Instructions do not return values, but modify the memory in some way or
 interact with the interpreter. Computations are valid instructions, and will be
diff --git a/content/fate_v1/instructions/references/_index.md b/content/fate_v1/instructions/addresses/_index.md
index 9beb132..e296f2c 100644
--- a/content/fate_v1/instructions/references/_index.md
+++ b/content/fate_v1/instructions/addresses/_index.md
@@ -1,5 +1,5 @@
 ---
-title: References
+title: Addresses
 ---
 ### DE-ALLOCATION
 {{< fatecode >}}(free [POINTER]){{< /fatecode >}}
diff --git a/content/fate_v1/instructions/player_choices/_index.md b/content/fate_v1/instructions/player_choices/_index.md
index a0dba20..4aea5a0 100644
--- a/content/fate_v1/instructions/player_choices/_index.md
+++ b/content/fate_v1/instructions/player_choices/_index.md
@@ -2,13 +2,13 @@
 title: Player Choices
 ---
 Player choices are the main way to interact with the user, by presenting them
-with a list of `[RICH TEXT]` choices, and executing a list of instructions
+with a list of `[TEXT]` choices, and executing a list of instructions
 associated to the choice they have made.
 
 ### CHOICE OPTION
 {{< fatecode >}}([TEXT] [I0 = INSTRUCTION] ... [IN = INSTRUCTION]){{< /fatecode >}}
 
-Adds a choice showing `[RICH TEXT]` to the user, and executing `[I0]` ... `[IN]`
+Adds a choice showing `[TEXT]` to the user, and executing `[I0]` ... `[IN]`
 if chosen.
 
 ### CHOICE PROMPT
diff --git a/content/fate_v1/notations/_index.md b/content/fate_v1/notations/_index.md
new file mode 100644
index 0000000..320bdbe
--- /dev/null
+++ b/content/fate_v1/notations/_index.md
@@ -0,0 +1,118 @@
+---
+title: "Notations"
+menuTitle: "Notations"
+weight: 1
+---
+
+This page explains the notations used on this documentation, as well as some
+basics of Fate syntax.
+
+Fate uses a LISP inspired syntax, meaning that parentheses have a special
+importance and that everything uses a prefix notation. Basically, everything
+follows a `(O A B C D)` form, where `O` is being applied to `A`, `B`, `C`, and
+`D`.
+
+Valid separators are spaces, tabs, and line returns. Having multiple separators
+between two elements is the same as having a single one.
+
+### Comments
+Comments are line without anything but any number of separators before `;;`.
+Every that follows the `;;` on that line is considered to be a comment.
+{{< fatecode >}};; You can comment here
+(fate_version 1)
+     ;; Separators before the ';;' are also okay.
+something ;; This is not a comment, since the line contains something else.
+;; Multi line
+;; comments need a ';;' on
+;; every line.
+(end)
+{{< /fatecode >}}
+
+### Literals
+A literal is a hard-coded string. Basically, writing `42` corresponds to a
+literal of value `42`. A literal is any non-empty hard-coded string not
+containing a separator, nor any parentheses.
+
+This documentation uses `{` and `}` to denote literal values.
+
+Fate is pretty strict with typing, so literals have to have a type. The rule is
+as follows: does Java parses the literal as an integer? If so, it's an `{INT}`;
+otherwise, if it parses as a float? If so, it's a `{FLOAT}`; otherwise, it's a
+`{STRING}`.
+
+Now, the rules about separators and parentheses being absent in literals is a
+bit problematic for strings. To remedy this:
+* Writing `(lp)` counts as writing the literal `(`.
+* Writing `(rp)` counts as writing the literal `)`.
+* Writing `(sp)` counts as writing the literal ` ` (space).
+
+Thus, you cannot write:
+{{< fatecode >}}This is not valid (because of parentheses).{{< /fatecode >}}
+
+But you can write:
+{{< fatecode >}}This is valid (lp)because of parentheses(rp).{{< /fatecode >}}
+And it will be a bunch of `{STRING}` literals.
+
+### Identifier
+`{IDENTIFIER}`: Non-empty string literal without space characters, `.`, `)`,
+or `(`.  Line returns and tabs are considered to be space characters. Strings
+that correspond to valid numbers (e.g. `42`) are likely to cause issues and
+should thus be avoided.
+
+Examples of valid identifiers:
+* {{< fatecode >}}i{{< /fatecode >}}
+* {{< fatecode >}}what-kind_ofMonsterIS#THIS?{{< /fatecode >}}
+* {{< fatecode >}}変数{{< /fatecode >}}
+* {{< fatecode >}}80x9!{{< /fatecode >}}
+* {{< fatecode >}}pseudo::namespacing<$confusion>**a**{{< /fatecode >}}
+
+
+### Value
+`[INT]`: Computation (or literal) returning a value of type `INT`. Similarly,
+`[STRING]` would indicate the same for a value of type `STRING`.
+
+`[COMPUTATION]`: Any computation, the accepted type being determined by
+something else.
+
+Variable names can be used directly when a computation is expected. Since this
+would cause issues when `[STRING]` values can also be used, this feature is not
+always available. Cases where this feature is not available are suffixed with
+a `*`. For example, `[COMPUTATION*]` means that writing `my_var` is interpreted
+as the `[STRING]` literal `my_var`, and to get the value of a variable, you
+would need to write something like `(var my_var)`. `[STRING]` automatically
+implies `[STRING*]`.
+
+If need be, `(string {STRING})`
+
+Examples of valid value:
+* Values for `[INT]`:
+   * {{< fatecode >}}42{{< /fatecode >}}
+   * {{< fatecode >}}(+ 2 100 11 0 3 9){{< /fatecode >}}
+   * {{< fatecode >}}my_int_var{{< /fatecode >}}
+* Values for `[STRING]`:
+   * {{< fatecode >}}(string 42){{< /fatecode >}}
+   * {{< fatecode >}}Just some random words...{{< /fatecode >}}
+   * {{< fatecode >}}not_my_var{{< /fatecode >}}
+   * {{< fatecode >}}(var my_string_var){{< /fatecode >}}
+
+### Disambiguation and variadic operators
+In Fate, the computation to obtain a random integer is as follows:
+{{< fatecode >}}(rand [INT] [INT]){{< /fatecode >}}
+This notation makes it difficult to document what each `[INT]` corresponds to.
+To remedy this, names are given to each instance:
+{{< fatecode >}}(rand [I0 = INT] [I1 = INT]){{< /fatecode >}}
+Now, `[I0]` refers to the first `[INT]` value, and `[I1]` to the second one.
+
+Some operators can take a variable number of parameters. For example, the
+documentation for the logical conjunction computation is:
+{{< fatecode >}}(and [B0 = BOOL] ... [BN = BOOL]){{< /fatecode >}}
+The `...` indicate that there can be any number of instances of the type of parameter
+that just preceded. In this example, `[B0 = BOOL] ...` indicates that there
+can be any number of `[BOOL]` parameters. The parameter `[BN = BOOL]` is part
+of the `...` notation and simply indicates that the documentation considers that
+there are `N + 1` parameters. Thus, here, the documentation would allow:
+* {{< fatecode >}}(and){{< /fatecode >}}
+* {{< fatecode >}}(and (true)){{< /fatecode >}}
+* {{< fatecode >}}(and (true) (false)){{< /fatecode >}}
+* {{< fatecode >}}(and (true) (false) (false)){{< /fatecode >}}
+* {{< fatecode >}}(and (true) (false) (false) (true)){{< /fatecode >}}
diff --git a/content/setup/_index.md b/content/setup/_index.md
index a9cb42c..275e809 100644
--- a/content/setup/_index.md
+++ b/content/setup/_index.md
@@ -43,7 +43,7 @@ A Wyrd interpreter keeps track of:
 of any Wyrd type.
 * **The Program Counter:** an integer corresponding to the next Wyrd instruction
 to execute.
-* **Available Choices:** A list of `RICH_TEXT`.
+* **Available Choices:** A list of `TEXT`.
 * **Last Chosen Choice:** Index of the last chosen choice.
 * **The Code:** A list of instructions.
 
diff --git a/content/wyrd_v1/computations/_index.md b/content/wyrd_v1/computations/_index.md
index bf7992d..bc30f12 100644
--- a/content/wyrd_v1/computations/_index.md
+++ b/content/wyrd_v1/computations/_index.md
@@ -88,10 +88,10 @@ type `[TYPE]`.
 {{< fatecode >}}(newline){{< /fatecode >}}
 Returns a `TEXT` value corresponding to a newline.
 
-{{< fatecode >}}(rich_text [S0 = STRING] ... [SN = STRING]){{< /fatecode >}}
+{{< fatecode >}}(text [S0 = STRING] ... [SN = STRING]){{< /fatecode >}}
 Returns a single value `[TEXT]` representing the elements `S0` ... `S1`.
 
-{{< fatecode >}}(add_rich_text_effect ({string} [V0 = COMPUTATION] ... [VN = COMPUTATION]) [TEXT]){{< /fatecode >}}
+{{< fatecode >}}(add_text_effect ({string} [V0 = COMPUTATION] ... [VN = COMPUTATION]) [TEXT]){{< /fatecode >}}
 Returns a `[TEXT]` value of `[TEXT]` with the given effect enabled.
 
 ## LAST USER CHOICE
diff --git a/static/css/collapse.css b/static/css/collapse.css
new file mode 100644
index 0000000..6c3e926
--- /dev/null
+++ b/static/css/collapse.css
@@ -0,0 +1,19 @@
+#sidebar .topics ul li
+{
+  display: none;
+}
+
+#sidebar .topics>ul>li
+{
+  display: block;
+}
+
+#sidebar .topics .parent>ul>li
+{
+  display: block;
+}
+
+#sidebar .topics .active>ul>li
+{
+  display: block;
+}