home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / f / forthmac / !Forthmacs / docs / ascii / convention < prev    next >
Encoding:
Text File  |  1997-05-01  |  7.3 KB  |  227 lines
  1.  
  2. General Information
  3. *******************
  4.  
  5.  
  6. Getting Started
  7. ===============
  8.  
  9. Before anything else you should always make a backup of your "Working Disk" 
  10. archive called WorkDisc.  
  11.  
  12. All "Working Disks" are ZIP (deflated) archives, they hold the complete 
  13. directory tree including RISC OS file attributes in one single file called 
  14. 'WorkDisc' .  This archive is packed using ZIP, you should use Spark for 
  15. unpacking (distributed discs come complete with SparkPlug).  
  16.  
  17. This makes is easy to deliver RISC OS Forthmacs via BBS or other email media.  
  18. In addition to this advantage, the zipped archives can be used by different 
  19. computers on other platforms.  
  20.  
  21. To install !Forthmacs on your harddisk just copy the !Forthmacs directory 
  22. inside the 'WorkDisc' .  
  23.  
  24. You can of course run RISC OS Forthmacs from the disk, but that will be not so 
  25. much fun even with RISC OS Forthmacs internal file-caching.  The RISC OS 
  26. Version should be 3.1 or later, earlier versions do run but miss some 
  27. features.  
  28.  
  29. RISC OS Forthmacs needs at least about 300 kByte of ram but 512K to 2MB are 
  30. much better.  
  31.  
  32. In the main directory <!Forthmacs> you will see some files, 
  33. 'risc_os.bin.run.forth' is the basic 'obey' file to start RISC OS Forthmacs 
  34. (risc_os.bin.Forthmacs).  It looks something like this: 
  35.     
  36.     Wimpslot -min 1024K
  37.     RMEnsure ColourTrans    0.52 RMLoad System:Modules.Colours
  38.     RMEnsure ColourTrans    0.52 Error Forthmacs needs ColourTrans 0.52 or later
  39.     Set Forthmacs$Path @.,<Forthmacs$Dir>.,<Forthmacs$Dir>.tools.
  40.     Set Forthmacs$wimpmode 27
  41.     Forthmacs:risc_os.bin.Forthmacs %0
  42.     
  43. The first line sets the 'Wimpslotsize', the last calls the forth binary.  
  44.  
  45.  
  46. %0 stands for the first parameter, this can be a filename that 
  47. RISC OS Forthmacs will immediatly start to interpret.  If this parameter isn't 
  48. set, 'auto ' is the default.  Note: This would be auto.fth on other 
  49. implementations.  
  50.  
  51. 'Set Forthmacs$Path @.,<Forthmacs$Dir>.,<Forthmacs$Dir>.tools.' will tell 
  52. RISC OS Forthmacs where to find it's files.  In target applications you should 
  53. set this path accordingly.  
  54.  
  55. 'Set Forthmacs$vidmode 27' tells the terminal: about the wanted video mode, 
  56. the default is UNSET .  This doesn't swich the video mode, all others are 
  57. accepted as RISC OS 3.1 wimpmodes.  The 3.5 mode styles will not be supported, 
  58. future versions will run in WIMP.  
  59.  
  60.  
  61. Updating
  62. ========
  63.  
  64. To make updating easy and to keep net-costs low, all RISC OS Forthmacs tools, 
  65. applications, updates and add ons will follow a common strategy: They are now 
  66. also zip/deflated archives holding only the files needed.  
  67.  
  68. The ZIP archives holding the "Working disc" are updated when major 
  69. improvements took place and the add on files use more than 100kB.  
  70.  
  71. When you have got an update or an application archive you just copy the 
  72. !Forthmacs directory inside the archive over the original !Forthmacs 
  73. application directory.  When starting RISC OS Forthmacs later, sometimes some 
  74. installing routines will be run if necessary.  These routines will be found in 
  75. Forthmacs:risc_os.installjob 
  76.  
  77. Hope this improves updating :-) 
  78.  
  79.  
  80. Features
  81. ========
  82.  
  83. 32-bit stacks and addresses 
  84.  
  85. StrongARM optimised code 
  86.  
  87. structured source-code-ready decompilation 
  88.  
  89. macro assembler and disassembler 
  90.  
  91. Source-code-level debugging/tracing/single stepping 
  92.  
  93. Assembly language debugging/tracing/single-stepping 
  94.  
  95. Command line editing with interactive history editor 
  96.  
  97. command completion 
  98.  
  99. callfinder 
  100.  
  101. Operating system independent file system interface 
  102.  
  103. operating system interface compiler 
  104.  
  105. strings 
  106.  
  107. crash resistance ( also in multitasking ) 
  108.  
  109. run-time search order specification 
  110.  
  111. fast and effective cooperative multitasking 
  112.  
  113. runtime profiler tool 
  114.  
  115. on-line documentation available (ASCII and HTML) 
  116.  
  117. Assembly language debugging/tracing/single-stepping 
  118.  
  119. full ANS Floating and Floating Extended wordsets 
  120.  
  121. complete source code (optional) 
  122.  
  123. multilingual catch & throw messages 
  124.  
  125. StrongED-4 Forth-mode with search engine 
  126.  
  127. xmodem and serial interface tool 
  128.  
  129.  
  130. Upper Case vs. Lower Case
  131. =========================
  132.  
  133. In the older manuals Forth words were written in upper case LIKE THIS.  This 
  134. was done to make those words stand out from the rest of the text.  The 
  135. formatter now prints those keywords in bold-typewriter font like forth. 
  136.  
  137. When you type the Forth words, you should use lower case as shown in the 
  138. glossary.  Also, Forth source code in files should be in lower case.  
  139.  
  140. If you need to use upper case, read about the variable caps in the Master 
  141. Glossary.  
  142.  
  143. Note: There are very rare occasions when the formatting program doesn't switch 
  144. into bold-typewriter font, so don't worry if you find a keyword in upper case.  
  145.  
  146.  
  147. Master Glossary
  148. ===============
  149.  
  150. Reference documentation for most RISC OS Forthmacs words appears in the 
  151. chapter "Master Glossary".  The key to the glossary notation is the chapter 
  152. "Glossary Notation".  The Master Glossary is sorted by alphabetical order.  
  153. The chapter "Glossary Functional Index" lists the words of the Master Glossary 
  154. grouped by function.  
  155.  
  156. Documentation for the ARM-Assembler and Multitasking can be found in special 
  157. chapters.  
  158.  
  159.  
  160. Loading Files
  161. =============
  162.  
  163. To interpret Forth source code from a file named, for example, 'art ' , use 
  164. fload like: 
  165.     fload art
  166. As you probably know the directories in Risc_OS are seperated by a dot like 
  167.     risc_os.bin.Forthmacs
  168. Deep inside RISC OS Forthmacs, pathnames ending with 
  169. .DOC .TXT .EXE .FTH .IND .DAT are accepted as DOS-style pathnames and 
  170. converted to RISC OS pathnames.  This allows more portable code with 
  171. filenames.  
  172.  
  173. To edit files, use your favorite editor, this works very fine with Deskedit, 
  174. Zap, StrongED, Edit uEmacs or others.  
  175.  
  176. To learn more about files, read the chapter "Files".  
  177.  
  178.  
  179. Saving an Executable Image
  180. ==========================
  181.  
  182. After creating new definitions and changing things you may want to save an 
  183. executable file that includes those changes and additions.  
  184.     "" filename save-forth
  185. will do this for you.  The file will be added to the current directory unless 
  186. the pathname is explicitly specified.  The new file will be of the absolute 
  187. filetype.  
  188.  
  189. From now on, you can call up your own version of Forth with: 
  190.     * run filename
  191. In fact, you can automatically interpret Forth source code files as well when 
  192. you first start up Forth.  From supervisor ( or 'obey' file): 
  193.     * run filename  Forthmacs:sourcefile
  194.  
  195.  
  196. Interrupting a Listing
  197. ======================
  198.  
  199. When Forth is displaying a multi-line listing on the screen, in most cases the 
  200. listing may be interrupted by typing any character.  If the character is "q" 
  201. (for quit), the listing will be aborted.  If the character is anything other 
  202. than "q", the listing will pause, displaying a "More?" prompt at the bottom of 
  203. the screen.  
  204.  
  205. When the listing is paused, typing a "q" will cause the listing to be aborted, 
  206. and typing any other character will cause it to continue.  
  207.  
  208.  
  209. Copying the Manual
  210. ==================
  211.  
  212. The manual is copyrighted, and permission to copy in any way it is not 
  213. granted.  If you need extra copies, contact the RISC OS Forthmacs support.  
  214. You can copy and give away the complete Working disk, but not the manual.  
  215.  
  216. Online manuals are available on special request, both dvi and ascii files are 
  217. available at the moment.  
  218.  
  219. RISC OS Forthmacs support: 
  220.     Hanno Schwalm
  221.     Holunderstr. 10
  222.     D-28207 Bremen
  223.     Germany
  224.     Tel. 49 421 459996
  225.     schwalm@bre.winnet.de
  226.  
  227.