chore: update docs regarding embedding and the __arkscript__ folder

Author: SuperFola

content/docs/guides/coding.md

@@ -158,7 +158,7 @@ for (std::size_t i = 0, end = container.size(); i < end; i++)
 ```cpp
 /**
  * @file Lexer.hpp
- * @author Lex Plateau (lexplt.dev@gmail.com)
+ * @author Lexy Plateau (lexplt.dev@gmail.com)
  * @brief Tokenize ArkScript code
  * @date 2020-10-27
  *
@@ -176,7 +176,7 @@ Snippet to recapitulate guidelines for headers:
 ```cpp
 /**
  * @file Lexer.hpp
- * @author Lex Plateau (lexplt.dev@gmail.com)
+ * @author Lexy Plateau (lexplt.dev@gmail.com)
  * @brief Tokenize ArkScript code
  * @date 2020-10-27
  *

content/docs/prologue/building.md

@@ -24,7 +24,7 @@ You can choose to build the project from source (which requires some knowledge l
 *This step is optional*
 
 1. You can create an environment variable `ARKSCRIPT_PATH`, with the path to the installation directory of ArkScript, so that the standard library can be located without using `--lib <path>`.  
-The environment variable should direct to a folder with the folder `lib/` inside. Multiple path can be provided if your installation separates the modules and the standard library, by separating the different paths with a single `;`.
+The environment variable should direct to a folder with the folder `std/` inside. Multiple path can be provided if your installation separates the modules and the standard library, by separating the different paths with a single `;`.
 2. You can create an environment variable `ARKSCRIPT_REPL_STARTUP`, with the path to a single `.ark` file that will be loaded each time you use the REPL. Useful to preload your favorite libraries!
 
 ## Installing from a release
@@ -112,8 +112,11 @@ Commands:
 ```shell
 cmake . -Bbuild -DARK_BUILD_EXE=On
 cmake --build build --config Release
+
 # needs administrator rights to install under /usr/bin
 sudo cmake --install build --config Release
+# OR install under a custom directory (it must exists, cmake won't create it)
+cmake --install build --config Release --prefix /opt/ArkScript
 ```
 
 ### Building on MacOS
@@ -122,7 +125,15 @@ Requirements:
 - clang 16+
 - cmake >= 3.15
 
-On MacOS versions prior to 10.15, `libc++` lacks `filesystem` in the standard library.
+```shell
+cmake . -Bbuild -DARK_BUILD_EXE=On -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang
+cmake --build build --config Release
+cmake --install build --config Release  # might need administrator rights
+```
+
+---
+
+On MacOS versions **prior to 10.15**, `libc++` lacks `filesystem` in the standard library.
 
 You will need to:
 - Install a newer compiler using [Homebrew](https://docs.brew.sh/): `brew install gcc && brew link gcc`
@@ -131,9 +142,9 @@ You will need to:
 Commands:
 
 ```shell
-~/ark$ cmake . -Bbuild -DARK_BUILD_EXE=On -DCMAKE_CXX_COMPILER=/usr/local/bin/g++-14
-~/ark$ cmake --build build --config Release
-~/ark$ cmake --install build --config Release  # might need administrator rights
+cmake . -Bbuild -DARK_BUILD_EXE=On -DCMAKE_CXX_COMPILER=/usr/local/bin/g++-14
+cmake --build build --config Release
+cmake --install build --config Release  # might need administrator rights
 ```
 
 ### Building for the web using emscripten
@@ -165,7 +176,9 @@ cmake --build build_emscripten -j 8
 
 ### Running the tests
 
-To check that everything works, it is important to run the tests for the projects, and we have a multitude of them:
+To check that everything works, it is important to run the tests for the project. They can be compiled using `-DARK_TESTS`, building a `unittests` executable.
+
+The kind of tests we have:
 - `tests/benchmarks`: benchmarks for the parser and VM with a few scripts to help identifying regressions
 - `tests/fuzzing`: a collection of scripts (in `tests/fuzzing/docker/`) and ArkScript source files under the different `corpus` / `corpus-cmin` / `corpus-cmin-tmin` directories (only the `corpus` directory is managed by us, the two others are generated automatically through scripts and AFL++). Fuzzers can be run automatically using the `start-afl-docker.sh` script, that starts a docker image, compile ArkScript and run the fuzzers inside tmux sessions. An `output/` folder is created at the root of the project with the fuzzers output
 - `tests/repl`: a short test for the REPL to ensure it still autocompletes correctly

content/docs/prologue/getting_started.md

@@ -78,6 +78,6 @@ Everyone is welcome to contribute to the project, as long as you are respectful
 
 ## Using ArkScript in your company
 
-I (Lex Plateau) am working pretty much alone on this project, and I try to do my best to leave it as bug free and as performant as possible. However, this is a side project for which I'm currently **not paid** to work on, thus I can't fix every bug or address every feature request in a timely manner.
+I (Lexy Plateau) am working pretty much alone on this project, and I try to do my best to leave it as bug free and as performant as possible. However, this is a side project for which I'm currently **not paid** to work on, thus I can't fix every bug or address every feature request in a timely manner.
 
 Please reach out either by email (lexplt.dev@gmail.com) or via a [discussion](https://github.com/orgs/ArkScript-lang/discussions) before using the language in a company project, so that we can set up a support contract. If you don't want to set up a contract, your issues and support requests won't be prioritized (and possibly left unanswered).

content/docs/tutorials/embedding.md

@@ -73,7 +73,7 @@ int main()
 
     // Run an ArkScript function from C++ code and retrieve the result:
     auto value = vm.call("foo", 5, 6.0);
-    std::cout << value << "\n";  // prints 13
+    std::cout << value.toString(vm) << "\n";  // prints 13
 
     // If you just want to run a precompiled bytecode file:
     {
@@ -100,7 +100,7 @@ Ark::Value my_function(std::vector<Ark::Value>& args, Ark::VM* vm)
         throw std::runtime_error("my_function needs 4 arguments!");
 
     if (!types::check(args, Ark::ValueType::Number, Ark::ValueType::Number, Ark::ValueType::Number, Ark::ValueType::Number))
-        Ark::types::generateError(
+        throw Ark::types::TypeCheckingError(
             "my_function",
             { { Ark::types::Contract { {
                 Ark::types::Typedef("a", ValueType::Number),
@@ -137,10 +137,10 @@ int main()
     vm.run();
 
     auto bar = vm["bar"];
-    std::cout << bar << "\n";
+    std::cout << bar.toString(vm) << "\n";
 
     auto egg = vm["egg"];
-    std::cout << egg << "\n";
+    std::cout << egg.toString(vm) << "\n";
 
     return 0;
 }
@@ -205,7 +205,7 @@ int main()
         return Ark::Nil;
     });
 
-    state.doString("(begin (let a (getBreakfast)) (print a) (useBreakfast a))");
+    state.doString("(let a (getBreakfast)) (print a) (useBreakfast a)");
     Ark::VM vm(&state);
     vm.run();
 

content/docs/tutorials/language.md

@@ -19,6 +19,13 @@ aliases:
 
 {{< highlight_scripts >}}
 
+## Running code
+
+Create a `file.ark` on your disk, and from a terminal, run `arkscript file.ark`.  
+This will create a cache folder `__arkscript__/` with the compiled bytecode inside, that the VM will then run.
+
+*Alternatively*, you can head to the [playground](https://playground.arkscript-lang.dev) to run your code online.
+
 ## The basics
 
 In ArkScript, there are two main rules: