yForth? v0.2+beta - READ THIS (AND ONLY THIS) TO GET yForth? RUNNING.

0) Hello world!
Here's a little file which will help you having yForth? running in few
minutes on your system. 

1) What's yForth? ?
yForth? is a Forth environment written entirely in ANSI C, making it 
extremely portable. The first thing I want to tell you about yForth? is
that it seems a joke compared to other systems such as gForth or PFE.
The only things it has in common with PFE are that it's written in C, and
it's been written for fun.
It's rude, it hasn't anything odd, there's no reason to choose yForth? instead 
of other Forth environments. 
Nevertheless, you could find yForth? nice, in this case you're invited to 
explore yForth? in the following lines. 
yForth? is based on the draft of ANS Forth, but it's NOT complete. 
The reason is very simple: not all the words included in ANS Forth can be 
written using only ANSI C. In particular, those words which interact with 
system hardware almost directly, such as words which control the terminal, 
can't be written using solely ANSI C (and related libraries).
In fact, you'll find that all the device dependent routines are grouped
together in the file "udio.c". If you're using Turbo C, Borland C, or any
compiler which supplies the "conio.h", you can define HAVE_CONIO in 
your "config.h" file and go. 

2) Where does the name yForth? came from?
I've been charmed by Forth since the first time I "played" with it, but 
I've never been able to find some book (here in Italy, obviously) to learn it. 
When I've put my hands on the draft of ANS Forth I thought that 
the best way to learn it was to write an environment. I was wondering what
features made Forth so popular. I asked myself: Why Forth?

3) How do I compile yForth? for my system?
It's simple. First of all you'll have to modify "config.h" accordingly with
your system AND compiler requirements. In order:
- modules
You can exclude some modules to make a smaller environment, but keep
in mind that all the modules will be compiled anyway. You must rely on
your compiler "smart-linking" to cut off unused functions.
- big/little endian
Define LITTLE_ENDIAN if your machine "is" little-endian (e.g. Intel), 
undefine it if it's big-endian (e.g. Motorola, SPARC).
- double-cell transfer
You can choose two ways for moving a DCell data from data stack to C internal
variables. If DCELL_MEM is defined moving is performed via memory copy,
if it's undefined moving is performed via shift operators (<< and >>).
- data types
The most important thing is choosing what C types will identify Cells and
Double Cells in yForth?. Be sure that 2 * sizeof(Cell) == sizeof(DCell).
Note that using GCC makes this things trivial, since it has a "long long"
type which allows having 32bit Cells. Using Turbo C that's not possible.
Below data definition you'll have to change the maximum values of your
system. See "limits.h".
- terminal
Finally, define HAVE_CONIO to 1 if you're using Turbo C, Borland C or GCC 
for DOS. You'll have some nice words such as "page"...
- special functions
"asinh", "acosh", "atanh" aren't provided by all the libraries, if you don't
have them reset the definitions at the end of "config.h".

The second thing to do now is configuring the "Makefile". At the moment 
"Makefile" is ready for GCC (under Linux), it's simple and you won't find any 
problem modifying it.

Third, type "make all". Yes, that's all.

4) I have yForth? running, and now?
It's your, you can make anything you want with. If you want an explanation
of the words provided by yForth? please refer to the draft of ANS Forth or
something equivalent. The Net will help you.
Do not expect the prompt "ok" to come up when you run yForth?, the standard
says that "ok" shall be printed AFTER every succesful command execution...

5) What about yForth? in 1997?
Well, I think yForth? will be available since January 1997, and at the moment
I've no idea of some future developlment. I've learned a lot writing it, both
Forth and C, but I can't say I've learned programming in Forth.
Ideas come and go, now they're all gone. But don't despair, if you have some
fantastic intuition you want to share, email me, I'll listen to you!
Furthermore, this package is still incomplete. The source code can be better
organized, more documentation could be written, and so on. If you want to
work on it, you can, and I'd be happy to work together to make some improvement.

6) Hey, just a moment!
Don't forget:
	- yForth? is a "beta" release, I think it has bugs, but, most 
		important, I'm afraid that some words don't behave as the
		standard says they have to.
	- yForth? is NOT a complete ANS Forth.
	- yForth? is written in ANSI C. Ok, you could see some warning while
		compiling it, and I've to check it with lint, but it 
		doesn't make use of any capability other than those provided
		by the standard (well, "long long" doesn't belong to the
		standard, but you're anxious to work whit 32bit Cells,
		aren't you?).
	- yForth? comes with it's nice logo (yforthlogo.gif).
	- yForth? comes with some word not included in ANS Forth. The most
		useful ones are those you find in "ycore.c". Each comes with
		a short description just before its implementation.
	- yForth? may not support "page" on systems where "conio.h" is unknown.
		Since I love clearing screens, here's a little tip, define:
		: page s" clear" system drop ;
		And you'll have "page" working on your Unix system.

7) Please report bugs
I'll be very happy if you report me some bug. Obviously I'll be happy even
more if you tell me how fo fix it, but I can't pretend so much, even 'cause
my C is not very readable (few comments...).

email: lpadovan@cs.unibo.it

Enjoy yForth?

**********************************************************************
                             CONTRIBUTORS 
**********************************************************************