From 9b05c5dd5ad6c33960547ecad784482bdc749460 Mon Sep 17 00:00:00 2001 From: crc Date: Tue, 28 May 2024 20:38:05 +0200 Subject: [PATCH] begin work on the proper manual --- manual/konilo-manual.md | 137 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) diff --git a/manual/konilo-manual.md b/manual/konilo-manual.md index c7d8279..6b0345a 100644 --- a/manual/konilo-manual.md +++ b/manual/konilo-manual.md @@ -1,2 +1,139 @@ # 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.