home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / old / ckermit4e / ckm834.mss < prev    next >
Text File  |  2020-01-01  |  36KB  |  753 lines

  1. @comment[    -*-Text-*-    ]
  2. @Part(CKMKER,root="KER:KUSER")
  3. @string(-ckmver="@q<0.8(34)>")
  4. @define(exx=example,above 2,below 1)
  5. @Chapter<MACINTOSH KERMIT>
  6.  
  7. @Begin<Description,spread 0>
  8. @i(Program:)@\Bill Catchings, Bill Schilit, Frank da Cruz (Columbia
  9. University),@*Davide Cervone, University of Rochester
  10.  
  11. @i(Language:)@\C (SUMACC)
  12.  
  13. @i(Documentation:)@\Frank da Cruz, Bill Schilit
  14.  
  15. @i(Version:)@\@value(-ckmver)
  16.  
  17. @i(Date: )@\March, 1986
  18. @end<Description>
  19.  
  20. @index<Macintosh Kermit>
  21. @index<CKMKER>
  22. Macintosh Kermit, or @qq[MacKermit], is an implemtation of the Kermit file
  23. transfer protocol for the Apple Macintosh (and Macintosh-XL) computer,
  24. developed at Columbia University, based on C-Kermit (which also forms the
  25. nucleus of Unix Kermit).
  26.  
  27. @subheading<MacKermit Capabilities At A Glance:>
  28. @begin<format,leftmargin +2,above 1,below 1>
  29. @tabclear()@tabset(3.5inches,4.0inches)
  30. Local operation:@\Yes
  31. Remote operation:@\Yes (server mode only)
  32. Login scripts:@\No
  33. Transfer text files:@\Yes
  34. Transfer binary files:@\Yes
  35. Wildcard send:@\No
  36. File transfer interruption:@\Yes
  37. Filename collision avoidance:@\Yes
  38. Can time out:@\Yes
  39. 8th-bit prefixing:@\Yes
  40. Repeat count prefixing:@\Yes
  41. Alternate block checks:@\Yes
  42. Terminal emulation:@\Yes (VT100,VT102)
  43. Communication settings:@\Yes
  44. Transmit BREAK:@\Yes
  45. Support for dialout modems:@\No
  46. IBM mainframe communication:@\Yes
  47. Transaction logging:@\No
  48. Session logging:@\No
  49. Debug logging:@\No
  50. Packet logging:@\No
  51. Act as server:@\Yes
  52. Talk to server:@\Yes
  53. Advanced server functions:@\No
  54. Local file management:@\Yes
  55. Command/Init files:@\Yes
  56. File attributes packets:@\No
  57. Command macros:@\No
  58. Raw file transmit:@\No
  59. @end<format>
  60.  
  61. The main differences between MacKermit and other Kermit programs are:
  62. @Begin(Itemize)
  63. In MacKermit you are always connected via a terminal emulator (VT102).
  64.  
  65. MacKermit commands are issued by means of pull-down menus that overlay
  66. your terminal session.  
  67. @End(Itemize)
  68.  
  69. The major menus are @b(File), @b(Settings), @b(Remote), and @b(Transfer).  The
  70. @b(File) menu invokes Kermit's file transfer functions, allows settings to be
  71. saved and restored, and like most Macintosh applications, includes a "quit"
  72. selection for leaving the program.
  73.  
  74. The @b(Settings) menu provides dialog boxes for file, communications, and
  75. protocol settings.  The @b(Remote) menu has the commands that can be
  76. sent to Kermit servers, as well as an option to turn Macintosh Kermit itself
  77. into a server.  The @b(Transfer) menu gives you a standard Macintosh file box,
  78. allowing you to transfer directly to the selected application.
  79.  
  80. @Section(The Macintosh File System)
  81.  
  82. The Macintosh file system consists of one or more disks, each disk containing
  83. files.  All files on a disk must have a unique name.  Files may be
  84. collected together into @qq[folders], but folders are not analogous to
  85. directories on other file systems, and no two folders on the same disk may
  86. contain files of the same name.  Macintosh file names may contain practically
  87. any printable characters, including space and punctuation -- but colon (@qq[:])
  88. should be avoided because it is used in device names.
  89.  
  90. @Section(File Transfer)
  91.  
  92. @i<Glossary>:
  93.  
  94. @Begin(Itemize)
  95. @u<Mode> - Text or Binary.  Binary means the data is sent or stored without
  96. modification. Text means that every carriage return character (CR) in a
  97. Macintosh file is translated to a carriage-return-linefeed (CRLF)
  98. sequence when sending, and every CRLF in an incoming file is turned into
  99. a CR when stored on the Mac disk.  A text file is produced when you
  100. save a file from MacWrite using the "text only" option; text files are
  101. not associated with any particular Macintosh application and can be
  102. sent in a useful fashion to other kinds of computers.
  103.  
  104. @u<Fork> - Data or Resource.  Macintosh files may have two "forks".  The data
  105. fork contains data for an application; the resource fork contains icons,
  106. strings, dialog boxes, and so forth.  For instance, a MacWrite document
  107. contains text and formatting information in the data fork, and fonts in
  108. the resource fork.  For applications, the executable code is stored in the
  109. resource fork.
  110. @End(Itemize)
  111.  
  112. Macintosh Kermit supports the standard Kermit commands for transferring
  113. files -- Send, Receive, and Get.  Invocation of any of these commands
  114. produces a MacKermit file dialog box in which you specify the file name, the
  115. mode, and the fork.  Defaults are determined from the selected file or
  116. taken from the current file settings, described below.
  117.  
  118. When you select the Send command, you get a MacKermit file open box, which
  119. includes the standard Macintosh dialog items -- a file list, Disk and
  120. Eject buttons, etc.  You can only send one file at a time, by clicking on
  121. its name in the file list.  Clicking the Disk button will switch the file
  122. list to another physical disk.  If desired, you can type an alternate name
  123. to send the file under.  When you select a file, MacKermit examines its
  124. type; if the type is APPL, then MacKermit expects to send the resource fork
  125. in binary mode, otherwise the data fork in text mode.  The Mode and Fork
  126. radio buttons will display these choices; you may change them before clicking
  127. the Send button.  
  128.  
  129. You can receive or get multiple files, providing the opposite Kermit is
  130. capable of sending multiple files in a single transaction (most are).  As
  131. files arrive, they will be decoded according to the current mode (text or
  132. binary), and stored in the default fork (data or resource) under either the
  133. name they arrive with (overwriting existing files of the same names) or
  134. under new unique names (when name conflicts occur), according to the current
  135. default for name collisions.  You may also elect to perform an "attended"
  136. receive, in which you have an opportunity to override all file defaults on a
  137. per-file basis.  But this option must be used with caution -- if you take
  138. too long (more than about a minute) to execute an incoming file's dialog
  139. box, the opposite Kermit could time out and terminate the transaction.
  140.  
  141. The folder for new files is the same as the location of the settings file,
  142. or if no settings file was used then the new files appear on the desktop.
  143. If you are transferring a lot of files and want to keep them together,
  144. create a folder, drag the settings file into it, and double click on the
  145. settings file; all created files will appear in that folder.
  146.  
  147. File transfers can be cancelled by clicking on the Cancel File or Cancel
  148. Group buttons.  These will always work when sending.  When receiving, they
  149. will work if the opposite Kermit honors this (optional) feature of the
  150. protocol.
  151.  
  152. In any case, an "emergency exit" from any protocol operation can be taken at
  153. any time by typing "Command-@q(.)" -- that is, hold down the Command (Fan,
  154. Cloverleaf) key and type period.
  155.  
  156. @section(Remote Commands)
  157.  
  158. The @b(Remote) menu allows you to send commands to a Kermit server.  The
  159. response from these commands (if any) is displayed in a special pop-up
  160. window.  Responses to multiple Remote commands are separated by a dashed
  161. line.  The response window can be scrolled, sized, and positioned, and can
  162. be hidden by clicking the menu item "Hide Response" or the window's go-away
  163. box; all text remains intact and will be appended to the next time you do a
  164. Remote command; it can also be brought to the foreground by clicking the
  165. Show Response menu item.  Note that typein to the terminal emulator will not
  166. take effect when the response window -- or any other window -- is up front.
  167.  
  168. If the response window gets too full (i.e. fills up the free memory
  169. available to the MacKermit application), the program will probably bomb.
  170.  
  171. If the remote Kermit server is in binary mode, its responses to Remote
  172. commands may look strange.  For instance, a Unix Kermit server
  173. in binary mode will send lines of text separated by only linefeeds,
  174. rather than CRLFs.
  175.  
  176. A Remote command can be cancelled by taking the Emergency Exit (Command-@q<.>).
  177.  
  178. @section(Settings)
  179.  
  180. You can change File, Communications, and Protocol settings by using the
  181. Settings pull-@|down menu.  You can save and restore these settings by
  182. invoking the appropriate selection in the File menu.  If the bundle bit
  183. has been correctly set on your version of MacKermit you can double-@|click
  184. on the resulting document to start MacKermit with those settings.
  185.  
  186. The File settings establish the defaults for file transfer:
  187. @Begin(Itemize)
  188. @u<Mode>: text or binary.  Used for received files only.  When sending,
  189. MacKermit tries to figure out an appropriate mode for the file being
  190. sent (but then lets you override it the Send File dialog).
  191.  
  192. @u<Fork>: which fork -- data or resource -- to send, or to store an incoming
  193. file into.
  194.  
  195. @u<Naming>: Whether incoming files should supersede existing files of the same
  196. name, or a new unique name should be assigned to them.  If the latter, the
  197. new name is formed by adding a dot and a number to the end.  For instance,
  198. if a file called FOO exists and a file called FOO arrives, MacKermit will
  199. store the arriving file as FOO.1; if FOO.1 exists, then FOO.2, etc.
  200.  
  201. @u<Attended> versus @u<Unattended> operation for incoming files.
  202. @End(Itemize)
  203.  
  204. The Communications settings allow you to set the baud rate (anywhere
  205. between 300 baud and 57@q<.>6K baud), parity (odd, even, mark, space, or none),
  206. and duplex (full - remote echo, half - local echo).
  207.  
  208. The Protocol settings allow you to set packet parameters for both incoming
  209. and outbound packets.  These include the block check type (1 or 2
  210. character checksum, 3-character 16-bit CRC-CCITT), line turnaround handshake
  211. character (for file transfer with half duplex systems), packet start and end
  212. characters, padding, packet length, timeout interval, and so forth
  213. (Refer to Kermit User Guide).  Characters are specified by entering their
  214. ASCII value in decimal, e.g. 1 for Control-A, 13 for Control-M (Carriage
  215. Return), etc.
  216.  
  217. @Section<Terminal Emulation>
  218.  
  219. MacKermit provides a subset of the features of the DEC VT102 terminal; the
  220. VT102 is a VT100 with line and character insert/@|delete
  221. functions added.  The functions provided are sufficient to allow MacKermit
  222. to act as a terminal for EMACS as it exists on the DEC-20, VAX (CCA EMACS on
  223. VMS or UNIX), and for most host-@|resident display-oriented applications that
  224. expect to do cursor positioning and editing on the VT100 screen.  MacKermit
  225. does not currently support the following VT100/102 functions:
  226. @Begin(Itemize,spread 0)
  227. double height or double width lines
  228.  
  229. smooth scrolling
  230.  
  231. 132 columns
  232.  
  233. Interpretation of multiple parameters in a single escape sequence
  234.  
  235. etc
  236. @End(Itemize)
  237. (this is not an exhaustive list)
  238.  
  239. The keyboard is set up by default as follows: The COMMAND (Fan, Cloverleaf) key
  240. is used as the Control key.  The CAPS LOCK key forces all alphabetic characters
  241. to upper case, and causes keys on the numeric keypad to send VT100 keypad
  242. escape sequences.  The OPTION key is "Control-Meta" (explained below).  The
  243. terminal emulator sends ESC (escape) when the @qq(`) key is pressed unshifted.
  244. The character @qq(`) can be sent by typing Control (Command) and the same key.
  245. The Backspace key sends a Delete (Rubout) and Control-@|Backspace sends a
  246. Backspace.  The main keypad Enter key sends a "short" (250ms) BREAK signal.
  247. The Mac+ does not have a main keypad Enter key, so the BREAK function must
  248. be reassigned to another key.  Use CKMKEY (see below) to do this.  The
  249. short break is F126 (function number 126) and long break is F127.
  250.  
  251. MacKermit (V0.8 and later) comes with a separate key configuration program,
  252. CKMKEY, which lets you change the behavior of the keys, define function keys,
  253. and so forth.  CKMKEY is described in detail below.
  254.  
  255. MacKermit (V0.8(43A) and later) includes a mouse-controlled cursor postioning
  256. feature for use during terminal emulation.  When the mouse button is pressed
  257. while the Option and Command keys are held down, the program acts as if you
  258. typed the keypad arrow keys to move the terminal cursor to where the mouse
  259. cursor is.  You must have already defined the keypad arrow keys to send the
  260. appropriate character sequences for your host application.  The Catch-22 here
  261. is that if you don't have a keypad, there's no way for you to define the keypad
  262. keys using MacKermit's keyboard configurator.  In that case, you can use the
  263. VT100 startup file provided with MacKermit, which assigns the normal VT100
  264. arrow key sequences to the keypad arrow keys, and therefore also to the
  265. mouse-cursor feature.
  266.  
  267. MacKermit honors your parity communications setting by using built-in
  268. functions of the Mac's serial i/o chip.  Unfortunately, the chip has an
  269. unpleasant quirk -- arriving characters that do not have the specified
  270. parity are discarded rather than passed to the requesting application.
  271. Thus, if you are connected as a terminal using MacKermit to a device that
  272. requires, say, odd parity on characters sent to it, but does not put odd
  273. parity on characters it sends to you, then many incoming characters will
  274. not appear on your screen.
  275.  
  276. To allow useful coexistence of desk accessories and Kermit, the terminal
  277. emulation may be dragged using the drag bar.  A desk accessory that overlays
  278. the Kermit window can be clicked upon to move it behind the Kermit window,
  279. and then the Kermit window can be dragged to reveal the hidden desk accessory
  280. so that it can be restored to the foreground.  The same thing can be done
  281. with Kermit's own remote response window.  Note that Kermit's terminal
  282. emulation window does not accept input when any other window is in the
  283. foreground.
  284.  
  285. The following features are missing from the MacKermit terminal emulator,
  286. and may be added in subsequent releases:
  287. @Begin(Itemize,Spread 0)
  288. capturing text from the screen (e.g. cutting to clipboard, saving off top)
  289.  
  290. screen rollback, sizing
  291.  
  292. modem or dialer control
  293.  
  294. login scripts
  295.  
  296. transmission of raw text to host (e.g. pasting to screen)
  297.  
  298. printer support
  299. @End(Itemize)
  300.  
  301. MacKermit does not use XON/XOFF flow control during terminal emulation or file
  302. transfer.  The terminal emulator can normally keep up at 9600 baud, but after
  303. several continuous scrolling screens at this speed, some characters may be
  304. lost.  In the present version, when running at high baud rates keep your
  305. terminal in page mode, or use "more", or view text with a non-@|scrolling
  306. screen editor.  Also, don't drag the terminal emulation window while characters
  307. are arriving; if you do, the characters will be lost and the display will
  308. become confused.
  309.  
  310. @Section<Installation>
  311.  
  312. MacKermit is distributed in source form for building on Unix (or VMS/Eunice)
  313. systems that have the Stanford SUMACC Macintosh cross-@|development tools, in
  314. @index<Binhex>
  315. @q(.HQX) "binhex" form, and sometimes also as a binary resource file.  Those
  316. who want to work from the source are referred to the file @q(CKMKER.BLD) for
  317. instructions.
  318.  
  319. If you have the binary resource file available (its name will be
  320. @q(CKMKER.RSRC), @q(ckmker.rsrc), @q(CKMKER.RSR), @q(ckmker.rsr), or some
  321. variation on these, depending on what system it's stored on and how it got
  322. there), AND if you have "MacPut" on your system and MacTerminal on your Mac,
  323. AND if you have an 8-bit-wide (no parity) data path between your Mac and your
  324. system, use MacPut to download the binary resource file to MacTerminal's XMODEM
  325. @index<Setfile>
  326. option on your Mac.  After doing this you must use SetFile on the Mac to set
  327. the author to KERM, the type to APPL, and turn on the bundle bit.  For CKMKEY,
  328. the author should be KERK.
  329.  
  330. If you have an earlier release of Columbia MacKermit, you may use Kermit in
  331. place of MacTerminal and MacPut.
  332.  
  333. If you don't have the binary resource file available, you can download
  334. the @q(CKMKER.HQX) file in the same manner, then run "binhex" (version 4) on
  335. it.
  336.  
  337. @Section<CKMKEY - Macintosh Kermit's Keyboard Configurator>
  338.  
  339. This describes CKMKEY V0.8(0), May 1985.
  340.  
  341. @index<CKMKEY>
  342. The version number of CKMKEY indicates compatability with the like version of
  343. CKMKER -- Macintosh Kermit, referred to simply as "Kermit" from now on.
  344. Edit numbers (within parentheses) may differ.  If Kermit is used with a
  345. settings file containing a key configuration produced by an incompatible
  346. version of CKMKEY, then that configuration will be ignored.
  347.  
  348. @SubSection<What is CKMKEY?>
  349.  
  350. CKMKEY is a keyboard configurator program for use with Macintosh Kermit
  351. (versions 0.8 and greater). CKMKEY allows:
  352. @Begin(Itemize)
  353. Redefinitions of keys
  354.  
  355. Definitions of multicharacter function keys
  356.  
  357. Selection of long and short BREAK keys
  358. @End(Itemize)
  359.  
  360. CKMKEY is a separate program from Kermit.  It may be thought of as an editor
  361. for Kermit's terminal emulator key definition resource, which is kept in a
  362. Kermit settings file.  Before you can use CKMKEY, you must already have used
  363. Kermit to create a settings file to operate on.
  364.  
  365. The reason CKMKEY is separate from Kermit is that there is not enough room in
  366. the memory of a 128K Macintosh to hold a program that can do both.  CKMKEY
  367. displays and changes key settings, Kermit uses them.  Once you have started
  368. Kermit with a given set of key definitions, there is no way to examine or
  369. change them.
  370.  
  371. Some familiarity with the ASCII alphabet is assumed in the following
  372. discussion.
  373.  
  374. @SubSection<Modifier vs Normal Keys>
  375.  
  376. The Macintosh keyboard is composed of normal keys and modifier keys.  Modifier
  377. keys are SHIFT, CAPS LOCK, OPTION, and COMMAND (also known as APPLE, CLOVER, or
  378. FAN).  Only one normal key can be selected at a time, but one or more modifier
  379. keys can be depressed along with it.
  380.  
  381. @subSection<Key Maps>
  382.  
  383. When a key on the keyboard or numeric keypad is depressed the result is a scan
  384. code -- a number between 0 and 127 (see Inside Mac Event Manager for details if
  385. you're interested).  A table indexed by scan code resulting in the character to
  386. be displayed or transmitted will be referred to as a "keymap" or "key mapping."
  387.  
  388. On the standard Mac many keymaps exist -- the modifier keys (such as SHIFT)
  389. specify which keymap is selected.  For example, when no modifer keys are
  390. depressed the keymap contains the lowercase alphabet, numbers and some
  391. punctuation.  The keymap in use when the SHIFT modifer is depressed contains
  392. the capital letters and special characters.
  393.  
  394. All in all it is possible to select 16 different keymaps by depressing from
  395. zero to four modifier keys.  Normally however, 6 or so distinct keymaps will
  396. suffice.
  397.  
  398. CKMKEY allows you to redefine 6 keymaps: shifted and unshifted combinations of
  399. keymaps named "normal", "capslock", and "control".  These keymaps are
  400. predefined with the expected values -- the control map is preloaded with
  401. control codes, the capslock preloaded with the unmodifed keymap but with all
  402. letters uppercase.
  403.  
  404. In this document modifier keys are written in capital letters and key map names
  405. are written in lowercase.  SHIFT, CAPS LOCK, COMMAND, and OPTION are
  406. modifier keys, "normal" "capslock" and "control" are key maps internal to
  407. CKMKER.  Since one of the major functions of CKMKEY is to change maps
  408. invoked by modifier keys, it is important to keep this distinction in mind.
  409.  
  410. @SubSection<What's in CKMKEY's Keymaps>
  411.  
  412. A keymap is a list of 128 numbers.  Which keymap is selected depends upon which
  413. modifier keys are depressed, and the entry within the key map is determined by
  414. the scan code.  A keymap entry is an 8-bit quantity:  if the high order bit is
  415. 0, then the entry is the 7-bit ASCII character to be transmitted through the
  416. serial port; if the high bit is 1, then the remaining 7 bits
  417. are an index into the function-key table.
  418.  
  419. Notice that only single 7-bit values can be directly translated through the
  420. CKMKEY keymap.  If you want a single key to transmit multiple characters, then
  421. you can designate that key to be a "function key", and the key map will contain
  422. an indirect reference to the function-key table.  If you want a key to transmit
  423. an 8-bit value, assign the "meta" operation to one of the modifier keys and use
  424. the meta key together with the desired key (see below).
  425.  
  426. Functions are numbered 0-127 with the highest few being reserved for special
  427. use.  Currently functions 126 and 127 send a short 250 millisecond BREAK signal
  428. and a long 3.5 second BREAK respectively.  In the future more special functions
  429. may be allocated so (since it is arbitrary anyway) please use low numbered
  430. functions when defining your own.
  431.  
  432. @subSection<Menus>
  433.  
  434. CKMKEY has two menus, @b{File} and @b{Set}.  First you must use the @b{File}
  435. menu to select and open a Macintosh Kermit settings file, which in turn has
  436. been created using the Kermit Save Settings option from its own File menu.
  437. Then use the @b{Set} menu to establish or alter key definitions, then use the
  438. @b{File} menu again to save the settings file back for Kermit.  A variety of
  439. Kermit settings files can be kept, each with its own collection of settings and
  440. key definitions; Kermit can be started with the desired settings by double
  441. clicking on one of these settings files from the Macintosh desktop.
  442.  
  443. Menus consist of options.  If an option is followed by an ellipsis (three
  444. dots...) then clicking it will produce a dialog box of some kind; otherwise,
  445. clicking it causes the indicated action to be performed immediately.  If an
  446. option is dimmed then it is not available for some reason -- for instance, you
  447. can't set any keys until you open a settings file.
  448.  
  449. @SubSection<MENU: Set>
  450.  
  451. The @b{Set} menu includes dialogs for setting keys, defining functions, and
  452. reassigning modifier keys.
  453.  
  454. @Paragraph<DIALOG: Set Modifer Keys>
  455.  
  456. @i<Background>:
  457.  
  458. Skip ahead to the next section if you already know about things like SHIFT,
  459. CAPS LOCK, CONTROL, and META.
  460.  
  461. On a typewriter the only modifier key is SHIFT.  Typing a character with no
  462. modifier key depressed selects a lowercase letter or the character printed on
  463. the lower face of the keytop (say, the digit "4").  Typing a character with
  464. SHIFT depressed selects an uppercase letter or the character printed on the
  465. upper face of the keytop (say, a dollar sign).  Some keyboards also have a
  466. SHIFT LOCK key, which stays down once pressed and pops up the next time it's
  467. pressed; its operation is equivalent to holding down SHIFT.  And some keyboards
  468. have a CAPS lock key which operates like SHIFT LOCK, but only upon letters.
  469.  
  470. Computer terminals also have a modifier key called CONTROL (or CTRL).  Its
  471. function is a little less obvious: it is intended to produce one of the 33
  472. characters in the "control range" of the ASCII alphabet.  Control characters
  473. are not graphic -- they are intended for use as format effectors (like carriage
  474. return, formfeed, tab, backspace), for transmission control, or for device
  475. control.  The remaining 95 characters -- letters, digits, and punctuation --
  476. are the graphic characters.  When a character is typed with the CONTROL
  477. modifier pressed, its "control equivalent" is transmitted.  By convention,
  478. the control equivalent of A is Control-A, B is Control-B, etc, and there
  479. are also seven special control characters generally associated with
  480. punctuation characters or special keys.  For the "alphabetic" control
  481. characters Control-A through Control-Z, SHIFT or CAPS LOCK modifiers are
  482. ignored; for the others, operation varies from terminal to terminal.
  483.  
  484. The SHIFT and CONTROL modifiers allow all 128 ASCII characters to be sent from
  485. a normal typewriter-like keyboard that has about 50 keys.  However, certain
  486. host-resident computer applications -- notably the full screen text editor
  487. EMACS and its descendents -- can be used to greater advantage with a 256
  488. character alphabet (EMACS responds to single-character commands, and the more
  489. characters a terminal can send, the more commands are directly available).
  490. @index<META Key>
  491. For this purpose, some terminals also provide a META modifier key.  This key
  492. simply causes the high-order ("8th") bit of the selected ASCII value to be
  493. set to 1 upon transmission.  META characters can only be transmitted when the
  494. communication path allows all 8 bits to pass transparently; when this is not
  495. possible, software like EMACS allows a sequence of two 7-bit ASCII characters
  496. to represent a single meta character.  The advantage of having a real META
  497. modifier key is that it can be held down while the actual key is struck
  498. repeatedly or even autorepeats, whereas a use of a "meta prefix" requires much
  499. more typing.  To illustrate, suppose META-F is the command to go forward one
  500. word.  If you want to execute this operation repeatedly, just hold down META
  501. and F and let it autorepeat.  If you don't have a META key, then you have to
  502. use a "meta prefix" character (usually escape), and to enter META-F repeatedly
  503. in this case, you'd have to type <escape>F<escape>F<escape>F...etc.
  504.  
  505. @i<Macintosh Kermit Modifier Keys>:
  506.  
  507. You can define the modifier key to keymap correspondence in CKMKEY by selecting
  508. the "Modifer Keys..." menu item under SET, or by double clicking on a modifier
  509. key while in the SET KEYS dialog.
  510.  
  511. The SET MODIFIERS dialog lets you define what map OPTION, CAPS LOCK and COMMAND
  512. refer to.  Notice that SHIFT is missing -- SHIFT always references the shifted
  513. equivalents to the normal, control and caps lock maps.
  514.  
  515. The dialog is layed out in columns with the three modifier keys as column
  516. headings and the three map names below.  Also under each column is a "pseudo"
  517. key map for "meta."
  518.  
  519. Meta is not a map, but an operation: it augments the value being transmitted
  520. after it has been read from its map.  Meta can either be set to send a prefix
  521. string before the character or to turn the high order (8th) bit on in the
  522. transmitted character.  The default prefix for meta is set to be 033 (escape).
  523. If a meta modifier key is depressed and the key results in a function reference
  524. then no modification occurs; functions are not "metized".  However, functions
  525. can be defined to include 8-bit values.
  526.  
  527. Notice that meta can be set in conjunction with a key map.  Since meta is an
  528. operation as described above there is no ambiguity.  Consider for example
  529. setting OPTION to reference the "control" map and selecting "meta" for this
  530. modifier key as well.  The result is a control-meta key.  
  531.  
  532. @Begin(Quotation)
  533. @i<@u(CAUTION)>: If you have used Kermit's communications settings menu
  534. to select any parity other than "none", then any high order bits
  535. that may be set by CKMKER's key mapping will be superseded when
  536. Kermit applies the selected parity to outbound characters.
  537. @End(Quotation)
  538.  
  539. The SET MODIFIER KEYS dialog also lets you select your meta preferences:
  540. whether you want to use the 8th bit toggled on, or a prefix string.  The prefix
  541. string is entered in the same manner as a function definition (backslash
  542. followed by 3 octal digits for non-printable characters, see below).
  543.  
  544. Note that it is possible to cause ambiguities when selecting and using
  545. modifier keys.  For example say you set OPTION to refer to the control map,
  546. and you set CAPS LOCK to refer to the caps map; at this point if you hold
  547. both OPTION and CAPS LOCK down it is unclear which map you want your
  548. character to come from.  To try to prevent this type of ambiguity the SET
  549. KEY dialog will beep when you are holding down or mousing an ambigous set
  550. of modifier keys.
  551.  
  552. The Kermit code itself references maps in this precendence: if a control map
  553. modifier is depressed then use control map, else if a capslock modifier is
  554. depressed use capslock, otherwise use the normal map.
  555.  
  556. A sample modifier key configuration is shown in Figure @ref<-macmkey>.
  557. @Begin(Figure, Use Example)
  558. @bar()
  559. @blankspace(1)
  560.                  OPTION          COMMAND         CAPS LOCK
  561.  
  562.                  o  Normal       *  Normal       o  Normal
  563.                  *  Control      o  Control      *  Control
  564.                  o  Caps         o  Caps         o  Caps
  565.                 [X] Meta        [X] Meta        [ ] Meta
  566. @caption(Macintosh Kermit Modifier Key Dialog)
  567. @tag<-macmkey>
  568. @bar()
  569. @End(Figure)
  570. Here the CAPS LOCK key is used to reference "control", the COMMAND key to do
  571. the "meta" operation, and OPTION is "control-meta".  Holding down COMMAND and
  572. CAPS LOCK together will also result in control-meta.
  573.  
  574. @Paragraph<DIALOG: Set Function Definitions>
  575.  
  576. @i<Background>:
  577.  
  578. Skip to next section if you know what function keys are.
  579.  
  580. Many popular terminals have "function keys" in addition to the alpabetic,
  581. numeric, punctuation, and modifier keys described above.  Function keys are
  582. usually labeled F0, F1, F2, ..., or PF1, PF2, ...  On some terminals, like the
  583. DEC VT100, the function keys send predefined sequences of characters -- for
  584. instance PF1 sends three characters: ESCAPE (ASCII 033), followed by "O", and
  585. "P".  On others, the function keys may have arbitrary strings assigned to them.
  586. For instance, if you find yourself typing "Aaaarrrgggghhh!!! Sigh..." a lot,
  587. you can assign this string to function key F1, and then pressing the F1 key
  588. will cause this entire character string to be transmitted.
  589.  
  590. @i<Macintosh Kermit Function Keys>:
  591.  
  592. The Macintosh has no physical function keys -- no keys are marked F0, F1,
  593. F2, etc.  However, any key (modified by any combination of modifier keys) may
  594. be designated as a "soft" function key.
  595.  
  596. Selecting "Function Definitions..." from the SET menu brings you to the SET
  597. FUNCTIONS dialog (it would be nice if you could double click on a function
  598. key in the SET KEYS dialog but that is not yet available).
  599.  
  600. Use SET FUNCTIONS to declare a function definition string.  Scroll through the
  601. function definition list and select a function to define, preferably starting
  602. with F0, though this is not required (high numbered functions are reserved for
  603. special uses).  Type in the function definition; non printable characters must
  604. be entered with a backslash ("\") followed by exactly (yes exactly) three octal
  605. characters representing the ASCII value, for instance "\015" for carriage
  606. return.  A backslash itself is entered as "\134".  The function definition has
  607. to fit in the box.
  608.  
  609. Having defined a function, you must use SET KEYS to actually associate it with
  610. a key.  Note that it is possible to associate a function with more than one
  611. key.
  612.  
  613.  
  614. @Paragraph<DIALOG: Set Keys>
  615.  
  616. Selecting the "Keys..." menu item under SET initiates the SET KEYS dialog
  617. for redefining individual keys.
  618.  
  619. SET KEYS displays a picture of the keyboard.  You can either hold down the
  620. modifier and key you wish to define or click on the displayed picture with the
  621. mouse (double clicking on one of the modifier keys brings up the SET MODIFIER
  622. KEYS dialog).  Once a key is selected, it and any modifiers are highlighted,
  623. the name of the key and its value are displayed in the lower portion of the
  624. dialog.  You may enter the new value in the little box by selecting the box
  625. with the mouse and then typing a DECIMAL (yes decimal) number from 0 to 127.
  626. Then you should click on either SET KEY or else SET FUNCTION KEY.  Clicking on
  627. SET KEY means that the key should transmit the ASCII character corresponding to
  628. the given value (subject to modification by the meta key); clicking SET
  629. FUNCTION KEY means the number you entered in the box is a function number and
  630. that the key should transmit the character string associated with that
  631. function.
  632.  
  633. SET KEYS does not display a picture of the numeric keypad, but may be used with
  634. the keypad anyway -- just select the desired key by pressing it and then define
  635. it as above.
  636.  
  637.  
  638. @SubSection<MENU: File>
  639.  
  640. The File menu must be used to Open a Kermit settings file before CKMKEY will
  641. allow you do perform any other operations.  You may also Quit from CKMKEY
  642. through the File menu, and you can save your work.  The Save option allows
  643. you to save the settings file back under its own name, replacing the previous
  644. copy.  If you need to make copies of settings files, you can use Kermit itself
  645. to save them under different names, or else you can use the Finder.
  646.  
  647. There is also a Decompile option, that is of use only to programmers working
  648. on Macintosh Kermit -- it decompiles the key definition resource into a form
  649. that can be included in a C program.
  650.  
  651. @subSection<CKMKEY Known Limitations, Restrictions, Bugs>
  652.  
  653. @Begin(Itemize)
  654. There is no picture of the numeric keypad in Set Keys.
  655.  
  656. In Set Keys, when you strike a key on the numeric keypad, its name is not
  657. displayed.  You can still make assignments to the key.
  658.  
  659. There is no way to define a key from the numeric keypad unless you actually
  660. have a numeric keypad.
  661.  
  662. You can't save from CKMKEY under a different name.  Use the Finder or Kermit
  663. to do that.
  664.  
  665. You must use decimal numbers in the SET KEY dialog, and backslash followed
  666. by 3 octal digits in function definitions, which can be confusing.
  667.  
  668. You may have problems on a 128K mac if you define many long functions.
  669.  
  670. CKMKEY doesn't deal with write protected diskettes very well.
  671. @End(Itemize)
  672.  
  673. @subSection<Unlocking CAPS LOCK>
  674.  
  675. (Adapted from directions posted by David Chase @q(<rbbb@@rice>) on
  676. @q(INFO-MAC@@SUMEX-AIM), Friday 14 December 1984.  Follow these instructions at
  677. your own risk.  Not the authors, nor David Chase, nor Columbia University, nor
  678. Rice University provide any warranty, nor acknowledge any liability or
  679. responsibility for damage, injury, inconvenience, or loss of Apple or other
  680. service warranty sufferred as a result of the publication of these directions.)
  681.  
  682. A major impediment to using the Macintosh as a terminal is that the CAPS LOCK
  683. key is where you would normally expect to find the CONTROL key.  A key
  684. redefinition package, such as CKMKEY, can assign the CONTROL function to the
  685. COMMAND or OPTION keys but these keys are not easy to reach.  CONTROL can
  686. also be assigned to the CAPS LOCK key using software, but the CAPS LOCK key
  687. includes a mechanical locking device.  The following directions tell how to
  688. remove the locking device so that the CAPS LOCK key will go up and down
  689. like the other keys.  PROCEED AT YOUR OWN RISK.
  690.  
  691. Tools you'll need:
  692. @Begin(Itemize,spread 0.25)
  693. Phillips screwdriver for screws on bottom of the keyboard.
  694.  
  695. Solder sucker/wick.
  696.  
  697. Soldering iron.
  698.  
  699. Small prying tools (jewelers screwdrivers, small knife blade, etc).
  700.  
  701. Tweezers/small needlenose pliers.
  702.  
  703. Some paper clips or straight pins.
  704. @End(Itemize)
  705.  
  706. Now follow these steps:
  707. @Begin(Enumerate)
  708. Remove the five screws.  The keyboard should fall into three pieces.
  709.  
  710. GENTLY pry off the Caps Lock keycap.  This takes a little patience.
  711.  
  712. Remove the restoring spring so it doesn't get in the way.
  713.  
  714. Locate the two connections to the Caps Lock key on the back of the PC
  715. board, and remove all solder from them using wick or sucker.  Be
  716. careful not to overheat the solder pads, since they can be damaged
  717. (come loose from the PC board).
  718.  
  719. Pry back the plastic locking clips holding the key in, and remove it.
  720. (All the keys are clipped into a metal frame.  Removing the metal frame
  721. is not possible, since all the keys are soldered to the PC board, and
  722. clipped to the frame.  The clips are located "north" and "south" of the
  723. key, where the number row is "north" and the space bar "south".)
  724. There are four clips holding the bottom of the key on; pry these back,
  725. and, WHILE HOLDING THE KEY BOTTOM UP, remove the bottom of the key.
  726. You may have to use some makeshift tools, like a couple of unbent paper clips,
  727. to hold the four clips open.
  728.  
  729. Two pieces should be ready to fall out; a small piece of PC-board-like
  730. material (about 7/16 by 3/32 inch, with two notches on one edge and a
  731. tiny hole in the center), and a tiny piece of wire (a small, beefy
  732. staple with short legs).  Let them fall out. (It may help to toggle the
  733. key).  These two pieces are the locking device, they should be removed
  734. and left out of the reassembly.
  735.  
  736. Replace the restoring spring, snap the key back into place, resolder
  737. the two leads, screw the keyboard back together, and replace the key
  738. cap.  You may wish to experiment with the spring to reduce the key's
  739. springiness (this can be done with the keyboard assembled, though
  740. removing the cap is more difficult).
  741. @End(Enumerate)
  742.  
  743. For those who want to map the CAPS LOCK key to CTRL, but don't want to alter
  744. the keyboard as described in the manual, but still want to inhibit the locking
  745. function, the following suggestion is offered:
  746.  
  747. Pry off the key using a small screwdriver.  There is a spring whose end
  748. goes through the plastic support.  Stick a very small wad of paper or soft
  749. putty between the tip and the bottom of the keyboard.  This will prevent the
  750. key from depressing all the way and locking, but still allow contact of the
  751. key.  Eventually, the paper will work loose and you will need to find it
  752. and repeat the procedure.
  753.