
General Information
*******************


Getting Started
===============

Before anything else you should always make a backup of your "Working 
Disk" archive called WorkDisc.  

All "Working Disks" are ZIP (deflated) archives, they hold the 
complete directory tree including RiscOS file attributes in one single 
file called 'WorkDisc' .  This archive is packed using SparcFS, you 
should use Sparc for unpacking (distributed discs come complete with 
Sparc).  

This makes is easy to deliver Risc-OS Forthmacs via BBS or other email 
media.  In addition to this advantage, the zipped archives can be used 
by different computers on other platforms.  

To install !Forthmacs on your harddisk just copy the !Forthmacs 
directory inside the 'WorkDisc' .  

You can of course run Risc-OS Forthmacs from the disk, but that will 
be not so much fun even with Risc-OS Forthmacs internal file-caching.  
The RiscOS Version should be 3.1 or later, earlier versions do run but 
miss some features.  

Risc-OS Forthmacs needs at least about 300 kByte of ram but 512K to 
2MB are much better.  

In the main directory <!Forthmacs> you will see some files, 
'bin.run.forth' is the basic 'obey' file to start Risc-OS Forthmacs 
(risc_os.bin.Forthmacs).  It looks something like this: 
    
    Wimpslot -min 1024K
    RMEnsure ColourTrans    0.52 RMLoad System:Modules.Colours
    RMEnsure ColourTrans    0.52 Error Forthmacs needs ColourTrans 0.52 or later
    If "<Wimp$ScrapDir>"="" then ERROR Forthmacs needs Wimp$ScrapDir for swapping
    Set Forthmacs$Path @.,<Forthmacs$Dir>.,<Forthmacs$Dir>.tools.
    Set Forthmacs$wimpmode 27
    Forthmacs:risc_os.bin.Forthmacs %0
    
The first line sets the 'Wimpslotsize', the last calls the forth 
binary.  


%0 stands for the first parameter, this can be a filename that 
Risc-OS Forthmacs will immediatly start to interpret.  If this 
parameter isn't set, 'auto ' is the default.  Note: This would be 
auto.fth on other implementations.  

'Set Forthmacs$Path @.,<Forthmacs$Dir>.,<Forthmacs$Dir>.tools.' will 
tell Risc-OS Forthmacs where to find it's files.  In target 
applications you should set this path accordingly.  

'Set Forthmacs$vidmode 27' tells the TERMINAL: about the wanted video 
mode, the default is UNSET .  This doesn't swich the video mode, all 
others are accepted as Risc-OS 3.1 wimpmodes.  The 3.5 mode styles 
will not be supported, future versions will run in WIMP.  


Updating
========

To make updating easy and to keep net-costs low, all Risc-OS Forthmacs 
tools, applications, updates and add ons will follow a common 
strategy: They are gzipped/tar archives holding only the files needed.  

The Sparc file-archives holding the "Working disc" are updated when 
major improvements took place and the add on files use more than 
100kB.  

When you have got an update or an application archive you just copy 
this archive to the 
    risc_os.installing
directory and run Risc-OS Forthmacs, the installing is done 
automatically for you.  

Hope this improves updating :-) 


Features
========

32-bit stacks and addresses 

structured decompilation 

macro assembler and disassembler 

Source-level debugging/tracing/single stepping 

Command line editing with interactive history editor 

command completion 

callfinder 

Operating system independent file system interface 

operating system interface compiler 

strings 

crash resistance ( also in multitasking ) 

run-time search order specification 

cooperative multitasking 

runtime profiler 

on-line documentation 

Assembly language debugging/tracing/single-stepping 

Floating point (optional) 

complete source code (optional) 

xmodem and serial interface tool 


Upper Case vs. Lower Case
=========================

In the older manuals Forth words were written in upper case LIKE THIS.  
This was done to make those words stand out from the rest of the text.  
The formatter now prints those keywords in bold-typewriter font like 
FORTH. 

When you type the Forth words, you should use lower case as shown in 
the glossary.  Also, Forth source code in files should be in lower 
case.  

If you need to use upper case, read about the variable CAPS in the 
Master Glossary.  

Note: There are very rare occasions when the formatting program 
doesn't switch into bold-typewriter font, so don't worry if you find a 
keyword in upper case.  


Master Glossary
===============

Reference documentation for most Risc-OS Forthmacs words appears in 
the chapter "Master Glossary".  The key to the glossary notation is 
the chapter "Glossary Notation".  The Master Glossary is sorted by 
alphabetical order.  The chapter "Glossary Functional Index" lists the 
words of the Master Glossary grouped by function.  

Documentation for the ARM-Assembler and Multitasking can be found in 
special chapters.  


Loading Files
=============

To interpret Forth source code from a file named, for example, 'art ' 
, use FLOAD like: 
    fload art
As you probably know the directories in Risc_OS are seperated by a dot 
like 
    risc_os.bin.Forthmacs
Deep inside Risc-OS Forthmacs, pathnames ending with 
.DOC .TXT .EXE .FTH .IND .DAT are accepted as DOS-style pathnames and 
converted to RiscOS pathnames.  This allows more portable code with 
filenames.  

To edit files, use your favorite editor, this works very fine with 
Deskedit, Zap, StrongED, Edit uEmacs or others.  

To learn more about files, read the chapter "Files".  


Saving an Executable Image
==========================

After creating new definitions and changing things you may want to 
save an executable file that includes those changes and additions.  
    "" filename save-forth
will do this for you.  The file will be added to the current directory 
unless the pathname is explicitly specified.  The new file must be of 
the absolute filetype.  

From now on, you can call up your own version of Forth with: 
    * run filename
In fact, you can automatically interpret Forth source code files as 
well when you first start up Forth.  From supervisor ( or 'obey' 
file): 
    * run filename  sourcefile


Interrupting a Listing
======================

When Forth is displaying a multi-line listing on the screen, in most 
cases the listing may be interrupted by typing any character.  If the 
character is "q" (for quit), the listing will be aborted.  If the 
character is anything other than "q", the listing will pause, 
displaying a "More?" prompt at the bottom of the screen.  

When the listing is paused, typing a "q" will cause the listing to be 
aborted, and typing any other character will cause it to continue.  


Copying the Manual
==================

The manual is copyrighted, and permission to copy in any way it is NOT 
granted.  If you need extra copies, contact the Risc-OS Forthmacs 
support.  You can copy and give away the complete Working disk, but 
not the manual.  

Online manuals are available on special request, both dvi and ascii 
files are available at the moment.  

Risc-OS Forthmacs support: 
    Hanno Schwalm
    Holunderstr. 10
    D-28207 Bremen
    Germany
    Tel. 49 421 459996
    support@4thware.winnet.de

