dmx.txt
(c)1999 Keinall "Lord Granitor" Caddle

Documentation for dmx.exe; also covers
beta.exe to a degree, as they currently 
share many components, such as the 
driver (dmx.c, in both cases).

:K31 at 16 Oct 1999
Began editing of this file to bring it up
to date, it's based on IDENT/beta.txt docs.
	06 Nov 1999
Continued editing of this har fileness...
	08 Nov 1999
Finished editing this file, it's now up
to date with dmx.exe; betad.txt describes
changes to beta.exe and Macas.txt describes
the Macas in depth.
	10 Nov 1999
Post-release changes and tweaks and stuff,
now I'm really done.. for now...
	18 Dec 1999
Pretended to document the changes to 
IDELIB. All I really did was rant a bit.

:Documented the new ad hoc debugging commands.
a builtin monitor, MM (Mini Monitor) was 
originally planned for DMX. 

It might not be far off...

---]
Intro

So, you've got dmx.exe, the mainstream product of
m7 technology. Well, I hope you know what you're doing.
If not, you will by the time you finish reading this.

---:
Requirements

To run dmx.exe, you have to have:

	The right attitude:

-a love for the Commodore 64 and/or related computers;
-an appreciation of Command Line Interfaces;
-an inate sense of koolness and serenity...

	The right files:

-CHAR.ROM, a 4K dual character set of 512 8x8 pixel monochrome characters
-basic2p.cas; a Tok/SACAS file which defines tokens for use in the 
driver component of the wonderful DMX. 
-INITIDE4.CAS, a Macas file used to do the startup screen of this
Great And Wonderful product.

	The right expectation:
	
This isn't a deeply intense project, a masterpiece, an open source
project, or anything so grand. It's just something I was fooling
around with and wanted to show to my koding friends. However, I've
lagged over a long period of time (just about a year) and now the
project is really far below my standard, but rekoding it all isn't 
something I've committed to yet. 

Also, there's no warranty. This shit is buggy and you should be
careful how you use it. And don't even think of blaming me. It
is probally more stable than windows 3.1 but less stable than DOS 6.

Have fun, but be forewarn'd it's fairly useless, even if it's sorta
kool.

---:
Recommended

The following will make using beta.exe more fun:
-a lack of fear of command line aruments;
-knowledge of what a DOS Commant Prompt is;

The following files are run by the Macas parser,
and will give you some source code to look at,
as well as something to play around with. I 
advise reading MACAS.TXT if you wish to get 
a firmer grasp of Macas.

-TESTIN6.CAS is the current test and demo program,
which demos the ability to write ptetty letters on
the screen...
-TESTVAR4.CAS test the floating point load/store routines.
-ID.CAS is a simple file which demonstrates the 
system strings and the system numeric, and
their proper use with Print Ex.

---:
Optional

You may not want anything listed here, but it might help...

-an installation of Allegro 3.11;
-OpenDOS and CWSDMPI (turn OpenDOS's dpmi off);
-Windows 9x - this is not recommened in itself... 
but it's what I currently use to develop all the 
stuff in the M Project. Actually, I use DJGPP and
Allegro, but my box runs this stuff a the sole OS
right now. 
-Linux - the M Project has not yet been ported to Linux.
but it might be ported to Linux 2.2 or later, eventually,
and utilize fbcon.
-BeOS - looks nice and stuff, but I've never used it.

---]
What is dmx.exe?
What is DMX?

DMX is the codename for a project to create an
Integrated Development Environment for Militant
Testing of Macas. This is a neat abreviation
but is really a backacronym, in truth, they are
two manifestatiosn of DMX:

IDE MT - dmx.exe; which you are now reading about.
IDE MT : Beta Edition - beta.exe; which is a more
experimental derivative of DMX. see betad.txt
for more info on this.

IDE NT tried to imm the C64's Full Screen Editor and Direct
Mode of the BASIC interpeter. IDE MT, on the other hand,
aims to create a comforable environment to work with 
Macas files, processed at runtime from the externally
edited plaintext source into ... procas... which is
largely inflexible as far as editign goes... 

Eventually an editior may be written which uses
the FSE already present in IDE MT...

A lot more work needs to be done, also, I'm gonna add in some
useful extensions which weren't standard on the C64, but 
which I find very handy and stuff. Also, due to the advanced in
keyboard technology, I may change up a few things...

---]
Newest Stuff

Keyboard control: HOME and END work on current line,
CTRL+HOME and CTRL+END work on the whole screen,
which is more modern in my estimation... 

Keyboard hak : INS / DEL turn reverse mode on/off
eventually I'll use CTRL+9 / CTRL+0

LET command trims open white space...

SYS command added to the IDE Driver (dmx.c);
this allows execution of sub-routines in the
Macas code, by name. Ain't that kool?

Several minor changes to improve how DIR
and DLIST (aka TYPE) work. 

--:
rantish:

m7 isn't modular or kool enough internally,
so I will eventually do some major redesign
and rewriting from scratch and stuff. 

