README.txt
for m5ness, version : 1. 5. 3
(major version 1, release 5, update 3)

(C)1999 Keinall "Granitor" Caddle

*** Important for Users: 
Read The Manual (nessuse.txt) First. 

Please. I spend time writing it to
make eveyone's life easier.
*** End of user stuff. Koders read on.

---]

What's new in m5ness?

Nothing much; mostly code cleanups... corrected a few
spelling errors, and i've continued working on
NASIC (as opposed to C-NASIC), but it's nowhere near
ready and I'm still trashing out some conflicting thoughts.

m1imp has been enhanced; it now supports comments; and
plenty of them. // comments ; / and ' as REM; /* comments */;
and also I added a new command to make use of the more
flexible getFasc...

m5ness now uses two seperate m1 type files,
MAUTORUN.TXT is loaded and run automatically;
then there's a pause (hit SPACE to continue);
then TESTIN.TXT is run.

Fun, ain't it? I wanted to add some more bells and whistles but
I decided not to; what I really want to do is get off of C-NASIC
and onto NASIC proper; this is fairly time consuming however,
and I've yet to properly prioritise everything.

I'm quite capable of it, but I haven't done it yet; largely because
I've been bitching about my monitor's erratic behaviour or window's
erratic behavior...

Also, Nelish has gone Nelish in a new way,
falling in love and saying "I have determined that computers give
me stress" before leaving IRC less.

In a way I agree, I still
don't like DOS; but I think Caldera's implemnetation is fairly
cool and it has been unobstructive once i got it configured...
I'm glad it's here to stand on while i build C99. Allegro and
DJGPP too.. these 3 (or 4, if you include MS-DOS) things are
just like floors to me, they're quite encessary but i don't spend that
much time staring at them and eithe rliking or disliking them...

The point (getting myself back on track here) is that I'm
still  working out the C99 roadmap. I have an idea but I haven't
verbalised, written coherently, typed, or HTML'd it yet.
I will do some or all of these eventually.
Perhaps whilst my monitor is in the shop.

---:
Where C99 is going:

I actually did a small C99 roadmap.
Immediately, though, they're csome things that I'd like to clean up
in the code (read implmentation details). Also, I'm designing
NASIC and I've already implemented the tokenization/detokenization
routines form this, but I've got to write a monitor type thingy
before I write the parser, or else I'll be coding in the dark.

I also have an overly complicated, but (I believe) worthwile way
of passing CLAs and stuff, when I do it i think there will be
pleanty rejoicing a while down the road when debugging problems in the
native (i.e. C) code is more important.

CLAs were fine for a mono-file thingy like m1 but they're not very
elegant for a more modular creature like m5 is.

---]
There are chickens in the trees...

Now, all fans of Seasame Street will immediately recognize this
reference to the short animation; but for those of you who do
not watch the great SS or fail to remember this for whatever 
reason, here's an approimation fo the story:

A misc. farmer-type guy plays a guitar in the vicinity of 
a large tree. He sings:-

There are chickens in the trees,
There are chickens in the trees,
Oh, won't you listen to me please?
They are chickens in the trees!

Along walks another man, and says:-

That's a very nice song,
but you've got it all wrong.
Chickens do NOT live in trees.

Subsequently, a flock (?) of chickens descends for the
tree, with much ado, and runs off merily...
except one, which picks at the ground before running along,
if memory serves correctly.

The 3000 series of SS is not as good as previously;
largely because there's less animation and instead 
a bunch of silly actors and poorly done computer animations.

Hand drawn animations kick ass;
as do scenes with muppets and no humans.

Humans suck, if I wanted to watch humans,
I wouldn't watch SS or any other Jim Henson production
in the first place.

---]
Liscence Rant

I don't intend to make money on C99 directly; It's something I do for fun;
like most emulator authors... except it's an imm and it's much less
feature rich as is. Plus it's built with free software (OpenDOS,
DJGPP, Allegro); so I'd have to have a heck of a good reason for
charging money for it. Besides, it's not much to look at now. It's not
even C99, it's m.

So, feel free to use it however you please, but take note that
I'm not providing any warranty, explicit nor implicit,
and I don't recomment you use it for anything that's highly important
as it's not even my "good" work, much less my best.

It's my testbed. It has loose parts all over the place, and will
break if you tug on them.

I don't anticipate a restrictive liscence (neither restriction freedom
downwards, as an ELUA for a commerical project, not restricting derivatives
to being free, as in GPL) anytime in the future; but I do reserve the
right to do so. 

Portions of code are based on concepts and/or code by Master Chip;

In particular the sprite loading code (which is yucky, I know),
and the startup screen, and Chip is actually quite inspirational,
without him, I doubt I would have made it this far... that would
be like playing Chess alone (which I know some ppl do, but I
personally do not...)

So, basically, m5ness is freeware; i doubt it's useful for any 
commercial applications; and, in fact, i expressly forbid its use therin;
it's Not Ready Yet.

