home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 4 / Amiga Tools 4.iso / tools / developer-tools / assembler / basmify_v1.1 / basmify.doc < prev    next >
Encoding:
Text File  |  1996-02-26  |  8.2 KB  |  261 lines
  1.  
  2.                                   Basmify
  3.                                   =======
  4.                                     1.1
  5.  
  6. ARexx  scripts for using the assembler BAsm of Barfly from within the editor
  7. CygnusED.
  8.  
  9.  
  10.  0. CONTENTS
  11. -------------
  12.  
  13.  1. Disclaimer
  14.  2. Requirements
  15.  3. Installation
  16.  3.1 Options
  17.  3.2 Localization
  18.  4. Usage
  19.  5. Limitations
  20.  6. Author
  21.  7. Credits
  22.  8. History
  23.  
  24.  
  25.  1. DISCLAIMER
  26. ---------------
  27.  
  28. Copyright (c) 1995-1996 by Ulrich Flegel.
  29.  
  30. Permission  is granted to make and distribute verbatim copies of this manual
  31. provided  the  copyright  notice and this permission notice are preserved on
  32. all copies.
  33.  
  34. No  guarantee  of  any  kind  is  given  that the programs described in this
  35. document  are  100% reliable.  You are using this material at your own risk.
  36. The  author  can  not  be made responsible for any damage which is caused by
  37. using these programs.
  38.  
  39. Permission is granted to include this package in Aminet CD-ROMs.
  40.  
  41. None  of  the programs may be included or used in commercial programs unless
  42. by written permission from the author.
  43.  
  44. None  of  the programs may be modified in any way.  For improvements contact
  45. the author.
  46.  
  47. None  of  the  programs  may  be  used  on any machine which is used for the
  48. research,  development,  construction,  testing  or production of weapons or
  49. other  military  applications.  This also includes any machine which is used
  50. for training persons for any of the above mentioned purposes.
  51.  
  52.  
  53.  2. REQUIREMENTS
  54. -----------------
  55.  
  56.  
  57. · Barfly
  58.  
  59. · CygnusEd 3.0 or higher
  60.  
  61. · ARexx
  62.  
  63.  
  64.  3. INSTALLATION
  65. -----------------
  66.  
  67. Copy  the files 'Assemble.ced' and 'NextError.ced' to any directory.  Assign
  68. 'Basmify:'  to  this directory.  If you don't the scripts will not find each
  69. other.   Then you have to change the 'NextError' and 'Assemble' variables in
  70. the scripts to fit the pathnames.
  71.  
  72. Adapt  the BAsmPath variable in the 'Assemble.ced' script to the pathname of
  73. the directory where your BAsm is, so BAsm needs not to be in your path.
  74.  
  75. In  CygnusED  assign  the  scripts  to  two  function  keys (menu:  Special;
  76. DOS/ARexx interface »; Install DOS/ARexx command...), say 'NextError.ced' to
  77. F9 and 'Assemble.ced' to F8.
  78.  
  79. For  initial  reading  and quick usage skip the subsections of chapter 3 and
  80. read on at chapter 4.
  81.  
  82.  
  83.  3.1 OPTIONS
  84. -------------
  85.  
  86. You  may  supply  the  ARexx scripts with some options.  You have to put the
  87. options in the invocation string defined in chapter 3.
  88.  
  89. Because  I  have  no  idea  how  to  request from CygnusEd which language is
  90. currently in use I had to supply a workaround.  The workaround is completely
  91. transparent   because  it  works  like  an  override  of  CygnusEd's  locale
  92. information. The option is named:
  93.  
  94.  LOCALE «Language» ,
  95.  
  96. where  «Language» is the descriptor of the language to be used by the script
  97. (f.i.  deutsch).  Omission of the LOCALE option will enable english language
  98. as long as no CygnusEd-localization-info is available.
  99.  
  100. It  may  be of no great use but you can supply a set of BAsm options via the
  101. scripts.   Normally  you  want  to put these in the source or in environment
  102. variables  used  by  BAsm.  Nevertheless, for testing purposes this might be
  103. handy. Use the following option:
  104.  
  105.  OPT «BAsmOptions»
  106.  
  107. Example «BAsmOptions» would be: -O+ -OW+
  108.  
  109. Due  to  limited parsing abilities of ARexx and to keep the scripts simple I
  110. had to make one assumption:
  111.  
  112. !! The OPT option must be the last of all options supplied to the scripts !!
  113.  
  114. This  should  be  no  great  limitation considered most people won't use OPT
  115. anyway.
  116.  
  117. If you want consistent behaviour regarding localization and options you HAVE
  118. TO supply the same options to both scripts.  This results from the fact that
  119. both scripts may call each other.  I didn't want to use separate environment
  120. variables for configuration and options.  This would easily be possible.  If
  121. there is a big need for this I might implement it.
  122.  
  123. Example:
  124.  
  125.  F8: Assemble.ced  LOCALE deutsch OPT -O+ -OW+
  126.  F9: NextError.ced LOCALE deutsch OPT -O+ -OW+
  127.  
  128. This  configuration  will  set  German language and enable optimization plus
  129. resulting warnings.
  130.  
  131.  
  132.  3.1 LOCALIZATION
  133. ------------------
  134.  
  135. The  release  version  of  Basmify only supports english and German language
  136. messages.
  137.  
  138. To  enhance  Basmify  for  further  languages it is necessary to modify both
  139. scripts.
  140.  
  141. You  have  to  search  for:  «WHEN Language='XXX' THEN».  Mark a block until
  142. «END».   Copy this Block straight on top of the «OTHERWISE» statement of the
  143. nesting «SELECT» statement.
  144.  
  145. Now  replace  in  each  line  of  the  new  block  every «XXX» by a matching
  146. translation.   Look  up the english meanings of the message variables in the
  147. «OTHERWISE» branch.
  148.  
  149. It  is  important  you  replace the correct language descriptor in the «WHEN
  150. Language='XXX'  THEN»  line.   Otherwise  it  is  possible  the localization
  151. informations from CygnusEd wouldn't match (given there is such a support).
  152.  
  153. Don't  forget to translate the messages in both scripts.  In an error case a
  154. fall back to english will occur.
  155.  
  156.  
  157.  4. USAGE
  158. ----------
  159.  
  160. Start  CygnusEd and load the source code you want to assemble.  For assembly
  161. press  F8 (or the key you have assigned 'Assemble.ced' to) in the view where
  162. the  source code is located.  'Assemble.ced' saves automatically any changes
  163. to the source before assembly.
  164.  
  165. 'Assemble.ced'  invokes  BAsm  and  if  no  errors  occurred you will get an
  166. appropriate  message.   If  there  were  errors or warnings you are told and
  167. 'NextError.ced' is invoked automatically to display the first error/warning.
  168.  
  169. Subsequent  key-presses  on  the  'NextError.ced'  assigned  key  result  in
  170. displaying  the  next error/warning.  First all errors are shown, afterwards
  171. all warnings.
  172.  
  173. When all errors/warnings have been shown and you press 'NextError' again you
  174. will be asked if you want to assemble the source again.
  175.  
  176.  
  177.  5. LIMITATIONS
  178. ----------------
  179.  
  180. · The scripts don't yet handle multiple BAsm
  181.  
  182. · The scripts could handle smart language localization if I knew how to find
  183.   out  the  language  CygnusEd  is  currently  using  (any status number for
  184.   this?).
  185.  
  186.  
  187.  6. AUTHOR
  188. -----------
  189.  
  190. If you have any suggestions or bug-reports, feel free to contact me
  191. (e-mail preferred).
  192.  
  193. Ulrich Flegel
  194. e-mail: flegel@ibr.cs.tu-bs.de
  195. irc:    Froody (#amigager)
  196. phone:  ++49-5307-5660
  197.  
  198.  
  199.  7. CREDITS
  200. ------------
  201.  
  202. I  will  constantly  insert  any  contribution  to  Basmify  here  for  your
  203. information.  You might find it amusing or interesting.
  204.  
  205. ____________________________________________________________________________
  206.  
  207. 95Oct2.114549+0100mesz.395394-2+180@hphalle0.informatik.tu-muenchen.de   was
  208. originally sent by rattei@informatik.tu-muenchen.de.
  209.  
  210. Christian  Rattei  wrote  (Mon,  2  Oct 1995 11:45:37 +0100 (MEZ)) in a Mail
  211. about "Basmify":
  212.  
  213. Following the forwarded message:
  214.  
  215. Hi,
  216.  
  217. Ich bin der Autor der BarflyInCED ARexx Scripte. Wie ich feststellen
  218. mußte, hast Du große Teile der Dokumentation, sowie des Readme-Files
  219. Deines Basmify Paketes (so, wie ich sie in aminet/dev/asm fand) von
  220. den Files meines Archivs übernommen. Da nicht nur meine Scripte,
  221. sondern _sämtliche_ Files des Archivs (also insbesondere _auch_ die
  222. Dokumentation) meinem Copyright unterliegen, betrachte ich dies als
  223. Verletzung meiner Urheberrechte.
  224.  
  225. Ich erwarte hiermit eine umgehende Entschuldigung Deinerseits _und_
  226. verlange für zukünftige Versionen Deines Basmify Archivs (falls es
  227. welche geben sollte und diese weiterhin, zumindest teilweise, auf
  228. meinen Dateien beruhen sollten) die Nennung meines Namens als Mitautor
  229. der betroffenen Teile des Archivs bzw. einen Verweis auf mein Original-
  230. Archiv mit Nennung meines Namens als Autor.
  231.  
  232. Sollte dies nicht geschehen, behalte ich mir weitere Schritte vor.
  233.  
  234. Bye,
  235.   Chris
  236.  
  237. -- 
  238. Christian Rattei (rattei@informatik.tu-muenchen.de)
  239. --------------------------------------------------------------------------------
  240. ____________________________________________________________________________
  241.  
  242. For  all  of  you  interested  in the above statement:  I suggest you have a
  243. «diff -y»-run on BarflyInCED and Basmify scripts and documentation.
  244.  
  245.  
  246.  8. HISTORY
  247. ------------
  248.  
  249. V1.0    initial public release
  250.  
  251. V1.1    second public release
  252.     - enhanced locale handling
  253.       (introduced workaround for missing CED locale support)
  254.  
  255.     - fixed port handling
  256.       (scripts can now distinguish multiple CED instances)
  257.  
  258.     - fixed options handling
  259.           (calling script will feed called script with selected options)
  260.  
  261.