From 3d9ed68493e193d19c47b9cdbae946f2f46f876d Mon Sep 17 00:00:00 2001
From: rich <rich>
Date: Sat, 8 Sep 2007 16:03:33 +0000
Subject: [PATCH] Finished documentation

---
 jonesforth.S | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 58 insertions(+), 6 deletions(-)

diff --git a/jonesforth.S b/jonesforth.S
index 2fb8515..710bf28 100644
--- a/jonesforth.S
+++ b/jonesforth.S
@@ -107,6 +107,14 @@
 	strings (or rather it used to, but the developers removed it!) so I've abused the syntax
 	slightly to make things readable.  Ignore these warnings.
 
+	If you want to run your own FORTH programs you can do:
+
+	./jonesforth < myprog.f
+
+	If you want to load your own FORTH code and then continue reading user commands, you can do:
+
+	cat myfunctions.f - | ./jonesforth
+
 	ASSEMBLER ----------------------------------------------------------------------
 
 	(You can just skip to the next section -- you don't need to be able to read assembler to
@@ -1660,6 +1668,8 @@ _HIDDEN:
 	NEXT
 
 /*
+	PRINTING STRINGS ----------------------------------------------------------------------
+
 	LITSTRING and EMITSTRING are primitives used to implement the ." operator (which is
 	written in FORTH).  See the definition of that operator below.
 */
@@ -1677,12 +1687,18 @@ _HIDDEN:
 	mov $1,%ebx		// 1st param: stdout
 	pop %ecx		// 2nd param: address of string
 	pop %edx		// 3rd param: length of string
-
 	mov $__NR_write,%eax	// write syscall
 	int $0x80
-
 	NEXT
 
+/*
+	COLD START AND INTERPRETER ----------------------------------------------------------------------
+
+	COLD is the first FORTH function called, almost immediately after the FORTH system "boots".
+
+	INTERPRETER is the FORTH interpreter ("toploop", "toplevel" or REPL might be a more accurate
+	description).
+*/
 
 
 	// COLD must not return (ie. must not call EXIT).
@@ -1756,6 +1772,15 @@ _HIDDEN:
 interpret_is_lit:
 	.int 0			// Flag used to record if reading a literal
 
+/*
+	ODDS AND ENDS ----------------------------------------------------------------------
+
+	CHAR puts the ASCII code of the first character of the following word on the stack.  For example
+	CHAR A puts 65 on the stack.
+
+	SYSEXIT pops the status off the stack and exits the process (using Linux exit syscall).
+*/
+
 	defcode "CHAR",4,,CHAR
 	call _WORD		// Returns %ecx = length, %edi = pointer to word.
 	xor %eax,%eax
@@ -1769,13 +1794,38 @@ interpret_is_lit:
 	mov $__NR_exit,%eax
 	int $0x80
 
-/*----------------------------------------------------------------------
- * Input buffer & initial input.
- */
+/*
+	START OF FORTH CODE ----------------------------------------------------------------------
+
+	We've now reached the stage where the FORTH system is running and self-hosting.  All further
+	words can be written as FORTH itself, including words like IF, THEN, .", etc which in most
+	languages would be considered rather fundamental.
+
+	As a kind of trick, I prefill the input buffer with the initial FORTH code.  Once this code
+	has run (when we get to the "OK" prompt), this input buffer is reused for reading user input.
+
+	Some notes about the code:
+
+	\ (backslash) is the FORTH way to start a comment which goes up to the next newline.  However
+	because this is a C-style string, I have to escape the backslash, which is why they appear as
+	\\ comment.
+
+	Similarly, any backslashes in the code are doubled, and " becomes \" (eg. the definition of ."
+	is written as : .\" ... ;)
+
+	I use indenting to show structure.  The amount of whitespace has no meaning to FORTH however
+	except that you must use at least one whitespace character between words, and words themselves
+	cannot contain whitespace.
+
+	FORTH is case-sensitive.  Use capslock!
+
+	Enjoy!
+*/
+
 	.data
 	.align 4096
 buffer:
-	// XXX gives 'Warning: unterminated string; newline inserted' messages which you can ignore
+	// Multi-line constant gives 'Warning: unterminated string; newline inserted' messages which you can ignore
 	.ascii "\
 \\ Define some character constants
 : '\\n'   10 ;
@@ -2004,3 +2054,5 @@ currkey:
 	.int buffer
 bufftop:
 	.int _initbufftop
+
+/* END OF jonesforth.S */
-- 
1.8.3.1