Also, m5ness was built using DJGPP and Allegro, and should run on top
of any DOS32 platform that Allegro supports. Right now I don't
use the Allegro sound or input routines, so there's no need to run
have or run the Allegro Setup routine.

I initially starting developing on Windows 95, then plain DOS,
but I needed to edit Makefiles in a tab-preserving way, so I also
used emacs under Linux. Why just plain DOS? Windows broke in strange
and unusual ways and I didn't feel I could take the insanity of using
that crap anymore, so I left it broken rather than doing the old
reinstall thing and hoping that it worked.

Anyhow, I've switched to using OpenDOS (7.01 Lite), which is alot
faster than MS-DOS and has a cool edit.com with a GUI that preserves
TABs in makefiles. I am happy with this.

I mention all of these things because I use a lot of free software...
in fact, now, only free software, free in the sense that I didn't
pay for it (in the case of OpenDOS and DJGPP and Allegoro), or I didn't
have to (in the case of Linux). I appreciate this and, although I
have no means of income currently, don't see a reason to charge money
for anything i've coded, in fact, I'd been deeply ashamed to do so,
as they're not usueful to me as yet, much less anyone else. And also
the code varies in quality, as I'm still teaching myself C. Some of it
is quick and dirty, and difficult to maintain. As it's my personal
project, I don't mind this, but if anyone was gonna use it, I'd be
very concerned.


---:
Copyright acknowledgements and such stuff

m relies on a dump of the C64's Character Rom;
however, Commodore has been bankrupt for almost a decade now,
and so has any company which tried to bring it back.
Also, on corporate person really seemed to care about the
C64, even the C128 wasn't well supported. Commodore Business
Machines died a horrible death.

It's my personal opinion that it was the managers' faults,
they were not ready to stand agains Steve and Bill (of
Apple and Microsoft fame), or even IBM (I'm sure they're some
famous ppl at IBM, but I you really can't name one person who
represents IBM, they're just kool overall).

You don't really need the C64's CHAR.ROM, you can make
your own charset... I have more on GCR disks but no means
of speedily transferring them to my x86 box yet,
so.. it's all at you what you decide to do. I don't belive the
copyright is valid , due to CBM's bankruptness.

---]

Status of support libraries;
why all the source is not included.

rendlib.c is a bit messy now because it contains 4 ways
of doing sprites, only one of which is fully implemented
(i.e. works); the rest being abandoned as I realised the 
folly of my ways. I'll clean it up eventually.

screen.h just looks pretty, but screen.c does not.
It works but is a little bit messy... and inefficient.

I'll release both screen.c and rendlib.c when I'm happy with
them, right now they work but i'm slightly ashamed of them;
I'll eventually do them better, but i also want to implement
a K1 block and.. other stuff, so I'll do everything one time.

The object files are in the source release, in case you
wish to link against them, that's rather nice of me,
if i do say so mysef, so.. enjoy.

Parser.c is fairly clean, it relies on both rendlib
(for rendRefresh/rendRedraw) and screen (aka SMELL), 
and nothing else. (other than mdefcon.h, aka "Guiness"...)

st.c and st.h are based on SMELL.
but they're broken until further notice.
I'll fix them for inclusion in m5ness v2 r1.

---:

So, this is what I'll release:

All header files 
(which double as API documentation):
rendlib.h; screen.h; 
rendlib.o; screen.o;
foolib.c; foolib.h;
parser.c; parser.h;
m5ness.c;
makefile;
mdefcon.h (aka Guiness; "Must drink Guiness" is all I hear on
the radio nowadays...")
mi1mp.c and m1imp.h;
: These import m1's TESTIN.TXT files.

And I think that's all, of the 120 or so files now in my
m5 directory, that are worth looking at...

I think looking at rendlib.c or screen.c will only inspire 
mass hysterica... about 10% of their contents are incomplete
or obsolete... never fear, I'll release it when I'm
happy with it.        

---]

It works, so who cares?

Well, I care. I believe I can write non-icky code.
And I won't stop until I write something that is somewhat
elegant. So there.

Naturally, it would help if I had some form of formal teaching
in programming, won't it? University here seems to be a waste
of time, though... and in fact, most places... so ...
"maybe next year"...

Actually, I think I'll actually do an associate degree, but not
to learn about programming, to do some more "human" stuff,
like psychology, english, history, philosophy, etc.

---]

What's taking so long?

Personal stuff takes up a lot of my time...
That's all I will say for now. 

I figure I get about 4-6 hours of coding done 
on an "good" (codewise) day, at an efficiency of about
20% (so that's about 1:10 of normal time, and nowhere
near hacker efficiency of 10x+).

And that includes time spend designing...
and writing documents like this one, 
It's of paramount importance to me that the next M be
well designed and cleanly implemented, emphasis on
well designed.

---]

What's next?

m5ness:
-Version 2: The Status Era

Those blank rectangular areas on the top and bottom 
of the screen are actually the logo and status bars;

m5ness,v2 (henceforth know as v2) will implement and
use the status bar, as well as take a variety of 
options from the command line and perhaps even
the allegro.cfg file... (unlike m1, m5ness does not take
a billion arguments, in fact, it take only one: r; to 
reserve RAM.)

