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. 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
  E. ROT recoded in Forth
  F. EXECUTE recoded in Forth
IV. Removed words
  A. code[ and ]code dropped from assembler
V. Ports
  A. Dropped "native" mode, now a separate release



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'

     bash# cd retroforth
     bash# make

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 complete. 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 plan to add more traditional looping words in a future release.


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
