begin work on the proper manual

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.