From 2ac2ba39f26ceaf38ad910d8319394be36d6f2ac Mon Sep 17 00:00:00 2001
From: hanez <you@hanez.org>
Date: Sun, 12 Oct 2025 23:21:43 +0200
Subject: [PATCH] Added docs/handbook.md. No code changes. (0.26.5)

---
 README.md        |  52 ++++--------------------
 docs/handbook.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 107 insertions(+), 45 deletions(-)
 create mode 100644 docs/handbook.md

diff --git a/README.md b/README.md
index 9bfb908..913cdda 100644
--- a/README.md
+++ b/README.md
@@ -69,33 +69,18 @@ Fun may not change the world — but it will make programming a little more fun.
 
 ## Documentation
 
-Actually, there does not exist any documentation. In the [examples/](https://git.xw3.org/fun/fun/src/branch/main/examples) directory should be an example of most Fun features.
+I am writing documentation only actually, but this is work in progress, since debugging and bug fixing includes this task.
+
+Current documentation is only found in the [Fun Handbook](/fun/fun/src/branch/main/docs/handbook.md).
+
+In the [examples/](/fun/fun/src/branch/main/examples) directory should be an example of most Fun features.
+
+A complete API documentation will follow.
 
 ## Development
 
 This section is a work in progress... Please excuse the lack of more information. There are daily updates here.
 
-### Requirements
-
-A C compiler, a libc and [Git](https://git-scm.com/).
-
-#### FreeBSD
-
-- [CMake](https://cmake.org/)
-- [Clang](https://clang.llvm.org/)
-
-#### Linux
-
-- [CMake](https://cmake.org/)
-- [GCC](https://gcc.gnu.org/) (Clang should work here too, not tested!)
-
-#### Windows
-
-This requires Cygwin to be installed and configured. I will not cover this here.
-
-- [CMake](https://cmake.org/)
-- [Cygwin](https://cygwin.com/) using [GCC](https://gcc.gnu.org/)
-
 ### Rules
 
 - Every commit requires a version incremantion in CMakeLists.txt before committing
@@ -169,29 +154,6 @@ FUN_LIB_DIR="$(pwd)/lib" ./build/fun
 
 But be sure to build Fun with -DFUN_WITH_REPL=ON.
 
-## Installation
-
-I do not recommend installing Fun on your system because it is in a very early
-stage of development, but I can say that I have Fun installed on my system. If
-you want to do that too, type:
-
-```bash
-git clone https://git.xw3.org/fun/fun.git
-cd fun
-cmake -S . -B build -DFUN_DEBUG=OFF -DFUN_WITH_PCSC=OFF -DFUN_WITH_REPL=ON
-cmake --build build --target fun
-sudo cmake --build build --target install
-```
-
-### Usage
-
-Now run Fun without prefixed FUN_LIB_DIR="$(pwd)/lib" because libs are installed to the
-system default lib directory (/usr/share/fun/lib).
-
-```bash
-fun ./demo.fun
-```
-
 ## Author
 
 Johannes Findeisen - you@hanez.org
diff --git a/docs/handbook.md b/docs/handbook.md
new file mode 100644
index 0000000..14dfbd0
--- /dev/null
+++ b/docs/handbook.md
@@ -0,0 +1,100 @@
+# Fun Handbook
+
+## Overview
+
+## Introduction
+
+## Installation
+
+### Requirements
+
+A C compiler, a libc and [Git](https://git-scm.com/).
+
+#### FreeBSD
+
+- [CMake](https://cmake.org/)
+- [Clang](https://clang.llvm.org/)
+
+#### Linux
+
+- [CMake](https://cmake.org/)
+- [GCC](https://gcc.gnu.org/) (Clang should work here too, not tested!)
+
+#### Windows
+
+This requires Cygwin to be installed and configured. I will not cover this here.
+
+- [CMake](https://cmake.org/)
+- [Cygwin](https://cygwin.com/) using [GCC](https://gcc.gnu.org/)
+
+### Build Fun
+
+Linux/UNIX only covered here for now.
+
+Clone repository:
+
+```bash
+git clone https://git.xw3.org/fun/fun.git
+```
+
+Change directory:
+
+```bash
+cd fun
+```
+
+Build:
+
+```bash
+cmake -S . -B build -DFUN_DEBUG=OFF -DFUN_WITH_PCSC=OFF -DFUN_WITH_REPL=ON &&
+cmake --build build --target fun
+```
+
+That's it! For testing it, run:
+
+```bash
+FUN_LIB_DIR="$(pwd)/lib" ./build/fun ./demo.fun
+```
+
+To see what's going on, run:
+
+```bash
+FUN_LIB_DIR="$(pwd)/lib" ./build/fun --trace ./demo.fun
+```
+
+To switch into the REPL after an error, run:
+
+```bash
+FUN_LIB_DIR="$(pwd)/lib" ./build/fun --repl-on-error --trace ./demo.fun
+```
+
+Both --repl-on-error and --trace are optional but can always be combined. To get
+more debug information, you need to build Fun with -DFUN_DEBUG=ON.
+
+To directly run the REPL, you have to run:
+
+```bash
+FUN_LIB_DIR="$(pwd)/lib" ./build/fun
+```
+
+But be sure to build Fun with -DFUN_WITH_REPL=ON.
+
+### Install Fun to OS
+
+I do not recommend installing Fun on your system because it is in a very early
+stage of development, but I can say that I have Fun installed on my system. If
+you want to do that too, type:
+
+```bash
+sudo cmake --build build --target install
+```
+
+Now run Fun without prefixed FUN_LIB_DIR="$(pwd)/lib" because libs are installed to the
+system default lib directory (/usr/share/fun/lib).
+
+## Usage
+
+```bash
+fun ./demo.fun
+```
+