
                  [PilotFORTH icon] Neal Bridges' PilotFORTH
                                       
   Latest Release - About PilotFORTH - About Forth - Quick Start -
   Example Code - Related Information & Contributed Code - FAQ
     _________________________________________________________________
   
                          BEGIN COFFEE AWAKE UNTIL
     _________________________________________________________________
   
   VERSION 0.6.1 NOW AVAILABLE!
     * DOWNLOAD PilotFORTH version 0.6.1
       [Book]
     * Read the PilotFORTH documentation (HTML format)
     * Read the FAQ
     _________________________________________________________________
   
Change History:

     * (1998.1.25) Version 0.6.1 released. Fixed a bug in the new input
       handler.
     * (1998.1.25) Version 0.6.0 released.
          + Default text input is now via a standard PalmOS field. This
            allows keyboard popup and editing during an interactive
            session. Let me know if there are any problems with this.
     * (1998.1.14) Added struct to the Example Code section. Examples of
       its use will follow.
     * (1998.1.12) Version 0.5.8 released.
          + Added DU<.
          + Added case and core-ext to the Example Code section.
          + Updated double.
          + Updated core.
          + Updated float.
     * (1997.12.10) Updated the PilotFORTH documentation.
     * (1997.12.8) Improved the speed of the words in tools-ext.4th.
     * (1997.12.7) Fixed minor bugs in tools-ext.4th.
     * (1997.12.6) Created tools-ext.4th. This defines the standard
       conditional compilation words [IF], [ELSE], and [THEN]. It's
       available in the Example Code section.
     * (1997.12.1) Updated floating point elective float.4th.
          + Fixed a bug in F<.
          + Added REPRESENT.
     * (1997.11.22) Version 0.5.7 released.
          + Floating point support! The Standard FLOAT wordset is
            provided as an elective file, float.4th. From the FLOAT EXT
            wordset, FS. is also provided. These floating point words
            work on both old and new Pilot ROMs. Note that float.4th
            requires core and double to be loaded.
          + Other new features: REFILL, ABORTVECTOR, and PARSEVECTOR;
            documentation to follow shortly.
     * (1997.10.27) Version 0.5.3 released. Fixed a bug related to using
       EVALUATE with strings containing INCLUDE.
     * (1997.10.14) Version 0.5.2 released. For those of you having
       problems with AppHack, I've included a fix. It seems that AppHack
       uses a huge amount of stack every time an event is handled, and I
       have to compensate for that. There may be other hacks that take
       similar liberties; hopefully this fix catches them as well.
     * (1997.10.11) Version 0.5.1 released. Fixed a bug in the
       compilation of double literals.
     * (1997.10.9) Version 0.5.0 released. The standard DOUBLE wordset is
       now supported. A double.4th supplementary file is also provided
       with this release.
     * (1997.9.25) Added circle, rectangle, and rounded-rectangle
       primitives to the graphics example code.
     * (1997.9.25) More new contributed code!
     * (1997.9.19) New contributed code! Have a look at the Related
       Information section.
     * (1997.9.16) Version 0.4.5 released. Fixed small bugs in >NUMBER
       and WORD. Supplied a new version of the core.4th electives file
       with this release.
     * (1997.9.11) Version 0.4.4 released. Fixed a bug related to finding
       a file when it was the first memo in the database. Incorporated
       several other minor changes.
     * (1997.9.6) Updated implementation document. Wrote sections
       defining implementation-defined options and ambiguous conditions,
       as the ANSI Standard requires.
     * (1997.9.6) Version 0.4.3 released. Reversed the increased
       dataspace for Palm OSv2 models; I suspect it of causing problems
       with AppHack.
     * (1997.9.4) Version 0.4.2 released. Since 0.4.0:
          + Added >BYTE, RP!, SP!, and AHEAD words. RP! and SP! can be
            used as the foundation of an optional CATCH/THROW module,
            should anyone be so inclined as to write one.
          + Increased the available dataspace (this change only affects
            the PalmPilot OSv2 ROMs).
          + Created documentation & FAQ and placed them on-line.
          + Wrote new example code icon, which demonstrates resource and
            bitmap access.
          + Added developer's assistance in the form of a safe module
            (available in the Example Code section).
     * (1997.9.3) Created documentation.
     * (1997.9.2) Created a FAQ.
     * (1997.8.31) Added safe to the example code section. safe adds
       error-preventing assertions to a number of CORE words.
     * (1997.8.30) Wrote new example code icon, which demonstrates
       resource and bitmap access.
     * (1997.8.27) Added a Related Information section to this page.
     * (1997.8.26) Version 0.4.0 released:
          + Performed a substantial code review. The system now
            successfully passes John Hayes' coretest suite of 636 tests
            for the ANS CORE wordset, which permits an unprecedented
            level of confidence in the product.
          + Included a CORE electives file which provides in source those
            words from the CORE wordset (and a few others) not currently
            present in the kernel.
     * (1997.8.23) Version 0.3.5 released:
          + Added +LOOP and LEAVE. The CORE wordset is now well
            represented, with what words not present to be provided
            shortly as an elective.
          + Improved the speed of the system (already fast!) by as much
            as 20% on certain operations.
     * (1997.8.19) Version 0.3.3 released:
          + Added EVALUATE (ANS CORE wordset).
          + Added VERSION ( -- c-addr u), returning a string containing
            the version number of the program. Updated the startup
            example code.
          + Fixed a bug in WHILE.
          + Changed handling of record locking in the memo database to
            avoid certain problem situations.
     * (1997.8.19) PalmOS SysTraps DOC file created and made available,
       listing all PalmOS version 1 and version 2 systraps with their
       respective numbers. An ASCII version is available. A J-FILE
       version is also available, courtesy of Richard Hartman. Converted
       the .PRC 1997.8.20 to a .ZIP file; certain browsers were
       mis-interpreting the .PRC file as text and corrupting it.
     * (1997.8.17) Version 0.3.2 released:
          + Added the most-oft-requested feature: pagination for WORDS.
            Tap on the screen to advance one line; graffiti return to
            scroll without further pauses; any other character to advance
            one page. Along with this comes MORE: 1 MORE starts
            pagination, 0 MORE ends it. With this you can paginate your
            own output.
          + Found a fix for the About Box issue that was cropping up on
            the older Pilots.
          + Created a turtle-graphics example code snippet.
          + Repaired several miscellaneous bugs..
     * (1997.8.14) Added an Example code section.
     * (1997.8.13) Version 0.3.0 released:
          + Added support for source in files (memos). See the Example
            code section.
          + The system now checks dynamic RAM before establishing itself,
            and leaves 4K behind for proper system operation.
          + A new constant, LIMIT, reports the highest allowable address
            in the PilotFORTH's address space.
          + Added MEM ( -- ud1 ud2 ). This reports MemHeapFreeBytes for
            the heap containing the dynamic RAM. ud1 is the largest block
            availble, and ud2 is the total free RAM.
     * (1997.8.10) Version 0.2.2 released:
          + Repaired a bug in SYSTRAP.
          + Repaired a bug in /.
          + New definitions are now automatically saved between sessions.
          + Added a new pulldown menu: Program, with options Abort and
            Save. Save updates the saved dictionary immediately, rather
            than waiting for the session to end. Abort brings a running
            program back to the interpreter.
          + Added FORGET. FORGET name resets the dictionary to a point
            just before name was defined.
     * (1997.8.7) Version 0.1.0 released. First public release, intended
       for discussion purposes.  Implements most of the CORE wordset.
     * (1997.7.18) Registered p4th creator ID. Began development.
     _________________________________________________________________
   
