home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / myckeys.zip / README < prev   
Text File  |  1994-03-11  |  9KB  |  275 lines
  1. /* readme  - this is the readme file of the MyCKeys package  940304 */
  2.  
  3. MyCKeys is an EPM editing mode for C code.  It provides automatic 
  4. indentation, expansion and highlighting.
  5.  
  6. The following text describes how to install this EPM mode, and what 
  7. features it provides.
  8.  
  9. This package contains the following files:
  10.  
  11.    [eas]          -- extended attributes directory
  12.    myckeys.c      -- C source sample
  13.    myckeys.e      -- editing mode source
  14.    myckeys0.ex    -- stand-alone compiled version (for ebookie users)
  15.    myckeys1.ex    -- stand-alone compiled version
  16.    readme         -- this file!
  17.  
  18.  
  19. INSTALLATION:
  20. =============
  21.  
  22. You can install MyCKeys in three ways.  If you are not using ebookie,
  23. the first method is for you (isn't that nice ? :-).  The second method
  24. is for ebookie users, but you will have to invoke a command whenever you
  25. load a C source file(*).  The third method will handle this automatically,
  26. even for ebookie users, but you will have to recompile your editor macros.
  27.  
  28. (*) This is a Bad Thing(TM), but EPM does not allow an
  29.     externally-linked module to define a defload procedure.  This
  30.     is my main grief against EPM.  (Another grief is the lack of an
  31.     automatic parent-matching feature, à la EMACS...  You can
  32.     simulate it, but it's way too slow, and quirky.)
  33.  
  34.  
  35.  'Quick' installation:                (It does NOT work with ebookie)
  36.  ---------------------
  37.  
  38.     0. rebuild extended attributes for myckeys.c
  39.  
  40.        eg: cd a: & eautil /j myckeys.c
  41.  
  42.     [0bis. Optionally, rebuild myckeys.e extended attributes]
  43.  
  44.     1. copy myckeys0.ex somewhere in your EPMPATH, and rename it 
  45.        myckeys.ex
  46.  
  47.        eg: copy a:myckeys0.ex c:\os2\apps\myckeys.ex
  48.  
  49.     2. start EPM, and load myckeys.c
  50.  
  51.        eg: start epm a:myckeys.c
  52.  
  53.        [This step is important.  It will define three styles (you can
  54.         redefine them, but don't change their names):
  55.  
  56.                Case
  57.                Commentaire(*)
  58.                Function
  59.  
  60.        (*) Well, I should have name it 'Comment', but it's too late,
  61.            now :-) ]
  62.  
  63.     3. Link MyCKeys, by issuing the command 'link MyCKeys'
  64.  
  65.        [You'll have to link myckeys each time you start an EPM
  66.         session.  A good solution is to put the 'link MyCKeys'
  67.         command in your profile.erx file (you may have to activate
  68.         the profile support by issuing the 'profile on' command).]
  69.  
  70.     [3bis. Enable syntax expansion, by issuing the 'expand on'
  71.            command, if you have previously disabled it.]
  72.  
  73.     And here you are...
  74.  
  75.  
  76.  'Quick'n dirty' installation:
  77.  -----------------------------
  78.  
  79.     0. rebuild extended attributes for myckeys.c
  80.  
  81.        eg: cd a: & eautil /j myckeys.c
  82.  
  83.     [0bis. Optionally, rebuild myckeys.e extended attributes]
  84.  
  85.     1. copy myckeys1.ex somewhere in your EPMPATH, and rename it
  86.        myckeys.ex
  87.  
  88.        eg: copy a:myckeys1.ex c:\os2\apps\myckeys.ex
  89.  
  90.     2. start EPM, and load myckeys.c
  91.  
  92.        eg: start epm a:myckeys.c
  93.  
  94.        [This step is important.  It will define three styles (you can
  95.         redefine them, but don't change their names):
  96.  
  97.                Case
  98.                Commentaire(*)
  99.                Function
  100.  
  101.        (*) Well, I should have name it 'Comment', but it's too late,
  102.            now :-) ]
  103.  
  104.     3. Link MyCKeys, by issuing the command 'link MyCKeys'
  105.  
  106.        [You'll have to link myckeys each time you start an EPM
  107.         session.  A good solution is to put the 'link MyCKeys'
  108.         command in your profile.erx file (you may have to activate
  109.         the profile support by issuing the 'profile on' command).]
  110.  
  111.     4. Whenever you load a C file, issue the 'MyCKeys' command.
  112.  
  113.     [4bis. Enable syntax expansion, by issuing the 'expand on'
  114.            command, if you have previously disabled it.]
  115.  
  116.     And here you are...
  117.  
  118.  
  119.  'Slow' installation:
  120.  --------------------
  121.  
  122.     This installation is not properly speaking 'slow', but it's for 
  123.     more experienced users.  You'll have to recompile epm.ex and 
  124.     extra.ex.
  125.  
  126.     0. rebuild extended attributes for myckeys.c and myckeys.e
  127.  
  128.        eg: cd a: & eautil /j myckeys.c & eautil /j myckeys.e
  129.  
  130.     1. Go to your E macros directory
  131.  
  132.        eg: d: & cd \src\epm551\embarks
  133.  
  134.     2. rename ckeys.e ckeys.org, or whatever you want...
  135.  
  136.        eg: ren ckeys.e ckeys.org
  137.  
  138.     3. copy myckeys.e in this directory, and rename it ckeys.e
  139.  
  140.        eg: copy a:myckeys.e ckeys.e
  141.  
  142.     4. recompile epm.ex and extra.ex.  Put those new files in your 
  143.        EPMPATH
  144.  
  145.        eg: etpm epm & etpm extra & copy *.ex c:\os2\apps
  146.  
  147.     5. Start EPM, and load myckeys.c
  148.  
  149.        eg: start epm a:myckeys.c
  150.  
  151.        [This step is important.  It will define three styles (you can
  152.         redefine them, but don't change their names):
  153.  
  154.                Case
  155.                Commentaire(*)
  156.                Function
  157.  
  158.        (*) See comment in 'Quick installation', step 2]
  159.  
  160.     [5bis. Enable syntax expansion, by issuing the 'expand on'
  161.            command, if you have previously disabled it.]
  162.  
  163.     6. Exit EPM
  164.  
  165.     And that's all.  MyCKeys mode will be automatically invoked 
  166.     whenever you load a C file.
  167.  
  168.  
  169. FEATURES:
  170. =========
  171.  
  172.     MyCKeys mode provides the following features for files whose 
  173.     extension is one of '.c', '.h', '.ph', '.cpp', '.cxx' or '.sqc'
  174.  
  175.  Automatic indentation:
  176.  ----------------------
  177.  
  178.     I like STREAM mode.  But in this mode, standard EPM does not 
  179.     provide auto indentation.  MyCKeys provides it for STREAM mode.
  180.  
  181.     In addition, there is a function you can assign to your favorite
  182.     key : indentline.  If you want to assign it to the tab key, put the
  183.     following in your profile.erx:
  184.  
  185.          'buildaccel *' 1 9 9300 indentline
  186.          activateaccel
  187.  
  188.  Syntax expansion:
  189.  -----------------
  190.  
  191.     MyCKeys mode provides the same C expansion as standard EPM. 
  192.     (Well, I've customized it a bit, but you can override my changes 
  193.     by making changes in the 'expansion control constants' part of 
  194.     myckeys.e, and recompiling it...)
  195.  
  196.     Involved statements:
  197.  
  198.          if
  199.          for
  200.          do
  201.          while
  202.          switch
  203.          case
  204.          /* */
  205.          main
  206.  
  207.  Highlighting:
  208.  -------------
  209.  
  210.     I like code highlighting very much.  But I don't like syntax
  211.     highlighting as done by, say, Borland IDE...  I don't care having 
  212.     all semi-colons showing in green.  It's not important.  Even 
  213.     worse, it's distracting...
  214.     Instead, I would be pleased to see all functions headers in green
  215.     (or whatever color you like, as long as it's green :-), and things
  216.     like that.  In fact, I want highlighting to carry a semantic 
  217.     meaning, more than just a syntactic one...  
  218.  
  219.     So does MyCKeys.  It's far from perfect, but it's better than 
  220.     nothing... and it suits my needs, with acceptable constraints :-)
  221.  
  222.     It highlights comments, case statements and functions headers.  It
  223.     does on-the-fly highlighting, but it does not (yet) highlight 
  224.     pre-existing code.
  225.  
  226.     [The following heuristic is used to recognize a function header:
  227.  
  228.      When you type an opening brace in column 1, and if the first word
  229.      of the previous line is not 'typedef', then the function header 
  230.      starts at the first character of the nearest line whose first 
  231.      character is in column 1, and ends just before the opening brace.
  232.      (endembed comments are preserved.)
  233.  
  234.      The following heuristic is used to recognize a comment:
  235.  
  236.      When you type '/*', followed by a space, a comment is recognized,
  237.      the comment closing sequence '*/' is typed in, and highlighting 
  238.      is done.
  239.  
  240.      And the following heuristic is used to recognize a case 
  241.      statement:
  242.  
  243.      When you press the Enter key on a line whose first word is 
  244.      'case', then the whole line is highlighted.]
  245.  
  246.     [Remember! You should have syntax expansion enabled in order to 
  247.     use automatic highlighting (use the 'expand on' command)]
  248.  
  249. KNOWN BUGS/PROBLEMS:
  250. ====================
  251.  
  252.     If a comment follows a case statements on the same line, and if 
  253.     you press the Enter key on this very line, the comment will take
  254.     the case statement color. (except for the first case of a switch
  255.     statement :-)
  256.     FIX: go to the end of line, and press Ctrl-Enter
  257.  
  258.     Comments are only recognized and highlighted when they are typed
  259.     at the end of the line.
  260.     FIX: none, but it may be fixed in a next version.
  261.  
  262.     Whenever an EPM action issues a replacestring command, 
  263.     highlighting on the involved lines will be lost.
  264.     FIX: this is an EPM problem.  The replacestring command is not 
  265.          attribute-aware...
  266.  
  267.     And many others, but they're all features :-)
  268.  
  269.  
  270. Any comments and suggestions welcome...
  271.  
  272. --
  273. Martin Lafaix
  274. lafaix@sophia.inria.fr
  275.