home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / e / ebut10.zip / ebuttons-1.0 / README < prev    next >
Text File  |  1992-11-28  |  5KB  |  144 lines
  1.               Ebuttons - an X interface to emacs.
  2.  
  3.          Terry Jones (terry@santafe.edu), November 18, 1992.
  4.                       Santa Fe Institute
  5.  
  6.  
  7.  
  8. INTRODUCTION
  9. ------------ 
  10.  
  11. This program provides an X interface to issue commands to an emacs
  12. session.  It allows you to specify (in an X resource file) labels for
  13. a set of buttons and a command for each that will be executed when the
  14. corresponding button is clicked on with the mouse. For instance you
  15. can define buttons to compile, to find the next error, to save
  16. buffers, to move to the top/bottom of the buffer, to exit emacs etc.
  17. etc.
  18.  
  19. The idea is that this should be a thin vertical window that sits just
  20. to the side of an emacs session and allows for fast execution of some
  21. things. It is not intended to replace the keyboard! It just gives
  22. another option - if your hand is already on the mouse, use ebuttons.
  23. If not, use the keyboard. Or as you like it. The window can also be
  24. made horizontal (see below) but then not as many buttons will fit on
  25. the screen.
  26.  
  27. Ebuttons is intended to run as a subprocess to an emacs session.  It is
  28. controlled by the elisp code in ebuttons.el.  After loading ebuttons.el,
  29. executing the "ebuttons" function from within emacs will start the program.
  30. Since the program uses X, you have to be running X.  See the installation
  31. notes later in this document for more detail.  Note that this program does
  32. NOT require you to use the X version of emacs.  You must be running X, but
  33. you can use the non-X version of emacs.
  34.  
  35. Ebuttons was implemented under GNU emacs version 18.58. It should run
  36. on earlier versions of GNU emacs.
  37.  
  38. This program is adapted from the taglist facility written by Brad
  39. Mears (bmears@deltahp.jsc.nasa.gov). In fact, he should get almost all
  40. the credit. I have never written a line of elisp code, what you see in
  41. ebuttons.el is the result of deleting about 80% of his taglist.el.
  42. The X code looks somewhat different, but, again, is a result of
  43. editing a copy of taglist.c (as is this README).
  44.  
  45. I decided that this would be a nice thing to have after using taglist
  46. for a time and realizing that I liked the command buttons better than
  47. the tags. Plus, the tags list kept (necessarily) resizing and
  48. obscuring my emacs window. A further step would be to rewrite taglist
  49. so that it didn't have a set of buttons - it could be controlled from
  50. a button in an ebuttons window.
  51.  
  52. COMPONENTS
  53. ----------
  54. README          - this file.
  55. Makefile        - that file.
  56. Resources       - a sample set of resources for this program.
  57. ebuttons.c      - source code.
  58. ebuttons.el     - run-time elisp program.
  59. ebuttons.1      - a man page.
  60. make_ebuttons   - a shell script that generates some code for ebuttons.c.
  61.  
  62. INSTALLATION
  63. ------------
  64. 1 - Edit Makefile and run make. This will make you an executable 
  65.     and also format the manpage (putting the result in ebuttons.cat)
  66.  
  67. 2 - Copy the resulting executable (ebuttons) to some directory that is
  68.     in your path.
  69.  
  70. 3 - Copy the elisp program ebuttons.el to wherever you keep your
  71.     elisp code.
  72.  
  73. 4 - Customize the labels and commands used by the buttons. See the
  74.     file "Resources" for examples. Add the resources you want to
  75.     your .Xdefaults or .Xresources (or wherever) file.
  76.  
  77. 5 - (Optional)  Modify your .emacs file to load and run ebuttons at startup.
  78.     I do this via:
  79.   
  80.     (if (equal window-system 'x)
  81.         (progn
  82.       (load "ebuttons")
  83.       (ebuttons)))
  84.  
  85. 6 - (Optional) Modify your .emacs file so that ebuttons-toggle-screen
  86.     is bound to some key.
  87.  
  88.     (define-key global-map "\^Xt" 'ebuttons)
  89.     
  90.     Note that this is the key that was suggested for taglist, so if
  91.     you want to use both and have taglist on C-x t, come up with your
  92.     own arrangement.
  93.  
  94.  
  95. RUNNING ebuttons
  96. ----------------
  97.  
  98. The simplest method is to, as described above, have ebuttons start
  99. automatically when your emacs starts. Otherwise you can invoke it
  100. manually with M-x ebuttons (or C-x t if you have it bound there).
  101.  
  102. The (ebuttons) function has two purposes.  It either starts the ebuttons
  103. program or, if the program is already running, sends a signal to it that
  104. causes the program to hide/expose the ebuttons window.
  105.  
  106. To use the program, simply click on the button that represents the
  107. command you want executed.
  108.  
  109.  
  110. RESOURCES
  111. ---------
  112.  
  113. Your resource file should have pairs of lines like
  114.  
  115.     ebuttons.labelX:                 label
  116.     ebuttons.commandX:               (emacs-command)
  117.  
  118. where X is any number from 0 to the number of possible buttons minus
  119. one. The upper limit is set in the Makefile and is 50 in the
  120. distribution. Label numbers may be omitted (i.e. you can define labels
  121. 1, 2 and 5, omitting 3 and 4) - if you only define 3 buttons, only 3
  122. will appear. Actually this is not entirely true, an extra button (the
  123. last button in the window) is added. It causes the ebuttons program to
  124. exit and is (usually) labelled Quit.  You can change the name that
  125. appears on this button (if you wish) with:
  126.  
  127.     ebuttons*Quit.label: your-label
  128.  
  129. in your resource file. Other resources that will have useful effects
  130. are
  131.  
  132.     ebuttons*Command.borderWidth
  133.     ebuttons*Box.orientation
  134.     ebuttons*Box.hSpace
  135.     ebuttons*Box.vSpace
  136.     ebuttons.geometry
  137.     ebuttons*background
  138.     ebuttons*font
  139.  
  140. Look in the Resources file for an example of settings for these. My
  141. preference is to have the ebuttons window take up as little space as
  142. possible, so I use a small font and leave no vertical or horizontal
  143. space between the command buttons.
  144.