<!-- Forthmacs Formatter generated HTML V.2 output -->
<html>
<head>
<title>General Information</title>
</head>
<body>
<h1>General Information</h1>
<hr>
<p>
<p>
<h2>Getting Started</h2>
<p>
Before anything else you should always make a backup of your "Working Disk" 
archive called WorkDisc.  
<p>
All "Working Disks" are ZIP (deflated) archives, they hold the complete 
directory tree including RISC OS file attributes in one single file called <em>WorkDisc</em> 
.  This archive is packed using ZIP, you should use Spark for unpacking 
(distributed discs come complete with SparkPlug).  
<p>
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.  
<p>
To install !Forthmacs on your harddisk just copy the !Forthmacs directory inside 
the <em>WorkDisc</em> .  
<p>
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 RISC OS Version 
should be 3.1 or later, earlier versions do run but miss some features.  
<p>
RISC OS Forthmacs needs at least about 300 kByte of ram but 512K to 2MB are much 
better.  
<p>
In the main directory &lt;!Forthmacs&gt; you will see some files, <em>risc_os.bin.run.forth</em> 
is the basic 'obey' file to start RISC OS Forthmacs (risc_os.bin.Forthmacs).  It 
looks something like this: 
<p><pre>  </pre><p>
<p><pre>  Wimpslot -min 1024K</pre><p>
<p><pre>  RMEnsure ColourTrans    0.52 RMLoad System:Modules.Colours</pre><p>
<p><pre>  RMEnsure ColourTrans    0.52 Error Forthmacs needs ColourTrans 0.52 or later</pre><p>
<p><pre>  Set Forthmacs$Path @.,&lt;Forthmacs$Dir&gt;.,&lt;Forthmacs$Dir&gt;.tools.</pre><p>
<p><pre>  Set Forthmacs$wimpmode 27</pre><p>
<p><pre>  Forthmacs:risc_os.bin.Forthmacs %0</pre><p>
<p><pre>  </pre><p>
The first line sets the 'Wimpslotsize', the last calls the forth binary.  
<p>
<p>
%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, <em>auto </em> 
is the default.  Note: This would be auto.fth on other implementations.  
<p>
<em>Set Forthmacs$Path @.,&lt;Forthmacs$Dir&gt;.,&lt;Forthmacs$Dir&gt;.tools.</em> 
will tell RISC OS Forthmacs where to find it's files.  In target applications 
you should set this path accordingly.  
<p>
<em>Set Forthmacs$vidmode 27</em> tells the <code><A href="_smal_BG#31E">terminal:</A></code> 
about the wanted video mode, the default is <strong>unset</strong> .  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.  
<p>
<p>
<h2>Updating</h2>
<p>
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 now 
also zip/deflated archives holding only the files needed.  
<p>
The ZIP archives holding the "Working disc" are updated when major improvements 
took place and the add on files use more than 100kB.  
<p>
When you have got an update or an application archive you just copy the 
!Forthmacs directory inside the archive over the original !Forthmacs application 
directory.  When starting RISC OS Forthmacs later, sometimes some installing 
routines will be run if necessary.  These routines will be found in 
Forthmacs:risc_os.installjob 
<p>
Hope this improves updating :-) 
<p>
<p>
<h2>Features</h2>
<p>
32-bit stacks and addresses 
<p>
StrongARM optimised code 
<p>
structured source-code-ready decompilation 
<p>
macro assembler and disassembler 
<p>
Source-code-level debugging/tracing/single stepping 
<p>
Assembly language debugging/tracing/single-stepping 
<p>
Command line editing with interactive history editor 
<p>
command completion 
<p>
callfinder 
<p>
Operating system independent file system interface 
<p>
operating system interface compiler 
<p>
strings 
<p>
crash resistance ( also in multitasking ) 
<p>
run-time search order specification 
<p>
fast and effective cooperative multitasking 
<p>
runtime profiler tool 
<p>
on-line documentation available (ASCII and HTML) 
<p>
Assembly language debugging/tracing/single-stepping 
<p>
full ANS Floating and Floating Extended wordsets 
<p>
complete source code (optional) 
<p>
multilingual catch &amp; throw messages 
<p>
StrongED-4 Forth-mode with search engine 
<p>
xmodem and serial interface tool 
<p>
<p>
<h2>Upper Case vs. Lower Case</h2>
<p>
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 <code><A href="_smal_BO#236">forth</A>.</code> 
<p>
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.  
<p>
If you need to use upper case, read about the variable <code><A href="_smal_BB#199">caps</A></code> 
in the Master Glossary.  
<p>
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.  
<p>
<p>
<h2>Master Glossary</h2>
<p>
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.  
<p>
Documentation for the ARM-Assembler and Multitasking can be found in special 
chapters.  
<p>
<p>
<h2>Loading Files</h2>
<p>
To interpret Forth source code from a file named, for example, <em>art </em> , 
use <code><A href="_smal_BH#22F">fload</A></code> like: 
<p><pre>  fload art</pre><p>
As you probably know the directories in Risc_OS are seperated by a dot like 
<p><pre>  risc_os.bin.Forthmacs</pre><p>
Deep inside RISC OS Forthmacs, pathnames ending with <strong>.doc .txt .exe .fth .ind .dat</strong> 
are accepted as DOS-style pathnames and converted to RISC OS pathnames.  This 
allows more portable code with filenames.  
<p>
To edit files, use your favorite editor, this works very fine with Deskedit, 
Zap, StrongED, Edit uEmacs or others.  
<p>
To learn more about files, read the chapter "Files".  
<p>
<p>
<h2>Saving an Executable Image</h2>
<p>
After creating new definitions and changing things you may want to save an 
executable file that includes those changes and additions.  
<p><pre>  "" filename save-forth</pre><p>
will do this for you.  The file will be added to the current directory unless 
the pathname is explicitly specified.  The new file will be of the absolute 
filetype.  
<p>
From now on, you can call up your own version of Forth with: 
<p><pre>  * run filename</pre><p>
In fact, you can automatically interpret Forth source code files as well when 
you first start up Forth.  From supervisor ( or 'obey' file): 
<p><pre>  * run filename  Forthmacs:sourcefile</pre><p>
<p>
<p>
<h2>Interrupting a Listing</h2>
<p>
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.  
<p>
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.  
<p>
<p>
<h2>Copying the Manual</h2>
<p>
The manual is copyrighted, and permission to copy in any way it is <code><A href="_smal_AF#2A5">not</A></code> 
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.  
<p>
Online manuals are available on special request, both dvi and ascii files are 
available at the moment.  
<p>
RISC OS Forthmacs support: 
<p><pre>  Hanno Schwalm</pre><p>
<p><pre>  Holunderstr. 10</pre><p>
<p><pre>  D-28207 Bremen</pre><p>
<p><pre>  Germany</pre><p>
<p><pre>  Tel. 49 421 459996</pre><p>
<p><pre>  schwalm@bre.winnet.de</pre><p>
<p>
</body>
</html>
