RetroForth 6.21                                       http://www.retroforth.org
-------------------------------------------------------------------------------


Section 1: What's New
-------------------------------------------------------------------------------
This release adds a number of useful new features and fixes some of the minor
irritants that are known to exist. A detailed list follows.

I. Build system changes
  A. fasm- prefix dropped in ports tree
  B. linux-console now uses FASM only
  C. NASM ports now remove 'retro.o' after linking
II. Bugfixes
  A. Echoing of input in *-console ports eliminated
  B. 'drop' now checks the stack depth before proceeding
III. New or Changed words
  A. Support for simple loops
  B. Real return stack
  C. New 'inline' macro for use in compiled words
  D. 'bytes' recoded in Forth
IV. Removed words
  A. code[ and ]code dropped from assembler



Section 2: Building the images
-------------------------------------------------------------------------------
As normal, gunzip and detar the source package.

     bash# tar xzf retroforth-6.21.tar.gz

Then enter the directory and type 'make -k'

     bash# cd retroforth
     bash# make -k

Then cleanup:

     bash# make clean


Section 3: Notes, comments, bugs
-------------------------------------------------------------------------------
I *know* there is a problem with the color names under SDL. This is being
worked on and should be resolved in the near future.

The looping constructs are not standard or 100% finished. For now you
can use them by doing something like:

: bytes times c, repeat bytes ;
<count> bytes

This makes use of recursion (hence the 'bytes' at the end of the
definition). 'times' will exit the word when the count reaches zero. 'repeat'
decrements the count. I will clean it up a bit and also provide more 
flexible loops later on.


Section 4: File Organization
-------------------------------------------------------------------------------
retro.asm      Main file, includes all others
macros         Macros for internal use (dictionary, stack)
forth.asm      Forth dictionary + primitives
forth-ic.asm   Forth Interpreter/Compiler
forth.f        High-level Forth words
drivers.asm    Platform specific drivers, assembly
drivers.f      Platform specific drivers, Forth
user.asm       User extensions, assembly
user.f         User extensions, Forth
----------------------------------------------------------
Each version is saved into a subdirectory under
retroforth/ports. The forth* files are stored one level
above this (../) and can be used with either NASM or FASM.
----------------------------------------------------------
If you are editing RETRO.ASM, make sure that the files are
included in this order:

1) ../forth-ic.asm
2) drivers.asm
3) user.asm
4) ../forth.asm

And don't forget to INCBIN the following in this order:

1) ../forth.f
2) drivers.f
3) user.f
----------------------------------------------------------


Section 5: Register Usage
-------------------------------------------------------------------------------
EAX	TOS			|
EBX				|
ECX				|
EDX				|
ESI	Pointer to TOS		| Initally set to sp0
EDI				|
ESP	Return Stack		|
EBP				|


Section 6: Dictionary Structure
-------------------------------------------------------------------------------
c: dd link_to_previous_word
   dd pointer_to_cfa
   db length_of_name
   db "name"
b: ... assembly code ...
   ret

c: dd link_to_previous_word
   dd pointer_to_cfa
   db length_of_name
   db "name"
b: ... assembly code ...
   ret
