From 404df5a007951012b727f2a90bc3a59254a05dbd Mon Sep 17 00:00:00 2001 From: Svjatoslav Agejenko Date: Tue, 19 Sep 2023 18:10:01 +0300 Subject: [PATCH] Rephrased documentation for better readability --- doc/index.html | 251 +++++++++++++++++++++------------------------- doc/index.org | 47 +++++---- doc/language.html | 68 +++++++------ doc/language.org | 1 + 4 files changed, 179 insertions(+), 188 deletions(-) diff --git a/doc/index.html b/doc/index.html index cadd753..174e5ec 100644 --- a/doc/index.html +++ b/doc/index.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Fifth - virtual machine, operating system, programming language @@ -194,27 +194,6 @@ .org-svg { } - -
@@ -223,50 +202,49 @@

Table of Contents

-
-

1. General

+
+

1. General

  • This program is free software: released under Creative Commons Zero @@ -293,8 +271,8 @@
-
-

1.1. Source code

+
+

1.1. Source code

-
-

2. !Project deprecated!

+
+

2. !Project deprecated!

Current implementation does not support object oriented @@ -332,8 +310,8 @@ operating system.

-
-

3. Introduction

+
+

3. Introduction

Fifth is a combination of: @@ -342,14 +320,14 @@ Fifth is a combination of:

  • Programming language (inspired by Forth).
  • Operating system.
  • Virtual machine with custom instruction set.
    • -
  • Example Fifth source file - text editor
    • -
    -

    3.1. screenshots

    + +
    +

    3.1. Screenshots

    -
    +

    start.png

    @@ -359,20 +337,20 @@ Startup screen diplaying Fifth logo and full file list.

    -
    +

    dictionary.png

    Sample words defined. Most of the words are commands that can be -executed interactively from command line or from file. When executed -they can be selectively compiled or interpreted. +executed interactively from the command line or from a file. When +executed, they can be selectively compiled or interpreted.

    -
    +

    text editor.png

    @@ -384,24 +362,36 @@ Built in text editor.
    -
    -

    4. Installation

    +
    +

    4. Installation

    Just unpack all files, witout altering original directory structure, -somewhere in your hard disk. For example: C:\MISC\FIFTH\…. To run -fifth you need minimally just 2 files. emulator itself ( EMULATOR.EXE -or EMULATOR.COM ), and virtual disk file ( DISK.RAW ). +somewhere in your hard disk. For example:

    +
    +C:\MISC\FIFTH\
