New structure + scaffholds for a few drafts + completed docs aswell (#9)

* Added docs about different utils

* added few sources

* reorganization of the index file

* Updated the structure of the project + added scaffhold for some docs

* its now a beautiful link

* added the info that embedFile is compile time

README.org

@@ -1,2 +1,11 @@
 * Zig Documentation
 The purpose of this repository is to document the features of the Zig language, as well as examples of its use.
+
+You can use this documentation with 2 different ways:
+- Using emacs org mode so that you can execute codes on the fly(litterate programming)
+- Opening the index.html file in your browser or navigating to our [[hosted guide][https://pismice.github.io/HEIG_ZIG/]] 
+
+** Remarks
+- We are going to move all the "Sources" to the "Bilbliography" chapter using Zotero
+- Some exemples are not working with emacs yet
+- You might see a few TODO or empty chapters, those are the ones we are working on or plan to work on in the future

docs/concurrency.org

@@ -1,3 +1,4 @@
+* Concurrency
 ** Definitions
 Coroutine (cooperative multitasking): 
 - a coroutine itself is not concurrent !, it allows to manage concurrent tasks in the same way as callbacks for example
@@ -19,15 +20,14 @@ Asymmetric coroutines (called asymmetric because the control-transfer can go bot
 2. suspending itself and giving control back to the caller
 
 Green threads (userland threads):
-- preemptive multitasking (PAS VRAI !)
-- managed by a VM/runtime instead of the OS (TODO: A CONIRMER AVEC LE PROF JLUI POSERAI LA QUESTION)
+- preemptive multitasking (PAS VRAI selon appel !)
+- managed by a VM/runtime instead of the OS 
 - has the advantage to be managed in user space instead of kernel space which allows to avoid the overhead of making system calls to open and close threads
 - still use several native threads behind the scenes
 - used more for short-lived tasks
 
 Fibers :
 - Same as green threads but cooperative multitasking instead of preemptive multitasking
-- TODO: confirmer avec le prof si ya pas autre chose
 
 Preemptive multitasking:
 - The underlying architecture (NOT us) is going to be deciding what to execute and when
@@ -54,17 +54,24 @@ Event-driven programming (ex: NodeJS):
 ** Zig current state
 There a multiple ways you currently can do concurent code in ZIG:
 - Spawning OS threads (https://ziglang.org/documentation/master/std/#std.Thread)
-- Using old async/await from before 0.11 (not recommanded because unstable !!! https://github.com/ziglang/zig/issues/6025)
+- Using old async/await from before 0.11 (not recommanded because unstable !!! https://github.com/ziglang/zig/issues/6025 and might probably never get back in the language https://ziglang.org/download/0.12.0/release-notes.html#AsyncAwait-Feature-Status)
 - Using an event loop (by wrapping libuv or using libxev which is the equivalent buz in ZIG)
 - Using fibers (https://github.com/kprotty/zefi, https://github.com/kassane/fiber)
 - async/await built on top of libxev (https://github.com/rsepassi/zigcoro)
 - Low level single threaded concurrency if you want to craft your owng thing (https://github.com/kassane/context)
 - ... obviously you can still use C libraries that do async stuff :)
 
+*** Feedbacks from thoses methods:
+**** OS threads
+**** Old async/await
+**** libxev
+**** CHOISIR UNE DES 2 fibers
+**** zigcoro
+
 ** Function coloring
 Green threads make function colors disapear ???? (dependences entre threads)
 
-** MES NOTES -------- pas besoin de lire ca, cest juste pour moi
+** TODO MES NOTES -------- pas besoin de lire ca, cest juste pour moi pour approfondir certains sujets plus tard
 
 - "libuv and OSes will usually run background/worker threads and/or polling to perform tasks in a non-blocking manner." est ce que cest comment ca under the hood les non blocking async ?
 

docs/errors.org

@@ -1,11 +1,11 @@
-* Errors
+** Errors
 https://ziglang.org/documentation/0.11.1/#Errors
 In ZIG errors are juste values.
 Those values are those of an special type of enum "error".
 When you declare your enum using this keyword instead of "enum", the compiler is going to know that those values are going to be errors, therefore they can be catched, tried, ...
 
 
-** Handling errors in the application flow
+*** Handling errors in the application flow
 Functions can return either a value or an error, this is done by adding the "!" to the return type of a function
 With the "!" the return type of the function below is the coerced "anyerror!u8"
 
@@ -40,7 +40,7 @@ test "should panic" {
 }
 #+end_src
 
-** Errdefer
+*** Errdefer
 This exemple is taken from: https://ziglang.org/documentation/0.11.1/#errdefer
 Errdefer is a particularity of ZIG, it allows the user to execute some code when the function returns an error, it is useful exemple for deallocating variables you would have normally returned from the function, but since the function failed you deallocate that memory to avoid a memory leak.
 #+source: simple
@@ -65,7 +65,7 @@ fn createFoo(param: i32) !Foo {
 #+end_src
 
 
-** Coercing
+*** Coercing
 The rule is simple: you can coerce an error from a subset to a superset but you cannot coerce an error from a superset to a subset
 
 #+source: simple

docs/external-files.org

@@ -1,14 +1,58 @@
+** Reading external files
 There are multiple ways to do it in ZIG:
-1. @embedFile
-Simply going to embed the file in the binary.
-https://ziglang.org/documentation/master/#embedFile
+*** @embedFile
+This method is simply going to embed the file in the binary at compile time.
 
-2. Use an allocator to dynamically store the content of the file 
+Beware that by using this method the path to the file is going to be relative to the file you are calling it from and that the file must be in the same package.
+
+By using the other methods below you can use a file from anywhere but relative to your root folder and not main.zig.
+#+begin_src zig :imports '(std) :main 'yes :testsuite 'no
+const input = @embedFile("input.txt");
+std.debug.print("{s}", .{input});
+#+end_src
+
+*** Use an allocator to dynamically store the content of the file 
 By using the method: readToEndAlloc 
-https://ziglang.org/documentation/master/std/#std.fs.File.readToEndAlloc
+#+begin_src zig :imports '(std) :main 'yes :testsuite 'no
+// Alocator
+var gp = std.heap.GeneralPurposeAllocator(.{ .safety = true }){};
+defer gp.deinit();
+const allocator = gp.allocator();
+
+// Path
+var path_buffer: [std.fs.MAX_PATH_BYTES]u8 = undefined;
+const path = try std.fs.realpath("./input.txt", &path_buffer);
+
+// Open file
+const file = try std.fs.openFileAbsolute(path, .{});
+defer file.close();
+
+// Read
+const file_content = try file.readToEndAlloc(allocator, std.math.maxInt(usize));
+defer allocator.free(file_content);
+#+end_src
 
-3. Read the file and put it in a buffer
+*** Read the file and put it in a buffer
 By using the method readAll 
-https://ziglang.org/documentation/master/std/#std.fs.File.readAll
+#+begin_src zig :imports '(std) :main 'yes :testsuite 'no
+// Path
+var path_buffer: [std.fs.MAX_PATH_BYTES]u8 = undefined;
+const path = try std.fs.realpath("./input.txt", &path_buffer);
+
+// Open file
+const file = try std.fs.openFileAbsolute(path, .{});
+defer file.close();
+
+// Read
+var content_buffer: [1024]u8 = undefined;
+const size = try file.readAll(&content_buffer);
+
+std.debug.print("{s}", .{content_buffer[0..size]});
+#+end_src
+
+TODO reading files with org babel doesnt work yet idk why
 
-TODO mettre des exemples pour chacun
+Sources: 
+- https://ziglang.org/documentation/master/std/#std.fs.File.readToEndAlloc
+- https://ziglang.org/documentation/master/std/#std.fs.File.readAll
+- https://ziglang.org/documentation/master/#embedFile

docs/http.org

@@ -1,6 +1,5 @@
+** HTTP from the std
+*** Description
 Http.zig: Dispatcher based, you create the dispatch chai (As far as I understand it)
-Zap: Callback based, we define certain callbacks, we configure from there
-Tokamak: Middleware (scoped) and DI Based
-Jetzig: Middleware (as part of a request chain) and Convention based
-
-https://www.reddit.com/r/reactjs/comments/16blsh3/how_do_i_use_react_with_an_express_application/
+*** Exemples
+TODO