RetroForth 6.20                                          http://retro.tunes.org
-------------------------------------------------------------------------------
Welcome to RetroForth 6.20!

This is the latest revision and brings a number of new, useful additions to
RetroForth. Please be aware that this is a beta release and may still
contain bugs.
-------------------------------------------------------------------------------


Section 1: What's New
-------------------------------------------------------------------------------
Release 6.20 adds many more common words to the Forth core. This release
is far cleaner than the last few. The interpreter/compiler, primitives,
and high-level extensions have been cleaned up and reorganized to make it
easier to work with.

Thanks to Ron Aaron (http://ronware.gotdns.com), there is now an experimental
version for users of FASM. Other than minor syntax differences in the macros
and local labels, it is identical to the existing NASM version. This makes
switching assemblers far easier than a complete overhaul. Also new is the
start of a Windows version (which requires FASM at the moment).

Since 6.20-pre3 I've scrapped the build scripts. RetroForth now uses a Makefile
so there should be fewer distro-specific problems in the future. There are
plenty of comments in the makefile, so adding new ports shouldn't be a problem.



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

   bash# tar xzf retroforth-6.20-beta.tar.gz

Then enter the directory and type 'make'

   bash# cd retroforth
   bash# make

After a short time, each of the ports will be built. Please be aware that
the makefile uses NASM by default, so if you want to use FASM, you'll
need to make a few easy changes. I haven't finished integrating the 'clean'
script code into the makefile yet, so the 'clean' script remains for now.



Section 3: Notes, comments, bugs
-------------------------------------------------------------------------------
There are a number of known issues with the SDL port.
 * Color names -> actual colors are not accurate yet
 * The makefile is dependent on libSDL being at:
   /usr/lib/libSDL-1.2.so.0
 * Native mode is NOT present in the makefile yet

The following words have been added:
   ?negate ?dup >body body> defined >type .( /string

In the SVGALIB/SDL drivers you can now address the following colors by name:
   Black, white, red, blue, green, yellow, purple


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-nasm. There are no shared files or nested
ports, unlike previous versions.
----------------------------------------------------------
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

As of 12/31/03, including them in any other order will
result in a segfault / triple fault when the resulting
image is invoked.
----------------------------------------------------------
