RetroForth 6.20                                       http://www.retroforth.org
-------------------------------------------------------------------------------
Welcome to RetroForth 6.20!

This is the Release 6, Revision 20. It brings a number of new, useful additions
to RetroForth. There are no known problems with the Forth core at this time.
-------------------------------------------------------------------------------


Section 1: What's New
-------------------------------------------------------------------------------
Release 6.20 is the most significant update to RetroForth in nearly a year. It
brings a cross-assembler Forth core (for NASM and FASM), minor improvements
to the existing ports, and a port to Windows(TM) in addition to numerous new
words. A general cleanup and reorganization has also taken place.

The biggest news is support for FASM. Thanks to Ron Aaron, we now have two
new ports (fasm-linux-console and fasm-windows-console) which are written
using FASM and I've used his version of the Forth core to create a single
core which works seamlessly under both NASM and FASM. The Windows port is
especially nice since it makes RetroForth truely cross-platform. Many thanks
to Ron for all his hard work in helping to make this work.

You'll also notice a new assembler, again based on code by Ron. This is 
simpler and cleaner than the previous one. A number of minor bugs were fixed
in this release as well. Numerous CR/LF dependencies were resolved, so future
ports should be easier.

One often requested change has also been made. We now use 'make' to build the 
Forth images, so there is no need for the older, buggy build scripts anymore.
It is expected that this will also solve most of the distro-specific problems
associated with building RetroForth.


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

     bash# tar xzf retroforth-6.20.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 hope you like this release. It's been a lot of fun to develop it and
I'm quite pleased with the results. There are still quite a few places
that we can improve, but overall it's a lot better than any previous
release.

I will continue to extend the Forth core with more standard words and
update the ports. The Makefiles could use improvement. Merging of them,
cleaner output, and better organization are all due for them in next
few months.

SEDForth will be merged back into the RetroForth source tree as forth2asm
before February ends. It's due for a significant update as well so
keep an eye on it.

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.


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
