pygmy.txt

Embedded magazine source code in the year 1990

                     Pygmy Forth version 1.3 MANUAL   
                 Copyright 1989, 1990 Frank C. Sergeant
                                      809 W. San Antonio St.
                                      San Marcos, TX  78666

        Pygmy Forth version 1.3 is a fast direct-threaded Forth for 
reasonably compatible MS-DOS & PC-DOS machines.  It includes an editor, 
assembler, and metacompiler (so it can recompile itself) in only 14K.  Up 
to 15 files can be open simultaneously. It comes with full source code and 
documentation.  It is based loosely on Charles Moore's cmFORTH.

    TABLE of CONTENTS

                  Chapter  1   Terms of use and distribution
                  Chapter  2   Bonuses
                  Chapter  3   Credit Where Credit is Due
                  Chapter  4   "Why I Wrote Pygmy" 
                  Chapter  5   What Is Pygmy?
                  Chapter  6   How To Run The Program
                  Chapter  7   If You Are New to Forth
                  Chapter  8   What Was New With Version 1.2
                  Chapter  9   What Is New With Version 1.3
                  Chapter 10   Tips
                  Chapter 11   How Files Work
                  Chapter 12   The Assembler
                  Chapter 13   The Editor
                  Chapter 14   The Meta Compiler
                  Chapter 15   Vocabularies
                  Chapter 16   Additional Information
                  Chapter 17   Addresses
                  Chapter 18   The Glossary
                  Chapter 19   Memory Map
                  Chapter 20   Files
                  Chapter 21   Direct Threaded
                  Chapter 22   History & Philosophy
                  Chapter 23   How to Print the Source Code


Chapter 1           Terms of use and distribution

     I hold the copyright to all of the documentation and source code and 
machine code included in the Pygmy Forth version 1.3 package, including the 
organization and presentation thereof, with the exception of the parts 
taken from public domain sources or contributed by others.

     Conditional upon recipients accepting full responsibility for any 
adverse consequences or damages, I grant to recipients of this package
permission to further distribute it, to post it on computer bulletin 
boards, to use it for developing personal or commercial applications, and 
to use parts of it in building other Forth systems.  I DO NOT GRANT 
permission to distribute printed copies of the source code or the 
documentation, or to publish the same in books, magazines, etc.  If you 
wish to do something along these lines, please contact me.  (I am excluding 
from this excerpted source code that you have incorporated into your own 
Forth system, and nothing here is intended to prevent you from printing 
out a hard copy of the source code and documentation for your own use.)

                     Is This Shareware or What?

     Well, yes and no.  You are welcome to use Pygmy.  If you do, you 
assume all risk.  Don't use it on anything important until and unless you 
have completely tested it.  If Pygmy is valuable to you, feel free to send 
me some money.  A gift of any amount will be appreciated.  On the other 
hand, my "assistants" in this endeavor (my bulletin board buddies as 
mentioned below) certainly should not send money.  Please don't refrain 
from writing, regardless.  That reminds me of the old joke of the kid away 
at college who writes home "Dear Mom & Dad, please write often, even if 
it's only $5.00."


Chapter 2                       Bonuses

     There are some bonuses for anyone sending me at least two tens and a 
