We do need a README file, don't we?

diff --git a/README.TEXT b/README.TEXT
new file mode 100644 (file)
index 0000000..6d364ec
--- /dev/null
+++ b/README.TEXT
@@ -0,0 +1,38 @@
+I think the current branch is auto-hand-optimized.
+
+I currently think the path I took to get here was sort of as follows:
+
+1: hand-translated
+(fig-forth_6809.asm -- an attempt to simply re-write with help)
+
+2: search-and-replace
+(fig6800to6809dumb.asm -- a least-work attempt, probably automatic)
+(socialize6809.pl -- a script to convert to more modern syntax)
+
+3: auto
+(6800to6809.pl -- incomplete automatic translation script)
+(figd6809.dsk -- color computer disk image used in testing and debugging)
+
+4: auto-hand-optimized-offline -- see NEXT loop for clues
+(fig-forth-auto6809.asm -- script output)
+(fig-forth-auto6809halfopt.asm -- replacing sequences with single instructions)
+(fig-forth-auto6809opt.asm -- native registers in use, parameter stack is U)
+
+5: auto-hand-optimized-detour (lopped branch)
+(figao.asm -- Trying to mix explicit inner loop with subroutine inner loop.)
+
+6: auto-hand-optimized (current, JMP and JSR proceeding in parallel, in suspended animation)
+fig-forth-auto6809.asm -> fig-forth-6809_jmp.asm -- Explicit NEXT loop, requires JMP/LBRA to NEXT
+fig-forth-auto6809opt.asm -> fig-forth-6809_ret -- subroutine NEXT, RET comes back to NEXT
+
+The files from the first three steps don't seem to be in my junkpiles. The files here are actually what existed about steps 3 to 5.
+
+master has not yet been merged with the current branch, in no small part because I kept getting interrupted in the processes and am not complete confident what happened when.
+
+The source files of most interest are fig-forth-6809_jmp.asm and fig-forth-6809_ret.asm.
+
+fig-forth-auto6809.asm was renamed fig-forth-6809_jmp.asm, because definitions return to the inner interpreter via JMP NEXT (or BRA/LBRA NEXT).
+
+fig-forth-auto6809opt.asm was renamed fig-forth-6809_ret.asm, because defnitions return to the inner interpreter via the RET instruction, allowing some leaf definitions to operate as simple subroutines.
+
+Either is a (presently buggy) implementation of a fig Forth kernel, which should assemble to function on the TRS-80/Tandy Color Computer.