refactoring the flush - and - rekode way...
yeah, I'll pince some good routines from the
old kode... 

maybe. I've never been very consistent in the 
past with this...

---]

Command Line Aruments:

	Note that CLA parsing is a bit buggy. I can fix it but I 
	haven't yet. Their are other things more important to me
	right now, within C99.m7... in fact I'll probally not
	release anything else until I'm done playing around with it.


*new to support experimentation*

-dolly	
	This initiates a 80x65 matrix, suitable for 800x600 reolution.

	

*new to support the more flexible graphics routines*

-bigness
	This initiates a 16x10 text matrix (default is 40x25).
	The use of this mode is questionable, but it allows for
	very large letters...
	
-tikky
	This initiates a 80x40 text matrix, thus requiring
	a -size640x400 or higher... and a -nogui. For
	experts only... feel kool if you use it.

-size[width in pixels]x[height in pixels]
	Sets the physical size of the screen. It would be more
	humane to use modes but I'm not very humane at all. This
	requires -nogui, and replaces the gui method, using
	autodetection always... not that an invalid mode would
	cause doom and destruction and SIGSERVs... so be careful.
	
*older stuff which might have been tweaked to make it kooler*

-slothful

	This cute little switch enables slothfulness, and slows down the imm.
	In practice, a slight delay will be introduced between commands.
	This delay is adjustable, use Keypad '-' to increase the delay,
	thereby slowing down the imm, or Keypad '+' to do the converse.

	The PAUSE key can also be used to toggle the slothfulness of the imm.

e[e...]
	Now, for a while, using 'e' has enabled verious levels of parsing of 
	whatever was entered in the IDE. Here and now, I will explain what 
	the dfferent levels are. (one 'e' is equavalent to one level).

	Level   0:      Disable evaluation. 
		1:      Enable lookup, using the new parameter seperating
			algorithm. Spaces, digits, and the dash indicate the 
			start of a parameter. everything before is tested for 
			tokenness.
			If a valid token is found, then the entry "TokVal:".. 
			appears in the log file, indicating the value fo the
			entered token. (this is experimental software, and
			logging is fairly copious.. )
		2:      If the token has a valid value, the line is logged to
			the driver log file, by default, this is beta.log.
		3:      The user is informed of syntax errors in the parsing; 
			i.e. unresolved tokens.
			The lines with unresolved tokens are logged as well.

-drama

	This inables a slight pause everytime the sloth is adjusted. 
	Totally pointless. 


-debug

	This enables debug mode in the Second Impact Parser. a.k.a. parse3r2.
	No one in their sane mind would want to use this. You'd need the source
	to be able ot make sense of it. And I'm still hacking that, so, mind
	your sauce. Wait. Or just ask for it, if you want it. I don't see 
	why you would, though, it's in flux...

-parsetalk:[verbosity level]

	e.g. -parsetalk:0

	This controls the verbosity of the Second Impact Mainstream
	Constricted Nelish-inpired Almost Symbolic Instruction Code Parser.

	The verbosity of what it logs to casparse.log, that is.

	I'm currently revamping this, for now it's fairly silly.

-vartalk:[varlib verbosity level]

	e.g. -vartalk:2

	This controls the verbosity level of the embedded varlib logging info.
	You see, rather than logging to a seperate file, varlib takes a 
	file stream which 3r2 supplies (which represents casparse.log), and
	logs to that. I'll probally explain the mechanics later when I do 
	a src/API release, but for now, know ye that casparse.log will
	contain lines looking like this:

		varlib: Now Logging at level 0 verbosity.

	The levels of verbosity are as follows:

	Level   0:      Log only inital message.
		1:      adds logging of variable additions, i.e. 
			allocation of resources, initalisation of variable 
			with a given name and type.
			also logs when variables are not 
			found to be pre-existing,
			which should lead to the former case, 
			unless insufficent
			FMEM (frontal scope memory) is available.
		2:      adds logging of failures to find a given variable.
		3:      logs each variable comparison. only useful for 
			debugging the internal C functions...


-parselog:[logfile]

	broken. ignore.

-debugide

	This is a quick hack for debugging the driver. Ignore.
	
	Currently, it causes CONT to print the calling
	offset (Program Jump Offset) and return offset (Program Return Offset).
	However, like all quick hacks, it may change on a whim...

---]

Also read:

INITIDE4.CAS; 	--default startup script
ID.CAS; 	--alternate startup script
MACAS.TXT;	--describes Macas in detail

---:
Aside:

	It occurs to me that I really have little to no idea how the 
	current tokenization/detokenization/tokscript parsing routines 
	work, but it's probally not pretty and certainly not efficient.
	
	Good luck if you decide to try to use them. I'm just planning
	to start fresh...

---]
Direct Mode Parser : Commands

Commands are primitive at best,
inspired by CBM Basic 2.0...

so, anyhow, on with the show:
---*
Ledgend

<> : optional parament
[] : required parament

