August 25, 1989


		DIARY OF A FORTH STUDENT - DAY 2

			"What Documentation ?"

	Since I started forth I have wondered why some versions of forth
and many programs on BBS boards have so little or no documentation. The
answer that has come to me after some thought and exposure to the forth
community is that forth attracts people who like to explore new ideas
without the rigid and confining restrictions of any "concrete" format
or procedure.  One might use the term "software scientist" or "software
hobbiest" or "software experimenter" or perhaps "progressive programmer" ?
	The question which comes to mind for some people during their 
first "close encounter of the FORTH kind" is "is there a method to the
madness ?". For the user of any of the experiments in programming style
one may encounter on Forth BBS boards the method is to download the
program and try it. If it fails to load due to an "undefined word"
error caused by a word which was part of the author's extended wordset
which he failed to include with the program then you have several al-
ternatives. You might try leaving a message on the same board for the
author of the program describing which forth you use and what kind of
computer you have and what happens when you try to run his program. 
You might also try leaving a message for the sysop of that board telling
him you downloaded one the programs in his library and are having a
problem getting it to load. Another possibility which I have encountered
many times is trying to load a wordset extention out of sequence. That
is , trying to load for example , the 3rd of 4 extentions which are all
from the same author , WITHOUT first obtaining the first 2 extentions and
loading those. If the author started with a root dictionary of F83 and
wrote 4 extentions in a specific sequence, the later extentions will 
more than likely call words defined in the earlier extentions. In such 
a case you must find out how many extentions there are prior to the one
you have and locate those and download them so you can provide your
program with the prerequisite words to load. 
	What exactly is there of value on forth "boards" (BBS's)
and how do you make use of it ?

	Lets consider some possibilities:

		1. Public domain versions of forth
		2. Documentation to accompany the above
		   (you will find that documentation is often
		3. Information on WHERE or HOW to acquire
	           documentation for Public domain Forths.
		4. Tutorials and technique files 
		5. Wordset extentions or "programs" or both.
		   "Both" means the wordset extension provides 
		   'WORDS' to add to your root dictionary AND 
		   includes a program written with those words
		   which might be a utility or "tool" or a demo.
		6. Bulletins announcing forth related events or
		   activities.
		7. Utilities written in forth, which in some
	           cases may be used as an extention to expand
	           your dictionary provided you understand how
	           to use the words defined by the author when
	     	   he wrote the utility.
		8. Forth "tools" such as the type contained in
	 	   "Dr. Dobbs Toolbook of Forth".
		9. Real-time conferences which you can join and
		   watch the "pro's" discuss forth topics or if
		   you dare you may ask them a question yourself.
		   Only last week on August 24th, the creator/
		   inventor/discover of FORTH , Charles Moore,
		   was the featured guest on Genie's Roundtable
		   Conference, however there were so many people
		   attending the conference that only a few had
		   time to ask questions. Often the host sysop
		   of the conference will weigh the number 
		   attending against the time available and may
		   or may not ask you by name if you wish to 
		   ask the guest a question. Even if you do not
		   have a chance during the "official" conference
		   which lasts until the Host declares it over
		   you may have a chance to pitch your question
		   after the conference is "officially" ended
	           during an informal question/answer period when
		   the featured guest ussually stays for awhile
	    	   to answer questions which could not be fit in
		   during the "formal" proceedings. I had the 
		   opportunity to discuss several things with
		   Roedy Green, the author of ABUNDANCE and BBL,
		   which are HUGE versions of public domain forth
		   which are F83 standard compatible. I strongly
		   encourage anyone trying to learn forth to make
		   every effort to communicate directly with any
		   of these key figures in the evolution of the
	  	   language. This is one of great things about 
		   forth right now is that there is almost
		   nothing to stop you from communicating either
		   directly (realtime) or indirectly (E-MAIL and
		   messages) with everyone of influence in the
		   forth community. You can't ask for more than
		   that! Go ahead, talk to them! Tell them you
		   you think Forth is weird or confusing and see
		   how they respond ! Why not ? You'll never find
		   out unless you try. As a member of the forth
		   community, you are one of those people THEY
		   want to talk to so they can find out what you
		   think of their latest program ! That is one of
		   the reasons the people helping to shape the 
		   future of forth make themselves available !
		10. News in the world of Forth : "so and so 
		   completed initial successful testing of his
		   space-age widgit , programmed in Acme-forth.."
		11. Education related forth news: "such and such
		   university engineering class to hold their 
		   gizmo design contest next month, most entries
		   expected to use forth..."
		
	"WORLD'S FASTEST PROGRAMMER CONTEST HELD IN ANAHEIM,
	
		WINNER PROGRAMS MYSTERY GIZMO IN 1 HOUR 23
	
	MINUTES (WITH NO DOCUMENTATION) TO SPELL "THE RAIN IN

	SPAIN FALLS MAINLY ON THE PLAIN" IN MIDAIR BY STROBING

	A COMMON BARGRAPH LED ATTACHED TO THE END OF COMMON 

	HACKSAW BLADE WHIPPED BACK AND FORTH THROUGH THE AIR

	BY A COMMON 12 VOLT CAR-DOOR SOLENOID POWERED BY TWO

	COMMON 6 VOLT LANTERN BATTERIES WIRED IN SERIES !"

		Winner was Phil Burk and his hardware partner
                Mike Haas , both from Delta Research, who
		shared the $1000 cash prize. (not bad for an
		hour and a half of work eh?)

	How did I know that ? I was there ! I went to the 1988
Real Time Programming Convention sponsored by FIG. If you were
not there you missed a GREAT CONVENTION ! You missed a chance
to hear some of the world's most renowned leaders of the forth
community including it's creator Chuck Moore and some scientists
using forth at JPL and GODDARD SPACE FLIGHT CENTER. You also
missed a chance to see many forth related products which are
brand new , and very impressive such as Forth Engines capable
of 12 MIPS (Million Instructions Per Second) running a program
downloaded through an RS232 port from a Radio Shack model 100
laptop computer on a circuit board the size of a small paperback
book ! There was a computer there (a VME-bus system) running
mandelbrot fractals in about 3 - 5 seconds at about 30 MIPS !

	These are some of the things you can see and appreciate
for yourself when you attend FIG sponsored conventions and 
activities. FIG stands for Forth Interest Group and if you are
"interested" in forth you should consider joining and recycling
the knowdege you gain to further expand the forth community.

	To join FIG: Send $30 (last time I checked)
			To: Forth Interest Group
			    P.O. BOX 8231
			    SAN JOSE, CA. 95155

		Or for credit card calls: (408) 277-0668

	Joining gets you a subscription to the Forth Dimensions 
	publication and member discounts on books,mags,software,
	(a World's Fastest Programmer Contest t-shirt?), and
	fliers announcing future conventions with application
	included for reservations. If you need books on forth
	this is your one-stop forth book shop and when you attend
	a FIG sponsored convention or event bring your checkbook
	so you can scarf up the latest forth goodies or books
	or even public domain versions of forth on diskette.


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

	How can you best utilize the online resources in the 
Forth Community on the Forth BBS boards ?

	1. Try everything at least once, but start with the sure
	   things first, and experiment with the "iffy" stuff
	   later. What does that mean ? The answer is not nearly
	   as simple as the question. Almost ALL versions of 
	   forth have SOME things in common, and at the same time
	   almost ALL versions of forth are only compatible with
	   certain wordsets (79-STANDARD, 83-STANDARD, FIGFORTH,
	   etc.) and at the same time almost ALL versions of
	   forth are either commercial or public domain . What
	   are the exceptions ? I haven't the foggiest idea !
	   I don't even know if there ARE any exceptions. I will
	   tell you what I do know from first hand experience.

		a. Regardless of WHICH forth you use, you need to
	    	   know certain things about it. You need to know
	           which standard it conforms to , if any. You
	   	   need to know which other versions it is MOST
		   compatible with, if any. For example, if you
	  	   use a commercial version, you have vender 
		   support, which will solve many of your
		   problems of learning forth, but if someone
		   writes a program in a custom version using
		   only 83-standard words , will it run in some
		   other version ? If someone writes a program
		   in a custom version using custom words will
		   it run in the next updated version ? These and
		   many other questions relate to what you can 
		   and cannot use with the version you have. I
		   have found that it is best to learn something
		   about the basics of forth before you run off
		   to download a ton of software from a BBS.

		b. If you are using a commercial version of forth
		   for the convenience of the vender support such
		   as the LMI (Laboratory Microsystems Inc.) BBS
		   board, you will still need a book or two to
		   help you. You may find that once you get the
		   book, you might run accross a public domain
		   version of forth that conforms to the book
		   more than your commercial version, making it
		   easier to learn forth by following the book
		   with a public domain version of forth , and
		   then going back to your commercial version
		   after you get the basics from using the 
		   public domain version. 

		c. If you are using a public domain version, you
		   might find it easier to use a PDforth which
		   was intended to be accompanied by a specific
		   manual or tutorial book available from the
		   supplier of the public domain version of
		   the forth. MVPFORTH is one example. This is
		   discussed in more detail in the first DIARY
		   file (DIARY.ARC). 

		d. If you are using a public domain version, you
		   might find it easier to use a version which
		   has a tutorial already available from the 
		   same forth board (BBS). F-PC is an example of
		   such a version. F-PC has MANY, MANY extensions
		   and tools and much documentation. It is in
		   many ways the single most comprehensive and
		   complete one-stop answer to learning forth 
		   you could find. For example, I have about 
		   500 pages of documentation on F-PC which I
		   printed out from material I downloaded from
		   Genie's Forth RT. The file DOC225A.ARC is a
		   very comprehensive manual for F-PC. I have
		   megabytes of F-PC software covering every-
		   thing from Floating Point Math to advanced
		   VGA graphics (256 color kaleidascope and
		   Mandelbrot Fractals) and database. The F-PC
		   tutorial in the Bulletin Board (Category 15)
		   by Jack Brown from the University of British
		   Columbia math department is EXTREMELY
		   helpful! 
		e. KEEP A NOTEBOOK ! Take notes when you are 
		   online (short hand) so you can write down
		   the names of people whose messages are help-
		   full to you. You can later use the names
	 	   to search for NEW messages from them.

		f. Keep a file of folders to put printouts from
		   different .DOC files so you can keep all of 
		   material relavent to specific version of 
		   forth. Avoid mixing documentation relating
		   to different versions of forth, because at 
		   a later time you might not remember which
		   version it belongs to.

		g. Capture the directory of files from the library
		   or libraries that contain the tutorial in-
		   formation or the programs which were written
		   for the forth you are using. If you are like
		   me , you will want to capture the ENTIRE forth
		   library directory of files just to see what is
		   available. Go through this list and place an
		   asterisk next to every entry which contains a
		   reference to the version you are using. Then
		   go through the list again and number all the
		   asterisk entries starting with those you need
		   to download first, such as tutorials etc.
		   Then one by one , download and try the items
		   you marked to see if you can use them. If you
		   have problems getting them to run, leave a 
		   message for the SYSOP before downloading any
		   more . He might be able to help you.

		h. You will find that there are MANY different
		   subjects to discuss in forth. You might be
		   better off by creating SUBDIRECTORIES on 
		   your hard disk with names that match the
		   different concepts in forth. That way you can
		   download or copy specific files to that sub-
		   directory which pertain only to that concept.
		   Whenever you have a question about that
		   concept you can go to that subdir. and find
		   everything you have on the subject, right ?
		   Following this practice will enable you to
		   backup your reference files by subject heading
		   so you can arc or copy everything on a certain
		   subject to send or give to a friend . You can
	  	   also send stuff over the phone to people who
		   need it. 

		i. Some programs are text files, some are block
		   files (.BLK), some are sequential files (.SEQ)
		   some are .SCR files which may or may not be 
		   the same as .BLK. Some are labeled .4TH to
		   designate 4th source files. Some of these are
		   text files which contain line numbers and
		   screen # which must be edited out if you are
		   going to use a text to block conversion
		   program, which is one of those "tools" I 
		   mentioned earlier. If you are not sure how to
		   use such a program or what it expects, look at
		   a block file from a program that works and 
		   compare it to what is contained in the text
		   file. You will see that your block editor 	
		   provides the screen and line numbers. If you
		   use a block to text converter to convert a 
		   program which you KNOW works to a text file, 
		   then you can compare the KNOWN GOOD text file
		   with the UNKNOWN text file to see the format
		   difference. Of course I am only suggesting you
		   compare FORMAT , not content of the two
		   programs. This is something you have to find
		   out for yourself since it is one of the basics
		   covered in any book on forth. Once you un-
		   derstand what a file conversion program
		   expects from the input file then you will be
		   able to quickly edit out or add in whatever is
		   needed which in some cases means merely adding
		   or deleting blank lines ! If you are still
		   not sure what I am talking about download
		   CHAP20.ARC from the Genie FORTH RT and you
		   will see what I mean. The file descriptions
		   explains what is contained in the file.

	
	Last but not least, because FORTH is in many ways an

experiment in software , you must remember that the other members

of the forth community are all busy with their own particular 

experiments in forth. You can't really expect them to be able to

help you with your particular problem, but you are always welcome

to ask nevertheless. If they can help you, they will. If not,

they may be able to refer you to someone who can. You can only 

find out by asking, and they wouldn't be online with a Forth BBS

if they didn't want to communicate, so take advantage of their 

availability.  Whenever you leave a message for someone the first

time always introduce yourself and give a brief background so

they know what they are dealing with. The more people you get to

know online, the faster you will learn and the more you will en-

joy it ! And what goes around , comes around, so RECYCLE what you

learn ! Share your knowledge with others learning forth!

	
	Please refer any questions you might have regarding this
	file to: R.SCHEMMEL1 (Genie EMAIL address)

			Have Fun, 
				and may "the FORTH" be with you !

				Bob Schemmel
