From f06afe4ed5cb336fe78c4d7bb101e8d8fbfd5c50 Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Tue, 3 Feb 2026 01:16:04 +0200 Subject: [PATCH] Rephrased and expanded introduction in documentation for clarity and detail. --- doc/index.html | 275 ++++++++++++++++++++++++------------------------- doc/index.org | 37 ++++--- 2 files changed, 160 insertions(+), 152 deletions(-) diff --git a/doc/index.html b/doc/index.html index 174e5ec..56dea8e 100644 --- a/doc/index.html +++ b/doc/index.html @@ -3,13 +3,13 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Fifth - virtual machine, operating system, programming language - + @@ -202,49 +211,48 @@

Table of Contents

- -
-

1. General

+
+

1. General

- -
-

1.1. Source code

+
+

1.1. Source code

  • Download latest snapshot in TAR GZ format
    • @@ -283,51 +289,51 @@ Clone Git repository using command: 

    -git clone https://www2.svjatoslav.eu/git/fifth.git
+git clone https://www3.svjatoslav.eu/git/fifth.git
- -
-

2. !Project deprecated!

+
+

2. Introduction

-Current implementation does not support object oriented -programming. While working on Fifth I got lots of cool new ideas that -require reimplementation of everything. +Fifth is self-hosting computing environment that integrates a custom +virtual machine, a Forth-inspired programming language, and operating +system.

-Currently I try to implement those new ideas in the project called -Sixth. +At its core lies a stack-based virtual CPU with two stacks (data and +return), approximately 50 instructions, and a 4GB flat address +space. This virtual machine executes the Fifth language — a concise, +interactive, and extensible environment where every operation is a +command that can be defined, redefined, or extended by the user. The +language uses a custom character encoding (FSCII) with unique +representations for control characters (e.g., space as FF instead of +20 in ASCII) and features an innovative hexadecimal number system +visualized as squares split into four triangles, each representing a +single bit—similar to Bibi-binary.

-System is built many years ago when I was still using DOS as a primary -operating system. +It includes a disk-based filesystem, a built-in text editor, 2D +graphics capabilities, mouse and keyboard drivers, and tools for file +management and memory allocation.

-
-
-
-

3. Introduction

-
+

-Fifth is a combination of: +Released under the CC0 public domain license, Fifth is free for anyone +to use, study, and modify. Whether you're a retro computing +enthusiast, a systems programming student, or a curious developer.

-
+
+

2.1. Screenshots

+
-
-

3.1. Screenshots

-
- -
+

start.png

@@ -337,7 +343,7 @@ Startup screen diplaying Fifth logo and full file list.

-
+

dictionary.png

@@ -350,7 +356,7 @@ executed, they can be selectively compiled or interpreted. -
+

text editor.png

@@ -361,10 +367,9 @@ Built in text editor.
- -
-

4. Installation

-
+
+

3. Installation

+

Just unpack all files, witout altering original directory structure, somewhere in your hard disk. For example: @@ -384,15 +389,14 @@ To run fifth you need minimally just 2 files:

-For more information, please refer to Fifth distribution directory +For more information, please refer to Fifth distribution directory tree description.

- -
-

5. Fifth distribution directory tree description

-
+
+

4. Fifth distribution directory tree description

+

After downloading and unpacking the ZIP file you shoud get directory tree similar to this: @@ -415,14 +419,13 @@ tree similar to this:

- -
-

6. Requirements

-
+
+

5. Requirements

+
-
-

6.1. Software

-
+
+

5.1. Software

+
  • MS-DOS 6.22 with HIMEM.SYS loaded.
  • Mouse driver (optional, if you have a mouse).
    • @@ -433,10 +436,9 @@ tree similar to this:
- -
-

6.2. Hardware

-
+
+

5.2. Hardware

+
  • A minimum of a i386 CPU.
  • 64 KB of free RAM below 640KB.
    • @@ -446,10 +448,9 @@ tree similar to this:
- -
-

7. Numbers representation within Fifth

-
+
+

6. Numbers representation within Fifth

+

Because we are in full experimentation mode here (no regard for compatibility whatsoever), why not to try also alternative number @@ -461,7 +462,7 @@ Here alternative hexadecimal number representation format is devised:

-
+

numbers.png

@@ -481,19 +482,18 @@ See also: Bibi-binary.

- -
-

8. Disk file map, and it's data structures

-
+
+

7. Disk file map, and it's data structures

+

Core and high-level boot code is stored outside of the filesystem to allow easy access to it, at early booting time, when filesystem is not yet initialized.

-
-

8.1. Disk allocation

-
+
+

7.1. Disk allocation

+
@@ -539,9 +539,9 @@ yet initialized.
-
-

8.2. FAT entry format:

-
+
+

7.2. FAT entry format:

+
@@ -575,9 +575,9 @@ yet initialized.
-
-

8.3. File entry format

-
+
+

7.3. File entry format

+
@@ -630,9 +630,9 @@ yet initialized. -
-

9. Core architecture

-
+
+

8. Core architecture

+

Fifth core is simply some amount of already compiled into machine code and linked together modules (entries in other words). In compilation @@ -644,9 +644,9 @@ dictionary space only. Random word can be removed from dictionary at any time. Currently dictionary can contain at most 1000 entries.

-
-

9.1. Dictionary entry format

-
+
+

8.1. Dictionary entry format

+
@@ -713,9 +713,9 @@ run through headers backwards and find needed entry.

-
-

9.2. Possible module types

-
+
+

8.2. Possible module types

+
@@ -769,9 +769,9 @@ run through headers backwards and find needed entry.
-
-

9.3. Memory map

-
+
+

8.3. Memory map

+
@@ -818,13 +818,13 @@ run through headers backwards and find needed entry. -
-

10. Dynamically loadable modules

-
+
+

9. Dynamically loadable modules

+
-
-

10.1. Keyboard driver

-
+
+

9.1. Keyboard driver

+


KBD_@ ( – code ) get scancodes for pressed keys from keyboard.
@@ -861,9 +861,9 @@ FF space

-
-

10.2. Mouse driver

-
+
+

9.2. Mouse driver

+

mousex var Mouse x coordinate.
mousey var Mouse y coordinate.
@@ -882,9 +882,9 @@ mousedo ( – ) Updates mouse coordinates and keys. Parse mouse

-
-

10.3. 2D graphic library

-
+
+

9.3. 2D graphic library

+
lineh ( color len x y imgbuf – )
draws horisontal line from X,Y coordinates to right, with specified length.
@@ -897,7 +897,7 @@ draws rectangular box. x2 bust be >= x1, y2 must be >= y1.

-
+
 x1,y1-----------+
   |             |
   |             |
@@ -914,25 +914,24 @@ location X & Y with specified color.
- -
-

10.4. Trigonometry functions

-
+
+

9.4. Trigonometry functions

+
-
-

10.4.1. sin ( a – result )

-
+
+

9.4.1. sin ( a – result )

+

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.

-
-

10.4.2. cos ( a – result )

-
+
+

9.4.2. cos ( a – result )

+

-Return cosinus from given angle. Parameters are like in sin function. +Return cosinus from given angle. Parameters are like in sin function.

@@ -941,7 +940,7 @@ Return cosinus from given angle. Parameters are like in s
diff --git a/doc/index.org b/doc/index.org index c370a29..18c4996 100644 --- a/doc/index.org +++ b/doc/index.org @@ -17,23 +17,32 @@ - [[https://www2.svjatoslav.eu/gitweb/?p=fifth.git;a=summary][Browse Git repository online]] - Clone Git repository using command: - : git clone https://www2.svjatoslav.eu/git/fifth.git + : git clone https://www3.svjatoslav.eu/git/fifth.git -* !Project deprecated! -Current implementation does not support object oriented -programming. While working on Fifth I got lots of cool new ideas that -require reimplementation of everything. - -Currently I try to implement those new ideas in the project called -[[https://www3.svjatoslav.eu/projects/sixth/][Sixth]]. +* Introduction -System is built many years ago when I was still using DOS as a primary +Fifth is self-hosting hobby computing environment that integrates a +[[id:9b251eb9-aff6-4025-94bf-25e89e26d54a][custom virtual machine]], a [[id:da7fff9b-0b67-4843-828a-52a404d7f401][Forth-inspired programming language]], and operating system. -* Introduction -Fifth is a combination of: -- [[id:da7fff9b-0b67-4843-828a-52a404d7f401][Programming language]] (inspired by Forth). -- Operating system. -- [[id:9b251eb9-aff6-4025-94bf-25e89e26d54a][Virtual machine]] with custom instruction set. + +At its core lies a stack-based virtual CPU with two stacks (data and +return), approximately 50 instructions, and a 4GB flat address +space. This virtual machine executes the Fifth language — a concise, +interactive, and extensible environment where every operation is a +command that can be defined, redefined, or extended by the user. The +language uses a custom character encoding (FSCII) with unique +representations for control characters (e.g., space as FF instead of +20 in ASCII) and features an innovative hexadecimal number system +visualized as squares split into four triangles, each representing a +single bit—similar to Bibi-binary. + +It includes a disk-based filesystem, a built-in text editor, 2D +graphics capabilities, mouse and keyboard drivers, and tools for file +management and memory allocation. + +Released under the CC0 public domain license, Fifth is free for anyone +to use, study, and modify. Whether you're a retro computing +enthusiast, a systems programming student, or a curious developer. ** Screenshots -- 2.20.1