---:
RUN <offset>

	This command re-initalizes the parser and, given an optional offset,
	resumes execution at -exactly- that place. Even if there's no vaild
	command there!

	If you opt to omit the offset, then , the command will start
	at the start of the proCAS, a.k.a Start Of Text.

CONT

	If you use the ESC key to stop program execution, then, you can resume
	it by using CONT. In fact, you can always try to CONT. It should only
	fail if you are at the end of the program text...
	
	This might not be propelry implemented yet... so many things to do...

	?CAN'T CONTINUE not imm'd properly yet... 

SYS [O-Label Name]

	This ingenious command allows you to jump to a labeled sub-routine
	with the Macas text. Macas is more like assembly/machine language/code,
	so I feel it is more appropriate to use SYS. Implemented as a Macas
	JSR/GOSUB, has a nifty hidden feature:
	
	SYS [O-Label Name]":[proCAS text]
	
	well, play with it and you'll see... 

LIST < [<start> <-<end>>] | [statement offset] >

	Identical in syntax to the C64 LIST command, this cute little thing
	will list the line range , statement, or whole program, in the
	following format:

	[offset] [proCAS text]
	...

	e.g.

	0 m0

	Just try it and you'll see...

TEST [proCAS Text] 
	
	This ad hoc hak of a command allows inputting processed Macas
	commands direct to the parser, running them in Direct Mode.
	note that in Direct Mode, the trusty colon (':') can be used 
	to seperate commands, e.g.
	
	TEST C0:M1:S:?%FREE;" BYTES FREE"
	
	TEST C6:B14:J"START"
	
	TEST S:U"BOTTOM":L10,5:?"BOO!"
	
CLR 	
	Clears the variable table. This erases all variables,
	by de-allocationg the variable memscope's dual ranges,
	and also zeroes the entire memscope, in it's current 
	behaviour.

DIR [mask]
	
	Lists the names and sizes of the files that match the
	given mask (wildcard string). For example,
	
		DIR *.CAS
		
	In that respect, it's just like DOS...
	
DLIST [mask]
TYPE [mask]

	List the file or files to the screen.
	You can use a filename or a mask. The globbing
	process is identical to that for DIR.
	
	Also, you can hold CTRL to slow the display,
	or SHIFT to pause it, or press ESC to abort it.
		
LOAD [filename] 

	Attempts to load a CAS source file, currently using the
	aging m7/m1imp library to do the preprocessing. This means
	that newer .CAS files will load fine, but older files
	might be incompatible with the current parser... 

	I'm already working on better loading routines, and also on
	a comprehensive file handling system. And taking over the 
	world. So who knows when I'll get to doing what...
	
	A better preprocessing layer is needed... 

SAVE [MACAS filename] 

	Attempts to save the current proCAS to a MACAS  file with an 
	explicit .CAS extension, e.g.

		SAVE foot.cas

	Note that if you do not include the .CAS extention, then
	an error will be generated! 
	
	Not that a lot of extra info form the source file will be 
	lost in this file. Perhaps I should change the extention to 
	.PCN... (Processed C-Nasic).

KILL [MACAS filename]

	Attempts to delete the given file... this is a very temporary 
	hack. But then again, it might be here for a while.

LET [variable name]=[value]

	Duh. e.g.
		LET test=80
	** new 08 Nov 1999 : additional whitespace now
	correctly trimmed, giving this command a much
	kooler feel as you can now say:
	
		LET test = 79
		
	and similar stuff. 
	
	>>> This line intentionally left pointless.	<<<

PRINT [variable name]
?[variable name]

	e.g. 
		PRINT test

	Note that a space needs to follow any command name,
	unlike the C64's parser which was a lot more aggresive 
	at tokenization...
	
	But '?' is special and needs no trailing whitespace...
	
	Currently, this PRINT is different from the pc (ProCAS)
	parser... this is due to design and I'm working to 
	redesign and rekode the things like this to increase
	code reuse and whatnot...  the aim of the "Flat Parser"
	project... 

PI [name]

	A cute little thingy to evaluate the "number of a name",
	that is, it takes all the letters and sums the ASCII values
	of them (in upper case). It ignores everything else,
	except numbers, which are not properly dealt with yet...
	The face values of the digits are added, which is convienent
	for, say, John Smith the 4 th => JOHN SMITH 4. 

	This is relatively useless, but, a fun toy. sorta. 
	
FLIST [level]
	List the frontal scope of the main code memscope,
	i.e. the program text on a byte level. 
	
	level :
		1 - decimal numbers
		2 - hex. numbers 
		3 - hex. numbers with characters as well.

MEMSTAT
aka MSTAT
	List the bytes used and free, etc. of the program text in
	local and sma-managed formats. SMA is the Static Memscope Allocation
	library. It manages memscopes, basically. If the driver to 
	SMA interface is buggy then MSTAT might report different numbers. 


---]
Epilogue...

'movement and repose'

---]
K31...

K31;
	Carrots and cucumbers and traffic lights!
:13K

---K31