ABOUT PilotFORTH

   PilotFORTH is a 16-bit on-board native-code ANSI-subset Forth compiler
   for the 3Com PalmPilot/IBM WorkPad series of handheld PDAs. It is
   intended to comply with the ANSI standard for Forth.
   
   PilotFORTH compiles Standard Forth directly to machine language,
   providing far greater speed than traditional threaded implementations.
   
   PilotFORTH is freeware, but is not in the public-domain. Programs
   created with it are freely distributable; I only ask that should you
   market a program written with this or any later version of PilotFORTH,
   please provide me with a registered copy.
   
   Please bear in mind that this program is not warranted in any way to
   perform any specific function, or in fact to be fit for any purpose at
   all. It's a programming language, so obviously you can manipulate the
   device with it. Use it at your own risk, and always keep backups--and
   keep your paperclip handy.
     _________________________________________________________________
   
ABOUT FORTH

   Forth is a fabulous language, capable (in the right hands) of compact
   programs, fast execution, and down-to-the-metal control.
   
   The concepts in Forth are straightforward. Subroutines in Forth are
   called words. These words are named and stored in an internal list
   called a dictionary. New words are built from existing words in the
   dictionary. Each new word becomes a first-class object in the system;
   this makes Forth extensible.
   
   Forth compiles code much faster than any C compiler, while still
   incorporating such optimization techniques as function inlining and
   peephole optimization, with execution speeds (for native-code Forths
   such as PilotFORTH) that compare directly to speeds obtained by C
   programs.
   
   The basic unit of information in Forth is the integer, or cell. In
   PilotFORTH, the cells are 16-bits wide. Forth, by default, does no
   type checking. Cells are signed or unsigned based solely on context.
   
   Words are executed implicitly (you just enter the name of the word).
   Parameters are passed to and between words via Forth's two
   last-in-first-out stacks, the data and the return stack.
   
   There are any number of excellent sites for more information on Forth;
   have a look, for instance, at www.forth.org.
     _________________________________________________________________
   