five:

     1. Serial I/O routines with interrupt driven input.
     2. Double (32-bit) and Quad (64-bit) number support.
     3. Printed glossary, organized by categories, indexed to screen 
        numbers.
     4. Shadow file (PYGMY.DOW) commenting, screen by screen, on the 
        meta-compiler and kernel source code.
     5. Perhaps (don't count on this) 1 or 2 mini-applications to serve as 
        a skeleton for your own work.


Chapter 3               Credit Where Credit is Due

     Pygmy Forth was inspired by cmFORTH for the NOVIX, a public domain 
Forth written by Charles Moore.  Much of the overall structure and some of 
the specific high level code reflect this influence!  Some of the machine 
code, especially flag producing words, is tighter due to ideas suggested by 
Robert Berkey.  In addition, the code for DO LOOP (in the Starting Forth 
compatibility section) was contributed by Robert.  Wil Baden provided OF 
THENS.  The initial approach to handling files was suggested by Dennis 
Ruffer by his description of files in Forth Inc's polyForth.  Rob Chapman 
contributed the idea of (and how obvious when you think about it!) having 
FOR NEXT do the loop <n> times instead of <n+1> times.  He also contributed 
a slogan that I've adopted: "It's so simple - it HAS to work."  There may 
be other such specific contributions that escape my mind at the moment.

     In general, I would also like to thank the many people who, through 
the Forth bulletin board network, hounded, badgered, criticized, suggested, 
questioned, and otherwise encouraged me to think.  They should be held 
completely responsible for any remaining errors.

Chapter 4                   "Why I Wrote Pygmy" 

     Pygmy Forth's goals:
          1. Faster, more comfortable editor.
          2. Reduced sized and complexity.
          3. Inclusion of certain cmFORTH ideas:
             a. PUSH POP (instead of >R R>)
             b. FOR NEXT
             c. no IMMEDIATE word
                (but it does have words that are immediate)
             d. simple Meta-Compilation

     Pygmy includes
         1. a fast screen oriented block editor
         2. an 8088/8086 assembler
         3. full source code
         4. full meta-compiler
         5. up to 15 files open & accessible at one time
         6. default set of files opened automatically
         7. FOR/NEXT, PUSH, POP, \, COMPILER vocabulary, and
            other cmFORTH improvements
         8. Direct screen writes for speed for monochrome
            & color
         9. vectored I/O  ( EMIT, KEY, KEY?, CR )
        10. documentation (this file)
        11. *Starting Forth* compatibility hints for people new
            to Forth

Chapter 5                    What Is Pygmy?

     Pygmy is one step on my path toward a "perfect" Forth.  It runs on the 
IBM PC/XT/AT and compatibles. It is based (more and more loosely) on 
Charles Moore's cmFORTH for the NOVIX Forth chip.  I have made many changes 
to allow it to run on a PC, and other changes as well.

     cmFORTH was designed to run on a NOVIX connected by a serial line to a 
host terminal or computer that supplies editing and file storage services. 
Therefore, cmFORTH does not include an editor.  Also, no assembler is 
needed because the NOVIX's assembly language is Forth (more or less).

     Pygmy Forth includes an editor & assembler and still only takes up 
about 14K bytes.  The kernel (without editor and assembler) is less than 
8K.  It comes with complete source code, including a meta-compiler, so it 
can recompile itself.  The meta-compiler can also be used for target 
compiling custom applications.  In this case you can eliminate the parts 
(such as the editor & assembler & various utilities) that the final 
application will not need.

     Pygmy is direct threaded with top of stack kept in a register.  It has 
(in my opinion) quite a comfortable screen oriented block editor. You can 
move quickly from screen to screen with the PgDn & PgUp keys, search across 
screens, insert blank screens, and compress out blank screens.

     Pygmy allows you to have 15 files open at one time.  These are all 
accessible "simultaneously" at different block numbers (none of the 
OPEN/FROM as used in F83).  Your default files are opened automatically and 
the defaults can be changed, of course, and additional files can be opened. 
.FILES shows you the defaults and the documentation shows examples of how 
to reset them.  If you need more than 15 files open at one time, there is 
supplemental code that shows how to have over 200 files open simultaneously 
(untested).


Chapter 6                  How To Run The Program

     Make a backup copy of the distribution disk.  If Pygmy is distributed 
in a ZIP file, unzip it.  If you are going to run from a hard disk, set up 
a directory and copy all of the files to that directory as in the following 
example. 

           C:\>md pyg 
           C:\>cd pyg 
           C:\PYG\>copy a:*.*

    Then bring up Pygmy by typing
           C:\PYG\>pygmy

     In previous versions, most of the documentation was in block files.  
Version 1.3 contains only 3 files other than the program itself.  One is a 
block file, PYGMY.SCR, which contains all the source code.  Another is a 
regular text file, PYGMY.TXT (the file you are currently reading), which is 
readable with TYPE or LIST or just about any text editor.  The last file is 
YOURFILE.SCR and contains 8 blank blocks all ready for you to play with.

     If you are reading this, then you probably know everything you need to 
know to read PYGMY.TXT.  To read the source code, bring up Pygmy and then 
use Pygmy's editor to browse through the block file PYGMY.SCR.  To start at 
the beginning, make sure Caps Lock is on, then type    

           0 EDIT    

(end all commands by pressing <Enter>).  Then just start browsing with the 
PgDn & PgUp keys.  To get out of the editor press Esc.  To get back in 
where you left off, type  

           ED

   To skip to a particular screen, press Esc to get out of the editor and 
then type    n EDIT    where n is the screen you want to jump to. To see 
what files have been opened automatically, get out of the editor and type   

           .FILES



                              CONFIG.SYS file

   If you get error messages when you try to open files, it probably means 
that your CONFIG.SYS file is not allowing enough files.  Change or add a 
"FILES=" statement to CONFIG.SYS so it says  FILES=20 then reboot and try 
again.  (As shipped PYGMY.COM tries to open only 2 files automatically, so 
this should rarely be a problem.)


            If You Have Trouble Using Pygmy With Your Monitor

   Version 1.3 (as did version 1.2) of Pygmy automatically sets itself up 
to match the monitor you are using.  This should work with any MS-DOS or 
PC-DOS computer that uses video display memory at either $B0000 or $B8000
(like normal IBM PCs and compatibles do).


Chapter 7               If You Are New to Forth

     Could/should this manual teach you Forth?  I don't know.  Probably 
only YOU can teach yourself Forth.  Maybe something can be done to make your 
job easier.  I think the very best way for you to do it is to work your way 
through the book Starting Forth by Leo Brodie.  It should be available from 
the Forth Interest Group (see phone number below).  It's not ready as I 
write this, but look for an upcoming book by Kent Peterson that will teach 
you Forth with examples written specifically for Pygmy.

     I didn't design Pygmy to be a teaching Forth, but it does have some 
advantages:  (1) it doesn't cost you a fortune (2) the entire source code 
is included (3) it is small enough that you have a chance to grasp it - it 
shouldn't be too intimidating (4) meta-compiling, using Pygmy, is the 
easiest I have ever seen (5) I am available to answer questions via GEnie 
and, thereby, a number of other bulletin boards (or even via the U.S. 
Postal Service - in which case a SASE might facilitate assistance to 
beginners).

     If you want to try it without a book, then read all of the 
documentation and read the source code as well.  Try out simple examples.  
Join FIG and read Forth Dimensions.  Then get a book, like you should have 
done to begin with.  Then read everything again and try out more examples.  
There is no substitute for doing your own experimenting. The word SEE may 
help.  To examine the internals of a word or data structure, use DUMP or 
DU.  Make heavy use of the glossary. The stack comments are most helpful, 
showing what goes into a word and what comes out.


Chapter 8             What Was New With Version 1.2

   Some bugs have been fixed.  Specifically,  <   &   >   did not work
in all cases but should now be fixed.  Also,  /  was accidentally doing
an unsigned divide because I had cleared register DX rather than sign
extending register AX into it.  Now / does a signed division,
truncating toward zero  ( eg    -3  2  /  returns  -1  ) rather than
flooring.  I don't much care whether division is floored or truncated
toward zero so I left it the way the 8088/8086 IDIV instruction does it.

   U/   has been added so there is still an unsigned divide available.

   The various MODs are still unsigned, but have been renamed to
reflect that fact.

   The type of video display is determined automatically.
  
   BOOT is DEFER'd to make it easy to customize ( e.g. ' MYAPP IS BOOT ).

   Words that return flags are now smaller and faster - based on Robert 
Berkey's code.