home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / c / sas-c-emacs-b3.lha / sas-c.doc < prev    next >
Encoding:
Text File  |  1994-09-28  |  11.0 KB  |  369 lines
  1.                    
  2.                   sas-c-mode
  3.                   ~~~~~~~~~~
  4.  
  5.                   Beta V0.3
  6.  
  7.          Copyright (C) 1993-1994 by Anders Lindgren.
  8.                    
  9.  
  10.                    
  11.                  DISTRIBUTION
  12.  
  13.     sas-c-mode is free software; you can redistribute it and/or modify
  14.     it under the terms of the GNU General Public License as published 
  15.     by the Free Software Foundation; either version 1, or (at your 
  16.     option) any later version.
  17.  
  18.     GNU Emacs is distributed in the hope that it will be useful,
  19.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  20.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21.     GNU General Public License for more details.
  22.  
  23.     You should have received a copy of the GNU General Public
  24.     License along with GNU Emacs; see the file COPYING.  If not,
  25.     write to the Free Software Foundation, 675 Mass Ave, Cambridge,
  26.     MA 02139, USA.
  27.  
  28.  
  29.     SAS and SAS/C are registrated trademarks of SAS Institute Inc.
  30.  
  31.                    
  32.                  INTRODUCTION
  33.  
  34. This package is the glue that ties the SAS/C message handler, SCMSG,
  35. to GNUEmacs for automatic error message reporting. The package gives
  36. Emacs all the knowledge about errors normally stored in the SCMSG
  37. utility. It also enables SCMSG to automatically bring Emacs to the
  38. front, place the cursor on the correct line in the correct file, and
  39. display the error information in the minibuffer.
  40.  
  41. sas-c-mode is in GNU Emacs terms a minor mode. This means that it is
  42. an addition to the current major mode, such as c-mode. When enabled
  43. the text "SAS/C" will be present to the right of the the name of the
  44. current mode. The sas-c-mode rebinds keys of the current local keymap,
  45. when it is terminated the original definitions are restored.
  46.  
  47. The idea behind makeing sas-c-mode a minor, as opposed to major, mode
  48. is to be able to use the features of c-mode. It can also be enabled
  49. when editing smakefiles or assmebler files.
  50.  
  51.  
  52.                  REQUIREMENTS
  53.  
  54. Atleast SAS/C V6.0 and Emacs V1.28 are required for this program.
  55. However SAS/C V6.50 is recomended.
  56.  
  57.  
  58.                 FILES
  59.  
  60. Files contained in this package:
  61.  
  62. sas-c.doc        This file.
  63. sas-c.el        Source code in elisp.
  64. sas-c.elc        Byte-compiled version of the above.
  65. SCMSG.opt.SC_EMACS    Options for SCMSG.
  66. sc_emacs.rexx        Handler for SCMSG->Emacs communication.
  67. quithost.rexx        Terminates sc_emacs.
  68. slashquote/
  69.   slashquote.library    A ARexx host library containing two functions.
  70.   slashquote.doc    A small docfile for the above.
  71.   slashquote.c        The sourcecode.
  72.   slashquote.fd        Library description file, used by slink to build
  73.             the library.
  74.   smakefile        file containing rules for building 
  75.             slashquote.library
  76.  
  77.  
  78.                    INSTALL
  79.  
  80. * The library "slashquote.library" should be placed in LIBS:
  81.  
  82. * Place the file `sas-c-mode.elc' into a lisp directory (for 
  83.   example GNUEmacs:lisp)
  84.  
  85. * Move sc_emacs.rexx and quithost.rexx to your rexx: directory.
  86.  
  87. * Copy SCMSG.opt.SC_EMACS to ENV:sc/SCMSG and ENVARC:sc/SCMSG.
  88.  
  89. * Turn on the ErrorRexx option in SCOPTS.
  90.  
  91. * The following line should be placed in s:.emacs
  92.  
  93.     (autoload 'sas-c-mode "sas-c" nil t)
  94.  
  95. * If you would like the sas-c-minor mode to be activated automagically
  96.   when editing C-files, place the following lines into your s:.emacs
  97.  
  98.     (setq c-mode-hook 
  99.           (function (lambda ()
  100.               ;;; Other thing to do when entering 
  101.               ;;; c-mode goes here.
  102.               (sas-c-mode 1))))
  103.  
  104.     
  105. If you know how to give the command "evaluate-region" on the lines
  106. entered into s:.emacs, do it. Otherwise quit and restart emacs.
  107.  
  108.  
  109.                    EXAMPLE
  110.  
  111. A normal sequence of events is the following:
  112.  
  113. * You compile a program, and an error occur. If no error occured, 
  114.   something must be very unnormal :-)
  115. * The SCMSG is started by the compiler, if it's option RexxOnly
  116.   is activated, no window is opened.
  117. * Automatically (if AUTOEDIT is enabled), or when an error is
  118.   doubleclicked, the SC_EMACS host is started. (Please see the section
  119.   `KNOWN PROBLEMS' below).
  120. * Emacs is started, if it isn't already running.
  121. * The cursor is placed on the correct line in the correct file
  122.   and the current errormessage is displayed in the minibuffer.
  123. * The message will disappear if the cursor is moved; press
  124.   C-c C-l to redisplay it.
  125. * Press C-c C-n to see next error, or C-c C-d to delete the current and
  126.   see next.
  127. * The SCMSG utility can be used to browse errors. Just doubleclick on
  128.   the errors to edit it in Emacs.
  129. * When done, press C-c C-c to rebuild the project.
  130.  
  131.  
  132.                 USAGE
  133.  
  134. The following keys are defined by default when sas-c-mode is
  135. active:
  136.  
  137. C-c C-a        Display the alternative file, if any.
  138. C-c C-c        Build a project (normally execute smake).
  139. C-c C-d        Delete the current message and display next.
  140. C-c C-h        Hide the SCMSG window.
  141. C-c C-l        Redisplay current error message.
  142. C-c C-n        Display next error message.
  143. C-c <down>        ---- " ----
  144. C-c C-p        Display previous error message.
  145. C-c <up>        ---- " ----
  146. C-c C-q        Remove all messages for a certain primary file.
  147. C-c C-s        Show the SCMSG window.
  148. C-c <        Go to the first error message.
  149. C-c <sh. up>        ---- " ----
  150. C-c >        Go to the last error message.
  151. C-c <sh. down>        ---- " ----
  152.  
  153. When an error is displayed, the mark is set at the previous cursor
  154. position. Press C-x C-x to return to the old position.
  155.  
  156.  
  157. The message is displayed in the following forms:
  158.  
  159.     Class #: text
  160.  
  161. Where Class is "Error", "Warning" or "Info". # is the error number and
  162. text is the actual message. If there exists an alternate file the string
  163. "(Alt)" is placed immediately to the left of the colon. To see it, press
  164. C-c C-a. The primary file can always be reviewed by pressing C-c C-l.
  165.  
  166.  
  167.                   VARIABLES
  168.  
  169. sas-c-mode    non-nil if in sas-c minor mode. READ ONLY.
  170.  
  171. sas-c-compile-command
  172.         Command to use when building project (default "sc:c/smake").
  173.  
  174.  
  175.                   FUNCTIONS
  176.  
  177. sas-c-bottom    Go to the last message.
  178.  
  179. sas-c-build    Rebuild the current project. This is done by executing
  180.         the command in the variable sas-c-compile-command.
  181.         
  182. sas-c-delete    Delete the current error message and move to the next.
  183.  
  184. sas-c-delcomp-current    
  185.         Delete all messages with the same primary filename
  186.         as the current error. NOTE: This function does not take
  187.         the filename from the current buffer.
  188.         Also note: This function is not bound to a key since
  189.         I belive it's a little bit unintuitive.
  190.  
  191. sas-c-delcomp    Prompt for a for a filename to remove from the error list.
  192.         Default is current buffer.
  193.  
  194. sas-c-delfile-current    
  195.         Same as sas-c-delcomp-current, but for secondary file.
  196.  
  197. sas-c-delfile    Same as sas-c-delcomp, but for secondary filename.
  198.  
  199. sas-c-display-altfile
  200.         This function displays the alternate file and places
  201.         the cursor on the corrent line.
  202.  
  203. sas-c-display-error
  204.         This function displays the current error and places the
  205.         cursor on the offending line.
  206.  
  207. sas-c-hide    Close the SCMSG window.
  208.  
  209. sas-c-next    Move to the next error message.
  210.  
  211. sas-c-prev    move to the previous error message.
  212.  
  213. sas-c-show    Show the SCMSG window. If called with an argument
  214.         the window gets unactivated. (i.e. call if called
  215.         with C-u M-x sas-c-show RET.)
  216.  
  217. sas-c-top    Go to the top of error messages.
  218.  
  219.  
  220.                 CUSTOMIZATION
  221.  
  222. The sac-c-mode can be custimized. a special variable sas-c-mode-hook
  223. is defined for this purpose. It shall be defined as below:
  224.  
  225. (setq sas-c-mode-hook 
  226.       (function (lambda ()
  227.           ;;; Things to do here
  228.           )))
  229.  
  230. When defining new keys the function sas-c-define-key must be used. If
  231. not, the mechanism which removes the keybindings when sas-c-mode is
  232. terminated won't work.
  233.  
  234. For example:
  235.  
  236. (setq sas-c-mode-hook 
  237.       (function (lambda ()
  238.           (sas-c-define-key "\C-x`" 'sas-c-next)
  239.           (sas-c-define-key "\C-c\C-q" 'sas-c-delcomp-current))))
  240.  
  241. This defines C-x ` as sas-c-next. This is quite useful for people
  242. who are used to the old "compile" macro. It also redefines the
  243. key C-c C-q to use sas-c-delcomp-current, instead of sas-c-delcomp.
  244.  
  245.  
  246.                  TIPS n'TRIX
  247.  
  248. If you are going to compile from within emacs, I recomend using
  249. the NOERRORHIGHLIGHT and BATCH flags.
  250.  
  251. It is useful to be able to compile (C-c C-c) from a makefile. I normally
  252. places the following lines into the header of the makefile to make it
  253. use the sas-c minor mode:
  254. (According to Emacs rules the local variables should be placed on
  255. the last page of the file.)
  256.  
  257. #       Local Variables:
  258. #       eval:(sas-c-mode 1)
  259. #       End:
  260.  
  261.  
  262.                 HOW TO EXPAND
  263.  
  264. sas-c-mode can be expanded with new clever commands, just start up
  265. your brain!
  266.  
  267. The following ELisp functions can be useful:
  268.  
  269. (sas-c-view-message file line text class errnum)
  270.     Display the actual error message. It reads in the file, if
  271.     it's not in any buffer. It then shows the buffer and places
  272.     the cursor on the correct line and displays the errortext.
  273.  
  274. (sas-c-get-file file)
  275.     Used by above.
  276.  
  277. (sas-c-scmsg command)
  278.     Send a ARexx command to SCMSG without requesting a resultstring.
  279.  
  280. (sas-c-scmsg-str command)
  281.     Send a ARexx command to SCMSG and return the resultstring.
  282.  
  283. (sas-c-scmsg-str command)
  284.     Send a ARexx command to SCMSG and return a number.
  285.  
  286.  
  287.                 KNOWN PROBLEMS
  288.  
  289. 1) SCMSG has given me quite a headache during the development due to a
  290. unfoutnate combination of bad design and bugs. The main problem is
  291. that the mechanism which calls the editor can't be used directly since
  292. it often emits strings with quotes, resulting in syntactically
  293. incorrect ELisp statements. It also only quotes filenames containing
  294. spaces resulting in inconsistency when writing a template of the form:
  295.  
  296.     (sas-c-get-file "%f")
  297.  
  298. which is expanded into:
  299.  
  300.     (sas-c-get-file ""foo bar.c"")
  301.  
  302. which also is an incorrent ELisp statement.
  303.  
  304. The solution to the problem is the sc_emacs ARexx host which
  305. translates all SCMSG messages into lisp statements.
  306.  
  307.  
  308. 2) When scmsg is started for the first time the option `AutoEdit' is
  309. ignored. The result is that Emacs isn't activated until the second
  310. compilation. A simple workaround is to start SCMSG once, before
  311. starting to compile. If you compile a lot and you've got a lot of
  312. memory you can start scmsg at boot time.
  313.  
  314. The following line does the trick:
  315.     run scmsg HIDDEN
  316.  
  317.  
  318.                  TODO
  319.  
  320. Sometime, I would like to write an installer script and to TeXInfo:ify
  321. this documentation. However, I have been waiting for some spare time
  322. to do it on the past six months, without luck. Finally I decided that
  323. you folks probably would like to have it even without the fancy
  324. stuff...  and here it is.
  325.  
  326. When is V1.0 about to come? Soon, I just want to run this one through
  327. the toughest test avaiable; the Amiga development community.
  328.  
  329.  
  330.                    HISTORY
  331.  
  332. 24-Mar-93 V0.1  - First release 
  333.  
  334. 09-Jun-93 V0.2  - sc_emacs.rexx added, enabeling SCMSG => Emacs
  335.           communication.
  336.         - Requires Emacs 1.28. (Old ARexx result `bazooka'
  337.           method removed.) 
  338.  
  339. 08-Jul-93 V0.2pl1
  340.         - Now it actually jumps to the correct line :-)
  341.  
  342. 27-Sep-94 V0.3    - SAS/C 6.50:ifyed.
  343.  
  344.  
  345.                  FINAL WORDS
  346.  
  347. I would like to thank the guys at SAS, especially Doug Walker and
  348. James Cooper, for their GREAT C compiler environment and their immense
  349. support. 
  350.  
  351. The english probably contains a lot of spelling and gramatical errors,
  352. please consider that english is not my native toung. Should somebody
  353. find the time to correct the language, nobody would appreciate it
  354. more than myself.
  355.  
  356. Suggestions, new ideas and (positive) criticism are highly
  357. appreciated. Please email them to:
  358.  
  359.     d91ali@student.csd.uu.se
  360.  
  361.     or snail mail them to:
  362.  
  363.         Anders Lindgren
  364.         Kantorsg. 2-331
  365.         754 24 Uppsala
  366.         Sverige
  367.  
  368.                     /Anders Lindgren, 27-Sep-94
  369.