home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / editor / gal210a4.arc / APPD.GAL < prev    next >
Text File  |  1987-08-11  |  12KB  |  250 lines
  1. .a js=y nm=1 pn=1 hy=n lp=12 bo=51 te=12 to=90
  2. .st3,14,1
  3. &dAppendix%D:%%The%Galahad%II%Text%Editor   .jc
  4. &d[%Appendix%D%] .hc
  5. .t36 D -  .zl
  6.  
  7.  
  8. .std3,14,1
  9. INTRODUCTION .jr
  10. .st3,11,1 .x-5
  11.  
  12.      Galahad has two parts:
  13.  
  14.           1) The printing formatter (see Appendix C and I), and
  15.           2) The editor (see Appendices D, E, F, G).
  16.  
  17.  
  18.      This Appendix discusses configuring and customizing Galahad.
  19.  
  20.  
  21. .std3,12,1
  22. Configuring Galahad II
  23. .st3,11,1
  24.  
  25.      Galahad II (Gal2) has a highly customizable editor.  It is configured
  26. using a two step process.  First, an initialization file must be created.  The
  27. distribution disk has a file called GALIBM.INI.  This is the starting point.
  28. You should make changes to it as desired.  See Chapter Six for details.
  29.  
  30.      To configure Galahad II with the INI file you have made, you must execute
  31. ConfPer.  ConfPer will ask you for four options.  The first argument is the
  32. file to be configured (GAL2.COM is the default).  The second argument is the
  33. INI file.  The third argument is the file to be the newly configured Gal2.  The
  34. fourth argument is the listing file, useful only in the event of an error in
  35. the INI file.
  36.  
  37.  
  38.  
  39.  
  40. .std3,14,1
  41. CUSTOMIZING GALAHAD II .jr
  42. .st3,11,1 .x-5
  43.  
  44.      Galahad II allows you to cause any key to execute any sequence of
  45. functions using an INI file.  By modifing the GALIBM.INI file itself you may
  46. customize Galahad II so that it does what you want.  Alternatively, you may
  47. elect to enter two INI files to Confper, the first being GALIBM.INI, and the
  48. second INI file containing just the keys that you wish to redefine.  This is
  49. done by specifying two =.INI files separated by a "+" when the =.INI file is
  50. requested.
  51.  
  52.      ConfPer also will accept its arguments on the command line in the same
  53. fashion as MS-Pascal, MS-Fortran, MS-Link, etc., or not prompt for any
  54. arguments if you enter A> CONFPER ;.
  55.  
  56.      We shall explain how to write your own INI file by giving some examples
  57. next.  You are assumed to have run Gal2 at least once before.
  58.  
  59.  
  60. .std3,14,1
  61. CREATING KEY DEFINITIONS .jr
  62. .st3,11,1
  63.  
  64.      A few definitions are in order.  A &ikey is the "botton" one presses on
  65. the keyboard.  A &ifunction defines the basic unit of Galahad II operation.  A
  66. &ikey%definition maps a key into a sequence of functions.  An &iINI%file
  67. contains a number of key definitions.  A &iprintable%key is a character that
  68. has a printable representation in the ASCII character set.  A &istring is a
  69. sequence of arbitrary characters enclosed in double quotes (").  Double quotes
  70. may be included in a string by entering two double quotes ("").
  71.  
  72.      A key definition consists of a key name, an equals sign, the list of
  73. functions separated by spaces, and a semicolon.  The case of both the key name
  74. and the function names is insignificant (except for the letter keys, of
  75. course), and whitespace may separate any of the above elements.  Literal
  76. characters (letter keys and printable characters) are included by enclosing
  77. them in double quotes (").  If a function prompts for input, and a string
  78. follows it in the key definition, the string is used for the input.
  79.  
  80.      Galahad II allows for key prefixes similar to WordStar (tm of MicroPro),
  81. but in a more general fashion.  Picture a multiple layer keyboard where most of
  82. your typing occurs on the bottom layer.  One or more of the bottom layer keys
  83. allows you to jump to an upper layer, temporarily giving you a whole new set of
  84. keys.  Each layer has a single character name, such as A, B, 0, 1, etc.  A key
  85. which is in an upper layer is called a &imeta%key.
  86.  
  87.      Galahad II provides an optional set of meta prefixes for all keys.  Meta
  88. keys are formed by prefixing the key name with 'm1' through 'm9', and 'mA'
  89. through 'mZ'.  These called meta levels, making possible 36 different meta
  90. keyboard levels.  A metaized key may be input by executing the key bound to the
  91. desired meta level function before executing the key.  The meta keys are bound
  92. by the level key, for example, Esc==MetaKey "1".
  93.  
  94.      WordStar key layout might use three layers B, K, and Q.  The ^B, ^K, and
  95. ^Q keys would then be assigned to &dMetaKey "B", &dMetaKey "K", and &dMetaKey
  96. "Q" respectively.  Then the desired functions would be assigned to meta B, K,
  97. and Q keys.  That is, one set of key definitions at meta level K, and another
  98. set at meta level K, etc.  To use the definitions at meta level K, the user
  99. would press ^K to access meta level K and then the desired key to cause the
  100. bound function to be executed.
  101.  
  102.      Typically, only the named (unprintable) keys are redefined.  The named
  103. keys are listed in Appendix F under &ireserved&iname.  Some of the named keys
  104. have shifted versions which may be formed by prefixing the key with an 's',
  105. meaning shifted.  Some control keys have names.  Any that don't are named by
  106. prefixing the letter by a caret (^).  Printable keys are expressed as a key
  107. name by enclosing them in quotes to form a string.  The quote character is
  108. included in a string by doubling it, so the name of the quote key is """".
  109.  
  110. .n10
  111. &oExamples:
  112.  
  113. UpArrow .t15 The up arrow key.
  114. sUpArrow .t15 The shifted up arrow key.
  115. Return .t15 The return key (Control-M).
  116. ^M .t15 Also the return key.
  117. "," .t15 The comma key.
  118. """" .t15 The quote key.
  119. mReturn .t15 The meta return key.
  120. m"," .t15 The meta comma key.
  121.  
  122.  
  123.      You now know enough about key definitions to refer to Appendix F, which
  124. contains the GALIBM.INI file.  Locate the keys that you are most familiar with,
  125. and find the meaning of the functions that they are assigned to by referring to
  126. Appendix E.  The function names have been chosen to have mnemonic meanings so
  127. that extensive help messages are not required.
  128.  
  129.      In your reading of Appendix E, you will notice two "keys" that do not
  130. appear on the keyboard, "Init." and "CmdLF.".  The "Init." key is executed once
  131. and only once, just after Galahad II starts executing.  This is handy for
  132. configuring the cursor to your liking, setting the screen color, etc.  The
  133. other special key, "CmdLF.", is a special rendition of the linefeed key.  When
  134. you press linefeed in Command Mode, the "CmdLF." key is executed instead.  This
  135. allows you to drop straight from command mode into edit mode with a single
  136. keypress.
  137.  
  138.      There are two ways to create key definitions.  You can make a permanent
  139. change by editing the default key definition file and use it to configure
  140. Galahad II, or you can use the &dReadInitBuffer function which changes the key
  141. definitions just this one time.  Both of these methods will be discussed in
  142. detail later, but for now we shall use the temporary method which uses
  143. &dReadInitBuffer.
  144.  
  145.  
  146. .std3,12,1
  147. An Example Key Definition
  148. .st3,11,1
  149.  
  150.      You should be ready for more advanced key definitions than the ones given
  151. in Appendix F.  Say that you use the string "Clarkson University" quite often.
  152. You may wish to assign it to the KP7 key, which is not defined by the
  153. GALIBM.INI file.  You first create an empty buffer by executing the command NEW
  154. (Press <RETURN>, and enter NEW), then enter the following key definition:
  155. 'KP7=="Clarkson University";'.  The single quotes are included for your
  156. edification and should not be included in the key definition.  Note that the
  157. key definition has the requisite four parts mentioned earlier: Key name (KP7),
  158. equals sign, function ("Clarkson University"), and a semicolon.
  159.  
  160.      Now instruct Galahad II to read the buffer as if it were an INI file by
  161. executing the &dReadInitBuffer function by typing 'ReadInitBuffer' ('read' is
  162. sufficient) at the Command: prompt.  If you have made any mistakes then you
  163. will be thrown back into the buffer at the point at which the error occured.
  164. If not then you may press the shift Home key to test your example definition.
  165. In any case, you have &inot made any permanent change to Galahad II so feel
  166. free to make mistakes.  The following examples use the same method.
  167.  
  168.      Let's improve on this key definition by including Clarkson's mailing
  169. address on a separate line.  The key definition would be: 'KP7=="Clarkson
  170. University" InsertNewline "Potsdam, N.Y. 13676";'.  The InsertNewline function
  171. does just that, insert a newline.  
  172.  
  173.      Let's keep improving the key definition by posing a problem.  Say that we
  174. had indented in a few columns and tried to insert Clarkson's name and address
  175. using the previous key definition (try it).  Unfortunately, the address part is
  176. not indented to the same column.  We'll fix that by using the TabToPrev
  177. function: 'KP7=="Clarkson University" InsertNewline TabToPrev "Potsdam, N.Y.
  178. 13676";'.  Now the address part gets tabbed out to the same column as the
  179. previous line started on.
  180.  
  181.      Now for a meta key example.  Let's presume that you have no more function
  182. keys to assign for the above example.  That is you have defined all possible
  183. keys to have some action.  In GALIBM.INI, Esc is bound to m1, that is, meta
  184. level one.  By pressing Esc you have opened up a whole new level of keys
  185. available for assignment.  In the above example make the assignment:
  186. 'm1KP7=="Clarkson University" InsertNewline TabToPrev "Potsdam, N.Y.  13676";'.
  187. Now KP7 has its previous meaning and Esc KP7 will display 'Clarkson University
  188. =......'.
  189.  
  190.      Let's say you wanted a new meta level for yourself.  Make the definition:
  191.  
  192.         sKP7==MetaKey "A";
  193.         KP7=="Clarkson =.....";
  194.  
  195.  
  196. .std3,12,1
  197. Entering Key Definitions
  198. .st3,11,1
  199.  
  200.      As promised earlier, the two methods for entering key definitions will be
  201. explained.  The first method involves using ConfPer to permanently affix your
  202. keys to Gal2.
  203.  
  204.      Find the GALIBM.INI file on the distribution diskette.  Make another INI
  205. file with your custom key definitions in it.  Call it YOURS.INI.  Now you are
  206. ready to run the files through ConfPer.  When ConfPer prompts you for your INI
  207. file, enter "+YOURS" without the enclosing quote marks.  This tells ConfPer to
  208. use both GALIBM.INI and YOURS.INI.
  209.  
  210.      The other method for entering key definitions is to include only your key
  211. definitions in a =.INI file, load that file into Gal2, and execute the
  212. &dReadInitBuffer command.  This method can be somewhat clumsy, but is useful
  213. for testing new key definitions. 
  214.  
  215.  
  216. .std3,12,1
  217. Tidbits
  218. .st3,11,1
  219.  
  220.      Listed below are a few tidbits that are not obvious without carefully
  221. reading the entire documentation.
  222.  
  223.      1) The easiest way to redefine a few keys is to make an INI file
  224. containing just those keys.  Test the definitions using &dReadInitBuffer
  225. function.  When you are satisfied, use ConfPer with two INI files, GALIBM.INI
  226. and your INI file.
  227.  
  228.      2) Several functions are intrinsically useless and are included just for
  229. compatiblity with Galahad I.  &dCommandMode is just that, a mode in which
  230. commands must be entered.  It is superceded by &dCommand, which allows the
  231. entry of one command and throws you back into editing after that one command is
  232. executed.  &dEditMode is a companion (useless) function to &dCommandMode.
  233.  
  234.      3) &dLoadFile causes the current file to be overlaid with the new file.
  235. Unless you have filled your computer's memory, &dLoadBuffer is more useful
  236. because the new file is loaded into a new buffer and the old file is still
  237. available using &dNextBuffer.
  238.  
  239.      4) &dUserPhrase is a watered-down version of &dRecordKey.  Most people
  240. will want to use &dRecordKey because &dUserPhrase will not accept cursor
  241. movement keys.
  242.  
  243.      5) Don't edit an INI file that contains PrinterFont functions in ASCII
  244. mode.  This is because the translation of older-style control characters mucks
  245. with the argument to PrinterFont.  Instead, enter the command &dBinaryFile
  246. before you load the INI file.
  247. .g2
  248.  
  249.  
  250.