X-Git-Url: http://git.annexia.org/?a=blobdiff_plain;f=jonesforth.S;fp=jonesforth.S;h=681f9a89fcb319f1292ffbef962d7db9c4283c96;hb=194e3f36f539ff90540bfb780cfbd424d7f6aaec;hp=3409cb8232c80881f8b5ffabead0099a610f59e9;hpb=a2e824fd9d9b81d143db5e670bf8fcad4a78bb4d;p=jonesforth.git

diff --git a/jonesforth.S b/jonesforth.S
index 3409cb8..681f9a8 100644
--- a/jonesforth.S
+++ b/jonesforth.S
@@ -1,7 +1,7 @@
 /*	A sometimes minimal FORTH compiler and tutorial for Linux / i386 systems. -*- asm -*-
 	By Richard W.M. Jones <rich@annexia.org> http://annexia.org/forth
 	This is PUBLIC DOMAIN (see public domain release statement below).
-	$Id: jonesforth.S,v 1.32 2007-09-26 22:20:52 rich Exp $
+	$Id: jonesforth.S,v 1.33 2007-09-26 22:47:49 rich Exp $
 
 	gcc -m32 -nostdlib -static -Wl,-Ttext,0 -o jonesforth jonesforth.S
 */
@@ -45,7 +45,8 @@
 	over every other element in a list of numbers?  You can add it to the language.  What
 	about an operator which pulls in variables directly from a configuration file and makes
 	them available as FORTH variables?  Or how about adding Makefile-like dependencies to
-	the language?  No problem in FORTH.  This concept isn't common in programming languages,
+	the language?  No problem in FORTH.  How about modifying the FORTH compiler to allow
+	complex inlining strategies -- simple.  This concept isn't common in programming languages,
 	but it has a name (in fact two names): "macros" (by which I mean LISP-style macros, not
 	the lame C preprocessor) and "domain specific languages" (DSLs).
 
@@ -74,8 +75,14 @@
 	This code draws heavily on the design of LINA FORTH (http://home.hccnet.nl/a.w.m.van.der.horst/lina.html)
 	by Albert van der Horst.  Any similarities in the code are probably not accidental.
 
-	Also I used this document (http://ftp.funet.fi/pub/doc/IOCCC/1992/buzzard.2.design) which really
-	defies easy explanation.
+	Some parts of this FORTH are also based on this IOCCC entry from 1992:
+	http://ftp.funet.fi/pub/doc/IOCCC/1992/buzzard.2.design.
+	I was very proud when Sean Barrett, the original author of the IOCCC entry, commented in the LtU thread
+	http://lambda-the-ultimate.org/node/2452#comment-36818 about this FORTH.
+
+	And finally I'd like to acknowledge the (possibly forgotten?) authors of ARTIC FORTH because their
+	original program which I still have on original cassette tape kept nagging away at me all these years.
+	http://en.wikipedia.org/wiki/Artic_Software
 
 	PUBLIC DOMAIN ----------------------------------------------------------------------
 
@@ -600,7 +607,7 @@ bufftop:
 /*
 	BUILT-IN WORDS ----------------------------------------------------------------------
 
-	Remember our dictionary entries (headers).  Let's bring those together with the codeword
+	Remember our dictionary entries (headers)?  Let's bring those together with the codeword
 	and data words to see how : DOUBLE DUP + ; really looks in memory.
 
 	  pointer to previous word
@@ -784,8 +791,8 @@ code_\label :			// assembler code follows
 	NEXT
 
 /*
-	In this FORTH, only /MOD is primitive.  We define the / and MOD words in
-	terms of /MOD.
+	In this FORTH, only /MOD is primitive.  Later we will define the / and MOD words in
+	terms of the primitive /MOD.
 */
 
 	defcode "/MOD",4,,DIVMOD
@@ -875,7 +882,7 @@ code_\label :			// assembler code follows
 1:	pushl $1
 	NEXT
 
-	defcode "0<",2,,ZLT
+	defcode "0<",2,,ZLT	// comparisons with 0
 	pop %eax
 	test %eax,%eax
 	jl 1f
@@ -911,22 +918,22 @@ code_\label :			// assembler code follows
 1:	pushl $1
 	NEXT
 
-	defcode "AND",3,,AND
+	defcode "AND",3,,AND	// bitwise AND
 	pop %eax
 	andl %eax,(%esp)
 	NEXT
 
-	defcode "OR",2,,OR
+	defcode "OR",2,,OR	// bitwise OR
 	pop %eax
 	orl %eax,(%esp)
 	NEXT
 
-	defcode "XOR",3,,XOR
+	defcode "XOR",3,,XOR	// bitwise XOR
 	pop %eax
 	xorl %eax,(%esp)
 	NEXT
 
-	defcode "INVERT",6,,INVERT // this is the FORTH bitwise "NOT" function
+	defcode "INVERT",6,,INVERT // this is the FORTH bitwise "NOT" function (cf. NEGATE)
 	notl (%esp)
 	NEXT
 
@@ -975,7 +982,7 @@ code_\label :			// assembler code follows
 						   | addr of EXIT     |
 						   +------------------+
 
-	And NEXT just completes the job by, well in this case just by calling DOUBLE again :-)
+	And NEXT just completes the job by, well, in this case just by calling DOUBLE again :-)
 
 	LITERALS ----------------------------------------------------------------------
 
@@ -1043,10 +1050,13 @@ code_\label :			// assembler code follows
 	subl %eax,(%ebx)	// add it
 	NEXT
 
-/* ! and @ (STORE and FETCH) store 32-bit words.  It's also useful to be able to read and write bytes.
- * Byte-oriented operations only work on architectures which permit them (i386 is one of those).
- * UPDATE: writing a byte to the dictionary pointer is called C, (CCOMMA) in FORTH.
+/*
+	! and @ (STORE and FETCH) store 32-bit words.  It's also useful to be able to read and write bytes
+	so we also define standard words C@ and C!.
+
+	Byte-oriented operations only work on architectures which permit them (i386 is one of those).
  */
+
 	defcode "C!",2,,STOREBYTE
 	pop %ebx		// address to store at
 	pop %eax		// data to store there
@@ -1120,7 +1130,7 @@ var_\name :
 	DOCOL		Pointer to DOCOL.
 	F_IMMED		The IMMEDIATE flag's actual value.
 	F_HIDDEN	The HIDDEN flag's actual value.
-	F_LENMASK	The length mask.
+	F_LENMASK	The length mask in the flags/len byte.
 */
 
 	.macro defconst name, namelen, flags=0, label, value