Welcome to RetroForth 6.20! This is a special preview
release. While it is working, there are problems with it,
so don't be suprised if something that was working in a
previous release is missing in this one.
----------------------------------------------------------


Building
----------------------------------------------------------
1) Start by decompressing the tar+gz archive
2) Enter a console or xterm and enter the main directory
3) Run './build NAME-OF-PORT'
   a. native
   b. linux-console
   c. linux-svga
4) Enter the ports directory, select the subdirectory
   containing the port you built, and run './rf'
5) After editing the source, run the top level './clean'
   script to remove the temporary files.


Changes since 6.20-pre2
----------------------------------------------------------
[x] Added .S << >> or
[x] Added iol@ iol!
[x] Fixed PAD
[x] Added 'run' script
[x] Renamed i & o (Native port)
    i -> io@
    o -> io!
[x] Updated Native drivers to use the new assembler
[ ] Begin work on RetroForth Driver Interface
[x] Began work on easier C subroutine support
    [x] Add support for compiling and linking with a
        single .c file (which can #include others)
    [ ] Macros to call C subroutines
    [ ] Sample library: Subset of Tom's TUNES program
        [ ] Simple function: play a .wav file
            * Filename must be 'a.wav' *
        [ ] Forth wrapper function
    [ ] Test under Linux
[ ] PCI access for Native/x86 (optional, GPL'd code!)
    [x] Based on code from OpenBIOS
    [x] Requires the following:
        [x] <<
        [x] >>
        [x] or
        [x] iol!
        [x] ioc@ (try to use io@ instead)
    [ ] Test on real hardware
----------------------------------------------------------
The RetroForth Driver Interface is a set of words to help
in the development of drivers for the Native/x86 port. In
general, I want this to be a framework, a support library;
not a driver manager. The Driver Interface should cover
essential tasks (port I/O, hardware bus, interrupts, etc)
but not enforce anything.
----------------------------------------------------------


New 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
----------------------------------------------------------
The Native/x86 port also has a few files that pertain to
booting:
raw.asm        Raw floppy bootloader
----------------------------------------------------------
Each version is saved into a subdirectory under
retroforth/ports. 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.
----------------------------------------------------------


Detailed TODO List
----------------------------------------------------------
[ ] C Subroutine macros
[ ] Cleanup drivers for core ports
[ ] Build a working library of code (in retroforth/lib)
    * In Progress *
[ ] Write Manual (see http://retro.tunes.org)
    [x] Introduction
    [x] Obtaining, Building, Invoking the Image
    [ ] Introduction to Forth
        [ ] Terminology
        [ ] Reverse Polish Notation
        [ ] Simple programs
    [ ] Developing Applications
        [ ] With the RF interpreter
        [ ] Using Forth2ASM and the User Extension System
        [ ] Using SEDForth to create native applications
        [ ] Using the RF/Libary
    [ ] Complete Wordlist
        [ ] Descriptions
        [ ] Stack comments
        [ ] Examples
----------------------------------------------------------
I really want to finish the manual. It won't be very long,
but should cover all of the essential aspects of RetroForth.
The tutorial will be brief, just enough to explain the
basics of Forth (terminology, RPN, definitions). As a
whole I don't want a lengthy, verbose manual. A good,
complete wordlist, with stack comments, descriptions, and
a few samples would be all most Forth programmers need to
master RF. A small glimpse into the inner design might be
nice as well.
----------------------------------------------------------
I'll also host the manual on http://www.forthfreak.de if
possible.
----------------------------------------------------------


Native/x86 Port - Sample Implementation
----------------------------------------------------------
[ ] Port the CARDS + DDR environment from RETRO5
    [ ] Port to Linux as well (needs file I/O)
[ ] Hardware driver improvements
    [x] PCI Bus access (borrow from OpenBIOS) * Not Tested *
    [ ] Better CMOS driver
        [ ] Realtime clock
        [ ] Hardware information
        [ ] Easier setting/obtaining of values
----------------------------------------------------------
I don't expect full scale drivers to result from this. It
would be nice to have at least limited access to the bus
and apic. APM/APCI would also be nice, but they're not
essential at this point.
----------------------------------------------------------
Cards was a block editor, with hotkey based menus, DDR
was a small debugger tool. I'd like to get them into a
more Forth oriented environment if possible. It'd be nice
to have a little, usable OS again.
----------------------------------------------------------
Usable? Well, I used RETRO5+Cards for notekeeping (it was
secure from casual browsers, since it saved notes in the
first cylinder of a hard drive), and DDR to help test
RF5 during debugging. For about four months (once it was
stable), until I started work on RETRO6, I had a copy
running nearly constantly on one of my computers. Oh,
the persistant data storage was nice too.
----------------------------------------------------------


Native/x86 Ideas
----------------------------------------------------------
[ ] Multiboot Compliant
[ ] Cleaner DOS startup / return to DOS code
[ ] Able to boot other OSes (at least chainloading)
[ ] Text mode output
[ ] Drivers
    [ ] Parallel Port
    [ ] Serial Port
    [x] PCI Bus  ** Not Tested **
    [ ] APIC (way off, we don't use interrupts atm)
    [ ] ACPI/APM
    [ ] Plug-N-Play driver model
    [ ] Hardware accelerated graphics
    [ ] Faster non-hardware accelerated graphics
    [ ] Sound cards
    [ ] Floppy drive
    [ ] Better Hard Drive support
    [ ] Winmodems
    [ ] CD-ROM
    [ ] USB
        [ ] Keyboard
        [ ] Flash Memory sticks
[ ] Boot from CD-ROM
----------------------------------------------------------
I don't expect to accomplish most of this on my own. If
others help, many are possible. Even so, just having the
ability to boot from a CD, and support serial and parallel
ports in addition to the hard drive would go a long way
towards making it into a usable OS for more people than me!
----------------------------------------------------------


Website Notes
----------------------------------------------------------
[x] New logo for RetroForth
[x] Return to a Wiki-based site
[x] "Support Development" Page
[ ] Restore retroforth.sf.net as a mirror
----------------------------------------------------------
I intend to restore the sf.net account as a backup mirror
in case anything happens to Bespin.org
----------------------------------------------------------


Beyond 6.20
----------------------------------------------------------
[ ] Backscroll
[ ] ELF Object Loader (for extensions)
[ ] Diagnostics
    [ ] If 'foo' isn't a word, print 'foo?' and ABORT
    [ ] ABORT   reset return stack; fall thru
    [ ] QUIT    reset data stack; JMP INTERPRET
    [ ] ABORT"  parse & print error message; JMP ABORT
    [ ] Memory Dump
        [ ] addr count DUMP, saves addr & count, displays <count> memory
        [ ] D continues where DUMP left off
        [ ] MEMVIEW interactive interface to DUMP
    [ ] SEE decompiler/disassembler
[x] Rename CALL, to EXECUTE (old standard)
[ ] Linux Console
    [ ] Setup terminal in "unbuffered mode"
    [ ] Signal handlers to reset terminal after a crash
    [ ] VT100 codes
    [ ] Use /dev/vcsa0 - see 'vcs' manpage
    [ ] Accept input from command line
    [ ] File I/O wordset
    [ ] Command line history/editing (could be a C add-on)
[ ] Linux SVGALIB / SDL
    [ ] Merge SETMODE and SETRES to search for a mode automatically
    [ ] Double or Triple buffer (improve scroll speed)
    [ ] Use a call table for redirection to accelerated graphics if
        they are supported
    [ ] Accept input from command line
    [ ] File I/O wordset
    [ ] Command line history/editing (could be a C add-on)
[ ] Linux / SDL
    [ ] New Maintainer
[ ] Translators (Source to Forth conversion)
    [ ] C (If this works, replace "Simple C" with it)
    [ ] BASIC
    [ ] Pascal
[ ] Ports
    [ ] MS Windows (Console)
    [ ] MS Windows (SDL)
    [ ] BeOS 5
    [ ] FreeBSD
    [ ] MenuetOS
[ ] Graphics Words (in Forth)
    [ ] Line
    [ ] Triangle
    [ ] Circle
    [ ] Ellipse
[ ] Audio Words (written in 'C', use code from TUNES)
    [ ] Play .wav
    [ ] Record .wav
    [ ] Text to speech
----------------------------------------------------------
The Diagnostics are high on the priority chart right now.
They would help move us to a real, useful development
model.
----------------------------------------------------------
Some of these features will make it into 6.20, I can't
say exactly which ones, but expect to see a few of the
easier ones merged in before I publicly release this
----------------------------------------------------------
The play/record .wav support library will be in 6.20
----------------------------------------------------------
I really want to find a new maintainer for the Linux/SDL
port. Since I no longer use X11 on my Linux box, I can't
really keep it well tested. I've been running blind on it
for a while, so a new maintainer with X11 + SDL would be
nice.
----------------------------------------------------------
The SDL port could be a good starting point for the BeOS
and Windows ports though. SDL supports those platforms,
so it should be just a little startup + linking to get it
working on those platforms.
----------------------------------------------------------
The translators subproject is pretty high on the priority
chart. I'd like at least limited ability to convert BASIC
and C code by the end of March. These translators would
go a long way towards making RF more usable by programmers.
----------------------------------------------------------
Line should be an angled line. We already have rect, which
can be used for hline, vline, and pixel drawing. We don't
have a way to draw slanted lines yet. There is a circle
implementation, but I'd like to simplify it a bit. Triangle
and ellipse are more luxeries than neccessities right now.
----------------------------------------------------------


Runtime Debugger - Notes
----------------------------------------------------------
I'm working on improving the set of words devoted to
debugging programs. With the addition of words like COLD,
ABORT, QUIT, and SEE; RF will soon be easier to program
for.
----------------------------------------------------------
--- In FORTH.F ---
here variable cold.h
0 variable cold.d
: cold cold.d @ last ! cold.h @ h ! ;
: save-state here cold.h ! d @ cold.d ! ;

--- At the end of DRIVERS.F ---
save-state
----------------------------------------------------------


New Words
----------------------------------------------------------
COLD  COLD.H  COLD.D  SAVE-STATE .S LAST
CELL-SIZE  CHAR-SIZE << >> or iol@ iol!
----------------------------------------------------------


Dropped or Moved Features
----------------------------------------------------------
SDL support
----------------------------------------------------------
This will be added back at a later time. For now, I want
to get the core functionality working and worry about
restoring this ports later. If someone else is willing to
update and/or maintain this port, contact me.
----------------------------------------------------------
I moved the block editor and looping examples into the
library.
----------------------------------------------------------