QUICK START

   To load the PilotFORTH .prc executable file into your Pilot/WorkPad,
   unzip the distribution .zip file, and use the Install option in the
   Desktop software that ships with the device to transfer the .prc file
   into the PDA.
   
   When starting PilotFORTH, you will be presented with a simple
   underline-style cursor. This is PilotFORTH's interpreter. The line
   editor is simple: it supports backspace, previous-word-delete (via
   cursor-left), retrieve-last-line (via the page-up button), and
   erase-line (via the page-down button). Text input is in bold type,
   output in normal type.
   Try this (in either upper- or mixed-case; PilotFORTH doesn't care):
3  5  +  .
10000  22  7  */  .

: .BINARY   BASE @ >R  2 BASE !  .  R> BASE ! ;
42 .BINARY

: HELLO  ." Hello, world!"  CR ;
HELLO

: ALLCHARS  256 0 DO I EMIT LOOP CR ;
ALLCHARS

: ALARM  256 5 * 41524 SYSTRAP DROP ;
ALARM

: COUNTNINE  10 1 DO I . LOOP CR ;
COUNTNINE

: BIGSHOW   PAGE  HELLO  COUNTNINE  ALLCHARS  ALARM  ;
BIGSHOW
     _________________________________________________________________
   
EXAMPLE CODE

   Memos beginning with the characters \, space, and a filename are
   considered files by PilotFORTH, and can be INCLUDEd from the
   command-line. A special file, startup, is loaded (if present) at
   initial startup, and at each execution of COLD. Filenames are
   case-sensitive. Note that the first two characters must be backslash
   and space.
   
   Load files in PilotFORTH with INCLUDE filename. Files can be nested to
   any reasonable depth.
   
   Before an example file can be accessed, it must be imported to the
   memopad via the PalmPilot Desktop.
     * core is the loadable electives file for the CORE wordset, provided
       with the current release. Most of the example code below requires
       that core be included first, which normally occurs as part of
       startup.
     * startup is a sample startup file. The startup file loads the first
       time PilotFORTH is run, and at each execution of COLD. Requires
       core.
     * double is the loadable electives file for the DOUBLE wordset,
       provided with the current release.
     * float is the loadable electives file for the FLOAT wordset,
       provided with the current release. Requires core and double.
     * core-ext is a loadable elective containing a number of words from
       the CORE EXT wordset. It is provided with the current release.
     * case is the CASE..OF..ENDOF..ENCASE structure as described in the
       ANS docs.
     * struct provides a lexicon for structured data. Examples of its use
       will follow shortly.
     * tools-ext defines [IF], [ELSE], and [THEN] from the standard TOOLS
       EXT wordset. These words allow for conditional compilation.
     * safe adds error-preventing assertions to a number of CORE words.
       These can be useful during development.
     * icon demonstrates accessing resources, and displaying bitmaps.
     * fib is a benchmark courtesy of Andrew Low.
     * graphics provides a few simple graphics primitives: line, point,
       circle, rectangle, and rounded-rectangle.
     * trig provides sin and cos words.
     * turtle defines a turtle-graphics lexicon, after the graphics words
       in LOGO. It requires trig and graphics above.
     * turtledemo demonstrates turtle.
     * snowflake is another demo for turtle.
     * backlight is a small lexicon for controlling the backlight on the
       Palm Personal (and later) models.
       Use 1 backlight to switch the light on, 0 backlight to switch it
       off, and backlight? to query its status.
     * alarm is the example code from the Quick Start section, expanded
       for clarity.
     * random demonstrates calls to the pseudo-random number generator in
       the Pilot ROM. rand returns a number from 0 to 32767. To seed the
       generator (for repeatable sequences), feed a double number into
       seed.
     * See also the Related Information & Contributed Code section for
       further examples of PilotFORTH code.
     _________________________________________________________________
   
RELATED INFORMATION & CONTRIBUTED CODE

  Related Information
  
     * ANSI Standard Forth Information.
     * Documentation for the PalmOS system calls, in PDF (Adobe Acrobat)
       format as provided by 3Com.
     * PalmOS version 1 and 2 systraps, listed by number.
          + DOC version
          + ASCII version
          + J-FILE version, courtesy of Richard Hartman.
       
  Contributed Code
  
   Please note that I have not validated any of the contributed code, and
   cannot vouch for its function or accuracy.
     * Georg Bauer has written a collection of PilotFORTH tools and
       library code.
     * A collection of PilotFORTH code, created by G. Wade Johnson.
       Wordsets, extensions, and tools.
     _________________________________________________________________
   
    Neal Bridges, 1997. All rights reserved.