+
    + +

    -Read more about Fifth distribution directory tree description. +To run fifth you need minimally just 2 files: +

    +
    +
    EMULATOR.COM
    Virtual CPU emulator
    +
    DISK.RAW
    Virtual disk file
    +
    + +

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

    -
    -

    5. Fifth distribution directory tree description

    +
    +

    5. Fifth distribution directory tree description

    After downloading and unpacking the ZIP file you shoud get directory @@ -426,46 +416,39 @@ tree similar to this:

    -
    -

    6. Requirements

    +
    +

    6. Requirements

    -
    -

    6.1. Software

    +
    +

    6.1. Software

      -
    • MS-DOS 6.22, with HIMEM.SYS loaded.
      • -
    • Mouse driver if you have a mouse.
      • -
    • Does work only when CPU is in real mode.
      • -
    • To recompile ASM sources I used FASM (Flat Assembler).
      • -
    • I ran QBasic utilities on QB 4.5 .
      • -
    • VESA support by BIOS, or external driver (UNIVBE).
      • +
    • MS-DOS 6.22 with HIMEM.SYS loaded.
      • +
    • Mouse driver (optional, if you have a mouse).
      • +
    • CPU is initialized into Unreal Mode during operation.
      • +
    • To recompile ASM sources, you can use FASM (Flat Assembler).
      • +
    • To run Quick Basic utilities, use Microsoft Quick Basic 4.5.
      • +
    • VESA support through BIOS or external driver (UNIVBE).
    -
    -

    6.2. Hardware

    + +
    +

    6.2. Hardware

      -
    • Minimum CPU 386.
      • -
    • 64 KB free RAM below 640KB,
      • -
    • 2 MB of free XMS.
      • -
    • VESA compatible video card.
      • +
    • A minimum of a i386 CPU.
      • +
    • 64 KB of free RAM below 640KB.
      • +
    • 2 MB of free extended memory.
      • +
    • A VESA-compatible video card.
    -
    -

    6.3. Human

    -
    -
      -
    • Beginner level Forth knowledge is recommended.
      • -
    • Lots of enthusiasm.
      • -
    -
    -
    -
    -

    7. Numbers representation within Fifth

    + +
    +

    7. Numbers representation within Fifth

    Because we are in full experimentation mode here (no regard for @@ -478,7 +461,7 @@ Here alternative hexadecimal number representation format is devised:

    -
    +

    numbers.png

    @@ -499,8 +482,8 @@ See also: Bibi-binary.
    -
    -

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

    +
    +

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

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

    -
    -

    8.1. Disk allocation

    +
    +

    8.1. Disk allocation

    @@ -556,8 +539,8 @@ yet initialized.
    -
    -

    8.2. FAT entry format:

    +
    +

    8.2. FAT entry format:

    @@ -592,8 +575,8 @@ yet initialized.
    -
    -

    8.3. File entry format

    +
    +

    8.3. File entry format

    @@ -647,8 +630,8 @@ yet initialized. -
    -

    9. Core architecture

    +
    +

    9. Core architecture

    Fifth core is simply some amount of already compiled into machine code @@ -661,8 +644,8 @@ 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

    +
    +

    9.1. Dictionary entry format

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

    -
    -

    9.2. Possible module types

    +
    +

    9.2. Possible module types

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

    9.3. Memory map

    +
    +

    9.3. Memory map

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

    10. Dynamically loadable modules

    +
    +

    10. Dynamically loadable modules

    -
    -

    10.1. Keyboard driver

    +
    +

    10.1. Keyboard driver


    @@ -878,8 +861,8 @@ FF space

    -
    -

    10.2. Mouse driver

    +
    +

    10.2. Mouse driver

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

    -
    -

    10.3. 2D graphic library

    +
    +

    10.3. 2D graphic library

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

    -
    +
     x1,y1-----------+
   |             |
   |             |
@@ -932,12 +915,12 @@ location X & Y with specified color.
    -
    -

    10.4. Trigonometry functions

    +
    +

    10.4. Trigonometry functions

    -
    -

    10.4.1. sin ( a – result )

    +
    +

    10.4.1. sin ( a – result )

    Return sinus from given angle "a", 360ø is 2000. So 1000 represents @@ -945,11 +928,11 @@ Return sinus from given angle "a", 360ø is 2000. So 1000 represents

    -
    -

    10.4.2. cos ( a – result )

    +
    +

    10.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.

    @@ -958,7 +941,7 @@ Return cosinus from given angle. Parameters are like in s
    diff --git a/doc/index.org b/doc/index.org index 4d9c4a0..c370a29 100644 --- a/doc/index.org +++ b/doc/index.org @@ -34,8 +34,9 @@ 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. -- [[file:5TH_ET.txt][Example Fifth source file - text editor]] -** screenshots + +** Screenshots + [[file:screenshots/start.png]] Startup screen diplaying Fifth logo and full file list. @@ -43,8 +44,8 @@ Startup screen diplaying Fifth logo and full file list. [[file:screenshots/dictionary.png]] Sample words defined. Most of the words are commands that can be -executed interactively from command line or from file. When executed -they can be selectively compiled or interpreted. +executed interactively from the command line or from a file. When +executed, they can be selectively compiled or interpreted. [[file:screenshots/text editor.png]] @@ -53,11 +54,16 @@ Built in text editor. * Installation Just unpack all files, witout altering original directory structure, -somewhere in your hard disk. For example: C:\MISC\FIFTH\.... To run -fifth you need minimally just 2 files. emulator itself ( EMULATOR.EXE -or EMULATOR.COM ), and virtual disk file ( DISK.RAW ). +somewhere in your hard disk. For example: + +: C:\MISC\FIFTH\ -Read more about [[id:0759f3e0-28bb-4901-9e4f-09ef41732173][Fifth distribution directory tree description]]. +To run fifth you need minimally just 2 files: +- EMULATOR.COM :: Virtual CPU emulator +- DISK.RAW :: Virtual disk file + +For more information, please refer to [[id:0759f3e0-28bb-4901-9e4f-09ef41732173][Fifth distribution directory +tree description]]. * Fifth distribution directory tree description :PROPERTIES: @@ -84,20 +90,19 @@ tree similar to this: * Requirements ** Software -- MS-DOS 6.22, with HIMEM.SYS loaded. -- Mouse driver if you have a mouse. -- Does work only when CPU is in real mode. -- To recompile ASM sources I used FASM (Flat Assembler). -- I ran QBasic utilities on QB 4.5 . -- VESA support by BIOS, or external driver (UNIVBE). +- MS-DOS 6.22 with HIMEM.SYS loaded. +- Mouse driver (optional, if you have a mouse). +- CPU is initialized into [[https://en.wikipedia.org/wiki/Unreal_mode][Unreal Mode]] during operation. +- To recompile ASM sources, you can use FASM (Flat Assembler). +- To run Quick Basic utilities, use Microsoft Quick Basic 4.5. +- VESA support through BIOS or external driver (UNIVBE). + ** Hardware -- Minimum CPU 386. -- 64 KB free RAM below 640KB, -- 2 MB of free XMS. -- VESA compatible video card. -** Human -- Beginner level Forth knowledge is recommended. -- Lots of enthusiasm. +- A minimum of a i386 CPU. +- 64 KB of free RAM below 640KB. +- 2 MB of free [[https://en.wikipedia.org/wiki/Extended_memory][extended memory]]. +- A VESA-compatible video card. + * Numbers representation within Fifth Because we are in full experimentation mode here (no regard for diff --git a/doc/language.html b/doc/language.html index b6c120c..ef8f0eb 100644 --- a/doc/language.html +++ b/doc/language.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + Fifth - language @@ -223,29 +223,31 @@

    Table of Contents

    + - -
    -

    1. Fifth source format

    +
    +

    1. Fifth source format

    Fifth uses a different character table and codes than ASCII (still @@ -256,8 +258,8 @@ numeric values. So typical nemric characters "0123…" is treated like ordinary letters.

    -
    -

    1.1. FSCII

    +
    +

    1.1. FSCII

    @@ -317,12 +319,12 @@ like ordinary letters. -
    -

    2. Fifth commands

    +
    +

    2. Fifth commands

    -
    -

    2.1. Compilation & miscellaneous

    +
    +

    2.1. Compilation & miscellaneous

    init module ( – )
    @@ -490,8 +492,8 @@ ne ( entrydata entrytype – ) Compile new dictionary entry.

    -
    -

    2.2. Conditionals & control flow

    +
    +

    2.2. Conditionals & control flow

    if ( flag – ) (immideate)
    @@ -533,8 +535,8 @@ done ( – ) exit from "until .. loop"

    -
    -

    2.3. Disk & file access

    +
    +

    2.3. Disk & file access

    diskload ( FromDisk ToMem amount – )
    @@ -593,8 +595,8 @@ fsDloadnew ( DynStr<SrcFileName> – DynHand<DataDest> )

    -
    -

    2.4. Dynamic memory

    +
    +

    2.4. Dynamic memory

    dynal ( size – handle )
    @@ -637,8 +639,8 @@ dyn. ( handle – )

    -
    -

    2.5. Graphics and text

    +
    +

    2.5. Graphics and text

    . ( n – ) print number on screen
    @@ -709,8 +711,8 @@ copyscreen ( SrcImgHandle DestImgHandle – ) copy contenc of source

    -
    -

    2.6. Math, memory & stack manipulation

    +
    +

    2.6. Math, memory & stack manipulation

    off ( n – ) writes 0 to given address, good for zeroing variable.
    @@ -773,8 +775,8 @@ abs ( n – |n| )

    -
    -

    2.7. Dynamic & static strings

    +
    +

    2.7. Dynamic & static strings

    Fifth supports both static and dynamic strings. Static strings must @@ -912,7 +914,7 @@ ex: var mystring1

    Author: Svjatoslav Agejenko

    -

    Created: 2023-09-18 Mon 01:47

    +

    Created: 2023-09-19 Tue 18:07

    Validate

    diff --git a/doc/language.org b/doc/language.org index 4d7a07a..d64d0f6 100644 --- a/doc/language.org +++ b/doc/language.org @@ -6,6 +6,7 @@ #+AUTHOR: Svjatoslav Agejenko #+LANGUAGE: en +- [[file:5TH_ET.txt][Example Fifth source file - text editor]] * Fifth source format Fifth uses a different character table and codes than ASCII (still -- 2.20.1