Also, a seperate doc on memory management, 
which I ranted a bit about in mdefcon.h;
but there's yet more I can/will say about it.

---]

How m5ness works:

m5 is a collection of libraries (or "technologies" in suitspeak)
which implement seperate yet interdependant layers of immitation.

Here's that in semi-pictoral form:

---Top : C99 concept
m5ness (wrapper program)
Parser (C-NASIC interpeter)
screen (SMELL)
rendlib (V99)
Allegro 3.1
Hardware
---Bottom : Native implmentation

m5ness initalises everything, and then runs the parser.
the parser calls funtions in the SMELL as needed,
SMELL calls RendLib as needed,
rendLib uses Allegro routines,
whcih access the hardware.

Hurray!!!

Now, some icky implementaiton details:

the routines in m1imp are used to load M1-format files
(with m5ness r5 extensions, sometimes know as
m1f-m5ness-r5; but not usually because that's long and
boring) into a block of RAM which it also allocates
and maps to a MEMSCOPE. The files are not simply loaded,
but also processed a bit, in order to conserve space
and make life easier for the Parser:

-It (m1load) formats the output (NASIC bytecode in Block
0) in one statement per line ; 0-terminated ;
no-whitespace out side of quotes; byte strings 
-It places 3 zeros at the end of the NPAM code block (Block 0)
-It builds a Label Table, with the labelnames and their
line numbers, in the Ltbl Block, and the back of the
NPAM MEMSCOPE (Block 1).

see mdefcon.h for more info on MEMSCOPEs and Blocks...
here's the gist of it, though:

MEMSCOPE:
START ...       |   FREE SPACE                          | ... END
Block 0         |                                       | Block 1

Block 0 is expanded into freespace by moving .used;
Block 1 is expanded into freespace by moving .back;
freespace = .size - (.used + .back);

use memStatf(FILE* stream, MEMSCOPE victim) (in foolib)
to print these stats out in a nice format,
foolib has gained more memory management routines,
read the header files.

The Parser has 2 phases:

Prefetch;
Exectuion.

---:
Prefetch : before the next instruction is fetched form the NPAM
code block; the keyboard is scanned for certain input...

see nessuse.txt for details.

---:
Execution : the command is read, and , if not END, executed.
END is executed as well, but this exits the Parser with a
"PROGRAM TERMINATED NORMALLY" message in the log file.

---]

Yet Another Rant:

Allegro 3.11 is out; I'll upgrade Real Soon Now... heh.
No need, even 3.1 from 3.0 was not that big for me.

Also, I'm now using Caldera OpenDOS.
It rocks; took a short while to configure and
v 7.01 doesn't support some cool stuff that MS-DOS 7 does;
e.g. menuen in config.sys;

but I feel more in control now.

btw, caldera's DPMI server crashes DJGPP (in a cute way, but still...);
so disable it (DPMI=OFF in the EMM386 line) and put cwsdmpi in the
PATH.

also, dir is cooler.... dir /c /2 /p is nice. speaking of which,
I now have 117 files in the main m5 dir! I need to do some cleaning
up soon.. I have Chip's c64.exe and related
stuff, and .. Yet More Stuff... there.

Oh, I'm also planning to use NASIC to extend itself, at least
initally. If speed is a real concern then native implementations
could be used in the runtime project (like compiling Java with
Windows native extentions to the win32 SPI for speed). I'm more
interested in development systems... developing what? Gee, just
about anything that needs a relatively small memory footprint...
the C64 did wonders; esp. when you tossed another 512K at it and
ran GEOS... or so I heard, I never could afford that stuff and I'm
not buying it now except as a collector's item type thing... like
how ppl buy old cars and refurbish...

My English teachers must be so disappointed in my paragraph structure.

Hey, this is a rant. live with it.


---]

Contact info:

My fellow friends/developers know where/how to find me.
If u are the populace, check nessuse.txt

---]
Pi!

Greets to:

Sir Nelish; his esteemed nelishness of Oy;
good luck with the woman/girl/grrl/bitch/whatever you call her.
And tell her if she breaks your heart i'll kick her ass.

Master Chip; his esteemed muhahahahahaness and 
one who calls others Wilson. Without him and his muhahaish
C64.exe project, I would never have gotten this far...
m5 now has a new featureset to surpass. Also, his help and
inspiration has been invaluable; i wouldn't have OpenDOS if
not for his trying-it-firstness.

Lord TWood; his esteemed first-in-line-for-a-degree-ness;

Sire Pennegan; who hates kode and will never read this;

S.O.P.py a.k.a Lord Drifter;
who never RTFM and will thus never see this;

Lady vixen; who doesn't kode but is a kool friend and is
very inspirational.. 

Female Cousin Yinny; another non-coder, she's had an indirectly
inpirational effect on the C99 project.

Female Cousin dopey; who always complains that I never thank her
for anything. But hey, I love her anyways.

---Keinall "Granitor" Caddle

[[[MooFoxy 99!
