konilo-documentation/manual/konilo-manual.md

# Konilo Manual

```
There is significant interest in a more traditional manual, so
this will (eventually) contain it. Expect it to be raw and very
unfinished at this point.

Document Format:

I'm going to be using a Markdown-like format for this, but it's
not strictly Markdown. Tooling to create various formats from it
will be implemented as part of the process.

Questions / Topics

- what is konilo
- relationship between konilo & retroforth
- ilo computer
- introduction to forth
  - stacks
  - words
  - dictionary
  - sigils
  - combinators
- konilo applications
  - block editors
    - basic editor
    - tuhi
    - rem
  - catalogue
  - manual
  - kohure
  - wisp
  - wiki
  - ripanga
- konilo frameworks
  - termina
  - kaute
  - graphica
- techniques
  - assembly programming
- host-specific things
  - x86-native
  - teensy
- basic interactions
  - installation
  - starting konilo
  - exiting konilo
  - listener
```

# Introducing Konilo

Konilo is a small, pragmatic personal computing system written
in Forth and running on a tiny virtual computer.

It's not something intended to be widely used. It's a deeply
personal system; I publish it in hopes that others may find it
useful, but making a system that appeals to a broad audience is
not my goal.

Konilo is a small system. A barebones system is just over 2.5k
memory cells, and provides a functional Forth environment
including the compiler, block editor, and interactive listener.
A fully extended system, with an expanded vocabulary of words
and several additional applications is under 10k.

Forth is at the heart of Konilo. It's not a conventional choice,
but over the last few decades I've become very comfortable with
it, and, in setting out to create a personal computing system,
have found it to work well. My Forth is not a traditional model.
I use a very minimal dictionary, and make extensive use of both
sigils and quotations, leading to an implementation that feels
quite different from classical Forth systems.

The entire system runs on a virtual computer. This is a path I
started for portability reasons, and one that I've found quite
practical. Through the use of a virtual computer, Konilo has
been demonstrated to run on hosts from the late 1980's through
modern machines.

# Konilo and RetroForth

Konilo is similar in many respects to RetroForth. Both derive
from classical Forth, adding in sigils, quotations, and use of
combinators for logic and flow control. Both have similar core
vocabularies, and (in general) it's easy to write programs which
work on both.

But Konilo has some important changes. From a language viewpoint
the major three are a much more limited dictionary structure, a
removal of word classes, and a completely different model for
strings.

RetroForth tracks a lot of data for each defined word. Konilo
does not. A comparison of the structure:

    RetroForth     Konilo
    ----------     ----------
    d:link         d:link
    d:xt           d:address
    d:class        d:hash
    d:source
    d:hash
    d:name

Note that Konilo lacks the d:class, d:source, and d:name fields.

Word classes are removed. In RetroForth, the contents of the
d:xt field are placed on the stack, and a word class handler
function is called during interpret or compilation. In Konilo,
the system handles two cases (normal vs immediate), with all
other functionality handled by the sigils.

The other big change is strings. In RetroForth strings are null
terminated sequences of characters. This is perhaps less than
ideal for a variety of reasons, but keeps compatibility with
previous generations of the system. Konilo, being a completely
fresh start, changes this, so that strings are character arrays.

# ilo computer

ilo is the virtual computer Konilo runs on. It implements a
misc-style stack processor, 64k cells of memory, and several
i/o devices. Implementations are small (between 100-500 lines
of source is typical) and easy to write (most implementations
have taken only a few hours to write & debug).

# frameworks: termina

Termina is the basic scaffold for many of the programs in
Konilo.

# frameworks: graphica

# frameworks: kaute

Kaute is a new scaffold for creating simple spreadsheet-like
programs.