From 21629af8ec39205ef6e5418b0655ad05a530eb58 Mon Sep 17 00:00:00 2001
From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Wed, 18 Feb 2026 06:48:33 +0200
Subject: [PATCH] Clarify trigonometric functions.

---
 doc/index.org | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/doc/index.org b/doc/index.org
index 522d669..6d20bd7 100644
--- a/doc/index.org
+++ b/doc/index.org
@@ -167,6 +167,7 @@ The directory entries are stored within the filesystem data
 area. Directory is just a file that list other files.
 
 * Core architecture
+
 Fifth core is simply some amount of already compiled into machine code
 and linked together modules (entries in other words). In compilation
 process modules is compiled one by one and simply stored on top of
@@ -175,6 +176,7 @@ dictionary, this is special list that contain names of compiled
 modules, variables etc. and they locations in core. Constants use
 dictionary space only. Random word can be removed from dictionary at
 any time. Currently dictionary can contain at most 1000 entries.
+
 ** Dictionary entry format
 | offset | length | description           |
 |--------+--------+-----------------------|
@@ -191,7 +193,9 @@ any time. Currently dictionary can contain at most 1000 entries.
 Core headers as linked list of module names make up something like
 dictionary.  When some entry address is needed compiler can quickly
 run through headers backwards and find needed entry.
+
 ** Possible module types
+
 | type | description    | "execute" action           |
 |------+----------------+----------------------------|
 |    0 | data           | compile "num" instruction  |
@@ -201,13 +205,16 @@ run through headers backwards and find needed entry.
 |      |                | with address to module     |
 |------+----------------+----------------------------|
 |    2 | imm. submodule | immediately call to module |
+
 ** Memory map
+
 | location | size   | description                 |
 |----------+--------+-----------------------------|
 |        0 | ~4096  | core                        |
 |  1500000 | ~32000 | highlevel Fifth boot code   |
 |  200000h |        | core startup messages area  |
 |  5200000 |        | end of dynamic memory space |
+
 * Dynamically loadable modules
 ** Keyboard driver
 #+BEGIN_VERSE
@@ -288,11 +295,31 @@ mousedo         ( -- ) Updates mouse coordinates and keys. Parse mouse
   location X & Y with specified color.
 
 ** Trigonometry functions
+
+
 *** sin ( a -- result )
 :PROPERTIES:
 :ID:       9a66ca9c-eb5f-45aa-8116-71763081f2fb
 :END:
-Return sinus from given angle "a", 360ø is 2000. So 1000 represents
-180ø angle.  Result will be in range -10'000 to 10'000, instead of ñ1.
+
+Return sine of angle "a", where the:
+
+- Input is scaled such that: 360 degrees = 2000 units (i.e., 1 unit =
+  0.18 degrees).
+
+- The output is scaled to a 16-bit integer range of -10000 to 10000,
+  where ±10000 represents ±1.0 in floating-point terms.
+
+This fixed-point representation allows efficient computation using
+precomputed lookup tables, avoiding floating-point operations which
+are not supported by the virtual CPU's integer-only instruction
+set. The lookup table provides fast, sine values within the system's
+precision.
+
 *** cos ( a -- result )
-Return cosinus from given angle.  Parameters are like in [[id:9a66ca9c-eb5f-45aa-8116-71763081f2fb][sin]] function.
+
+Return cosine of angle "a", using the same scaling and fixed-point
+representation as the [[id:9a66ca9c-eb5f-45aa-8116-71763081f2fb][sin]] function. Input angles are scaled (360° =
+2000 units), and outputs range from -10000 to 10000. Precomputed
+values in a lookup table ensure high performance for trigonometric
+calculations.
-- 
2.20.1