home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / z / zap / !Zap / 3rdParty / Tyler / ObeyHelp < prev    next >
Text File  |  1996-11-03  |  20KB  |  447 lines
  1.  
  2.         ZapObey - A syntax colouring mode for Obey files
  3.         ================================================
  4.  
  5.                !Help file for ZapObey version 0.27
  6.  
  7. Contents
  8. ========
  9.  
  10. 1.0 : Features.
  11. 2.0 : Installation.
  12. 3.0 : What it does.
  13. 4.0 : Customisation.
  14. 5.0 : History.
  15.  
  16. 1.0 Features
  17. ============
  18.  
  19. The program recognises a large range of operating system commands, and does
  20. so even if the commands are in mixed case or are in abbreviated form.
  21.  
  22. It correctly colours GSTrans sequences like <Obey$Dir>, |G and <255>.
  23.  
  24. Numbers are recognised in decimal, hexadecimal and binary formats.
  25.  
  26. Redirection of the output of commands to different streams is indicated.
  27.  
  28. There is Beautify option which forces the displayed case of recognised
  29. commands to follow the standard set out by Acorn, and a BEAUTIFY command,
  30. which processes the file in the same manner.
  31.  
  32. The Zap SAVEANDRUN and RUN commands now start up a new task and execute the
  33. file.
  34.  
  35. It is easy to customise the module to add your own *commands if required.
  36.  
  37. Cursor key enhancements stolen from Martin Ebourne's modes (see later).
  38.  
  39.  
  40. 2.0 Installation
  41. ================
  42.  
  43. Copy the module "ZapObey" into an appropriately-named subdirectory of the
  44. "3rdParty" directory inside the Zap application.
  45.  
  46. In the file called "External", in the directory "!Zap.Options.Default" or 
  47. wherever the variable Zap$External points to, add lines as follows:
  48.  
  49. <Zap$3rdParty>.Tyler.ZapObey *
  50.     Obey
  51.     -
  52.     BEAUTIFY
  53.  
  54. This tells Zap about the new mode.  The '*' causes the mode to be loaded when
  55. Zap starts and if this is undesireable, can be omitted.  If you want Obey
  56. files loaded by default into this mode then you will need to edit the "Keys"
  57. file.
  58.  
  59. My keys file has these lines in it:
  60.  
  61. File types:
  62. ...
  63. Obey        &1FEB    Obey
  64. Deskstart    &13F0    Obey
  65. Desktop        &1FEA    Obey
  66.  
  67. If your version of Zap is earlier than Zap 1.30 then you will need to edit
  68. your !Run file to include a command to load the module.  Then, the next time
  69. Zap is loaded Obey files or desktop boot files (or any other filetypes you
  70. have told Zap about will be loaded into the new mode and come out all
  71. rainbow-hued.
  72.  
  73. When the module is first installed its logical-colours have all been set to
  74. default to different physical colours.  This has been done to show the
  75. breadth of the syntax colouring involved.  Some of the colours a are a
  76. little contrived, and choosing your own colours is recommended.
  77.  
  78. It is recommend that if you want to see what the module does, you should
  79. have the colours all set to different vaules at least for an initial period,
  80. until you clearly understand what each colour means.
  81.  
  82.  
  83. 3.0 What it does and does not do
  84. ================================
  85.  
  86. This program correctly displays most Obey files and desktop-boot files which
  87. are commonly encountered.  When it does not know about a command it assumes
  88. that it has an orthodox syntax and colours it differently from normal
  89. commands to indicate that it has not been recognised.  This method of
  90. gracefully failing enables the module to be used as a spell-checker and, to a
  91. limited extent, a syntax checker.  Missing Then commands, for example may be
  92. spotted more easily.
  93.  
  94. Leading spaces and '*'s are dealt with correctly by the module.  Leading
  95. '%'s, '@'s and '.'s are also ignored: this is mainly to cooperate with a
  96. number of PD programs which use these characters as special preprocessing
  97. commands when multi-tasking Obey files.  The '%' character is also used to
  98. prevent GSTrans from acting on a line.
  99.  
  100. The code used to display numbers should deal with most things correctly.
  101. Numbers of the form 2_010101, &A012 are recognised.  Numbers may contain ':'s
  102. (as in Sys$Time) and may end with the letter k (for memory specification). 
  103. Numbers in paths are not coloured.  There are some contrived lines of valid
  104. code in which the numbers are not coloured correctly:
  105. 'Save 0Bad CAB1 +C0D CAFE' is one example.  Examples such as this one can
  106. usually be made pretty if desired by placing quotes around filenames and
  107. putting an & or a leading 0 in front of hexadecimal numbers that begin with a
  108. letter.  '&' is not coloured as a hexadecimal prefix when used in the form
  109. &.filename.
  110.  
  111. The module does not attempt to process the parameters of the Configure
  112. command; they are displayed as plain text.  Recognising them would be easy to
  113. add to the module, but it may not be worth the space, as the Configure
  114. commands are rarely encountered in in Obey files.  There are also problems as
  115. different machines can have different configuration options.
  116.  
  117. The parameters of 'Set Alias$...' commands are not processed.  Code was
  118. written to do this, but has now been removed from the module as processing
  119. the parameters of these commands no longer seems appropriate.  If you want to
  120. see some of the problems that doing this produces then you can enter a
  121. TaskWindow and type the command 'Show Alias*'.  Then change to Obey mode and
  122. delete the first column by using search and replace with "Alias$* : " as the
  123. item searched for.  Most of the problems with the 'Set Alias$'s stem from the
  124. commands being passed to OS_GSTrans before they normally would be.  Doing
  125. this will also give you some idea of the commands that your computer uses
  126. that are not currently recognised.  For more comprehensive information on the
  127. same subject stoke your computer up with your favourite command-providing
  128. modules and then try an extensive text-massage session with the output of
  129. *Help Commands.
  130.  
  131. There is Beautify option which can be ticked just off the mode menu.  Setting
  132. this forces the displayed case of recognised commands to make the file more
  133. legible.  It does not affect the file, just the way it is displayed.  To make
  134. this option more useful when editing files, there is also a BEAUTIFY command,
  135. which processes the file in the same way.  No attempt is made to change the
  136. case of unrecognised commands, paths, or command parameters; only recognised
  137. commands are processed.
  138.  
  139. The module also contains some enhancements to the cursor keys so that when
  140. they are  used in combination with the shift key they behave in a more
  141. appropriate manner than when is in text mode.  These routines have been
  142. stolen from Martin Ebourne's C mode and are documented by him in his own 
  143. directory.  Basically they make the shift-cursor combinations pause more
  144. frequently and more intelligently step through the code.  As Obey files often
  145. contain paths, this comes in very useful.  Martin has kindly given me his
  146. permission to use his code.  His Assembler mode provided the initial
  147. inspiration for the module, and my appreciation of his C mode has risen
  148. astronomically now I appreciate the problems involved in getting colouring
  149. modes to work properly at low widths.  He also provided me with Dom Symes'
  150.  address when I most needed it (thanks Martin).
  151.  
  152.  
  153. 4.0 Customisation
  154. =================
  155.  
  156. 4.1 : Why customisation?
  157. 4.2 : How to customise.
  158. 4.3 : The format of the commands.
  159. 4.4 : The common command-terminators.
  160. 4.5 : The rare command-terminators.
  161. 4.6 : Terminator summary.
  162. 4.7 : Final Notes.
  163.  
  164.  
  165. 4.1 Why customisation?
  166. ----------------------
  167.  
  168. It is not easy to write an Obey file colouring module that will suit all
  169. tastes.  Different users may have different commands which are recognised by
  170. their computer, different files in their library, or pointed to by their
  171. Run$Path variable, different modules which provide their own commands loaded
  172. by default, and so on.  No attempt has been made to write a program that
  173. examines all the files in the Run$Path, examines the currently selected
  174. directory, looks at all the Alias$... variables and talks to all resident
  175. modules to find out which commands they support.  Even if a module did all
  176. this it would still not have enough information to correctly colour Obey
  177. files because it would need to know something about the syntax of the 
  178. commands to do this.
  179.  
  180. An example of this is the common 'Do' command.  For those to whom it is
  181. unfamiliar, it was written because some commands do not get the operating
  182. system to feed their parameters through the GSTrans-decoding engine.  This
  183. means that Filer_OpenDir <Obey$Dir> (for example) will not work as it does
  184. not even try to decode the <Obey$Dir>.  The 'Do' command solves this by
  185. passing the entir