Wim Rijnders, Brussels, 17-7-97.

------------------------------------------------------------
Note: If the word 'befunge' does not cause any kind of 
      emotional reaction on your behalf (total panic 
		included), then this application is not for you. You
		might as well get rid of it right away.
------------------------------------------------------------
------------------------------------------------------------
Obligatory Fulfillment of GNU GPL for MRCEXT4 Component.
========================================================

(Item 3b) If you wish to obtain the source code for MRCEXT4.DLL,
please send an email to rijnders@lostcity.nl, and I will 
gladly send you the relevant files. In addition, I have a 
link on my befunge web page to the original site of MRCEXT4, 
where you can download the very same files direct from the 
source. You can find this link at:

http://ourworld.compuserve.com/homepages/wimrijnders/bef.htm

------------------------------------------------------------

Visual Befunge'93 for Windows'95
================================

This document contains info about the source files of Visual
befunge for Windows '95. Most notably, it describes some
idiosyncratic behaviour of the components, which is very 
useful to know if you intend to fool around with the source
code. I would advise you to take a good look at the 'Known
Problems' section.

Enjoy. Let me know if you found any use for this code, made
nice extensions or (heaven forbid) you found some serious
bugs. Any other constructive criticism is also welcome.

Wim Rijnders
rijnders@lostcity.nl


Contents
========
   * General Notes
   * Basic Program Structure
   * Known Problems
   * Hidden Features


General Notes
=============

I made the incredibly stupid mistake of commiting myself to 
making a Visual Befunge; I paid dearly for this, through
unanticipated complexicity and through excessive lack of sleep.

I try to look at it from the bright side. I learned one heck of
a lot in the process.

This program is far from complete; in particular, there is no 
befunge '97 implemented. To support bef'97 multitasking I'll 
have to change a lot of the visual bits as well.

First, I want to see if there's general acceptance of this effort 
of mine in the Fungoid community, then we'll see if we get around 
to implementing the new befunge'97 specs.

Actually, I'm kind of hoping that this code will serve as a
front end to an existing Befunge core, most notably Ben 
Holmstead's industrial strength interpreter, which is obviously
better that my feeble attempt.

One of the consequences of the 'Visual' bit is that I had to 
insert hook functions all over the place, in order to update all
screen elements properly. These functions are defined as externs
in the header file. 

I sincerely apologize for the excessive use of templates. It's 
not like I want to keep on reinventing the wheel or something. 
Programming in/for befunge is something you do for fun (albeit 
in a geeky kind of way). I'd rather concentrate of the befungish 
bits of the code.

Given half a chance I'll convert the templates to STL. I'll have
to learn STL first tho...


Basic Program Structure
=======================

Developing work was done with Visual C++ 4.0

The program is basically created with the AppWizard by selecting
SDI and ignoring all other options. I also added two CDialogBar 
members, one for displaying the befunge stack and one for 
displaying the output window.

I added two dialog boxes for user input, one for characters and 
one for numeric values. You'll also find a standard dialog box for 
changing the font in the befunge window. 

The dockable control bars come from a freeware package with a nice 
GNU license slapped on it. The owners allow me to use their nifty 
product as long as I mention their name somewhere (see the About box).
Oh yeah, and I also have to make their source code available somehow
(see top of this text file).

The befunge part is adapted directly from Pressey's code. I built a 
class around his interpreter, along with some nonfunctional nifty 
extra's.


Known Problems
==============

Following in an enumeration of weird and unexpected behaviour
when using this code.

* ASSERT's on Startup under Debug-Mode
 -------------------------------------

 For given configurations of the dialog bars under debug-mode, 
 you may get assertions in the following MFC routine:

	void CDockBar::AssertValid()

 I couldn't get rid of it (Lord knows I tried), but selecting 
 'Ignore' seems to work OK. Just ignore this assertion.

 Also read the following related note.

* Warning when compiling under Debug-Mode
  ---------------------------------------

 When compiling a Debug version, you are likely to get the 
 following error warning:

 "Second param DockControlBar() set to zero for debugging"

 This is due to two conditional compilations in 
 CMainframe::OnCreate(), which have the form:

		#ifdef _DEBUG
		#pragma message("Second param DockControlBar() set to zero for debugging")
			DockControlBar(&m_wndWatchBar, (unsigned int ) 0);
		#else
			DockControlBar(&m_wndWatchBar, AFX_IDW_DOCKBAR_LEFT);
		#endif

 This befunged code is the end-result of a problem which drove me 
 potty, and had the delivery of VisBef delayed for a week.

 If I pass a non-zero parameter in debug-mode, the debug version 
 will continually ASSERT, hang, and create Access Violations for 
 certain layouts of the control bars. This happens somewhere deep 
 in MFC and I dare not touch that code.

 Setting the second parameter to zero just results in a single 
 harmless assertion (see previous note). Given the problems I had 
 before, I can live with that.

 The Release version does not appear to have this problem.


* Changing fonts in DEBUG-mode results in ASSERT in MFC-code.
  -----------------------------------------------------------

  There's a totally ridiculous ASSERT at line 114 of DLGFONT.CPP. 
  This ASSERT tests if the Font Dialog Box has a window handle.
  Of course it doesn't, because the window has been destroyed 
  after pressing the OK button. In fact, the code following the 
  ASSERT takes the absence of a window handle into account.

  I fail to see the use of this ASSERT. Just ignore it. This is 
  an MFC-related problem. I hope someone can tell me the raison 
  d'etre and if it is restricted to MFC 4.0.


 Hidden Features
 ===============

* Bef'97 features
-----------------

   Yes, I have secretly been working ahead. On careful inspection
	of the code you will find:

	- a full-blown bef'97 2^31x2^31 befunge space, implemented using
	  a simple hashing approach.

	- Multitasking for as many PC's as your machine can handle.

	- Actually, I prefer coining the previous feature as 'multithreading'
	  to distinguish it from the 'real' multitasking I implemented.
	  A 'task' in my program is a collection of PC's which belong together. 
	  This distinction will be important for BefGlad implementation.

* Integrated Editing
--------------------

   Observant readers may note that I have already incorporated
   editing capabilites in the view class.However, I ran into some 
	basic problems which I couldn't figure out on the short term.

   The problem is basically the following: You can run the
   befunge program while editing it. The befunge program can 
   modify values as well. So how do you know what to save to 
   file when you're done? I think I'll need a sort of shadow
   buffer for storing the changes (or the original or something);
   unfortunately I can't bring up the necessary energy to
   implement this right now. This project has been too demanding
   already.

	To turn on the editing feature, #define ALLOW_EDIT in you project
	or at the beginning of file VisBefView.h. After compilation, a
	black cursor should be visible at topleft. You can use the cursor
	keys to navigate, as well as Home, End, PgUp. Etc. Left-clicking
	on a cell puts the cursor at that position. Any printable ASCCI 
	character you type will be stored at the cursor position.
