Category : Forth Source Code
Archive   : DIARY.ZIP
Filename : DIARY2.TXT

Output of file : DIARY2.TXT contained in archive : DIARY.ZIP

August 25, 1989


"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
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..."









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
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