home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / elisp / modes / xmr / README < prev    next >
Encoding:
Text File  |  1992-03-29  |  8.0 KB  |  218 lines
  1. What's New in Version 2.3
  2. -------------------------
  3.  
  4.   - The resource completion/help has been extended to include the WCL
  5.     resources and the constraint resources.
  6.  
  7.   - dm-xmr.el -- A set of Dmacros for XMR mode, which replaces the
  8.     abbreviation stuff.
  9.  
  10.   - The display name is made optional -- it is looked up from DISPLAY.
  11.  
  12.   - Uncommenting region removes only the first `!'.
  13.  
  14.   - xmr-database.sh has been fixed not to generate such long lines.
  15.  
  16.   - Fixed a bug in the hierarchy parsing function that ignored the
  17.     `wcPopups' links.
  18.  
  19.   - New features have been added:
  20.  
  21.     - to indent the current resource set or a region containing resource
  22.       sets.
  23.  
  24.     - to rename the current object.
  25.  
  26.     - to search an object by name.
  27.  
  28.     - to aid in navigating the widget hierarchy -- parent, child, next
  29.       sibling, or previous sibling.
  30.  
  31.  
  32. Please send your comments or bug reports to ik@ctt.bellcore.com.
  33.  
  34.  
  35. Archive Information
  36. -------------------
  37.  
  38. Archive site: archive.cis.ohio-state.edu
  39. XMR mode:     /pub/gnu/emacs/elisp-archive/modes/xmr.tar.Z
  40. Dmacro:       /pub/gnu/emacs/elisp-archive/packages/dmacro.tar.Z
  41.  
  42.  
  43. General Usage
  44. -------------
  45.  
  46. XMR mode is an emacs extension that is useful for editing X/Motif/WCL
  47. resource files. Basically, it helps you to edit large resource files
  48. which can become tedious and repetitive. It also provides an on-line
  49. assistance by keeping track of the valid resources for each widget
  50. class and providing access to the on-line documentation for each
  51. widget class. XMR mode supports a limited amount of run-time
  52. integration as well; however, used in conjunction with other emacs
  53. features (e.g. compile, tags, etc.) you can easily create a fully
  54. integrated environment.
  55.  
  56. The prescribed organization of the resource file is as follows:
  57.  
  58.   - Each widget's resource specifications must be grouped contiguously
  59.     without any intervening blank lines. From here on, I'll refer to
  60.     these resources collectively as the widget's resource set.
  61.  
  62.   - Each resource set must be separated by at least 1 blank line.
  63.  
  64. The package consists of the following files:
  65.  
  66.     README         this file
  67.     dm-xmr.el         Dmacros for XMR mode
  68.     man.el         emacs interface to man (modified for XMR mode)
  69.     xmr-database.el  contains widget specific information
  70.     xmr-database.sh  generates xmr-database.el
  71.     xmr-mode.el         XMR mode extension to emacs
  72.  
  73. In order to load and use it, add something like the following lines to
  74. your .emacs file:
  75.  
  76.     (setq load-path (cons "directory-containing-xmr-mode-stuff" load-path))
  77.     (setq auto-mode-alist (cons '("\\.ad$" . xmr-mode) auto-mode-alist))
  78.     (autoload 'xmr-mode "xmr-mode")
  79.  
  80. Summary of each major feature is as follows.
  81.  
  82. 1. Dmacros and name completion. XMR mode contains a predefined set of
  83. Dmacros for interactively specifying each widget class. (If you don't
  84. know what the Dmacro package is, see below.)
  85.  
  86. For example, suppose you want to specify a resource set for the push
  87. button widget. When, you type Ctrl-c-d (by default), you'll be
  88. prompted for a widget class (Actually a Dmacro, but there is a Dmacro
  89. for each widget class). Type a `?' to see what widget classes are
  90. available. Then, type `push followed by RETURN and the following line
  91. will be inserted:
  92.  
  93.     *<name>.wcClassName:    XmPushButton
  94.  
  95. You'll then be prompted for the widget's name. Type in `testButton'
  96. and you'll get:
  97.  
  98.     *testButton.wcClassName:    XmPushButton
  99.  
  100. By typing Ctrl-J (by default) at the end of the line, you'll get:
  101.  
  102.     *testButton.wcClassName:    XmPushButton
  103.     *testButton
  104.  
  105. Now you can continue to specify the widget's resource, and when you
  106. are at the end of each line, instead of pressing RETURN, type Ctrl-J.
  107.  
  108. In addition to the Motif widget classes, there are Dmacros for other
  109. high-level UI component such as the radio box, generic dialog box,
  110. file menu, etc. So, for example, if you choose the "filemenu" Dmacro,
  111. you'll see the resources which define a file menu and its children.
  112.  
  113. 2. On-line help. XMR mode knows about which resources, including the
  114. inherited resources and the constraint resources, are valid for each
  115. widget class. Thus, when you're editing a widget's resource set, you
  116. can query for the valid resources, provided that you've specified the
  117. widget's class. In WCL (1.0x), this is done by specifying the resource
  118. `wcClass', `wcClassName', or `wcConstructor'. If you are editing
  119. non-WCL resource files, you can still get this help by including one
  120. of these resources in the widget specification. (The resource manager
  121. should simply ignore this entry. If not, just comment it out.)
  122.  
  123. For example, suppose you were't quite sure what resources were
  124. available for the push button above:
  125.  
  126.     *testButton.wcClassName:    XmPushButton
  127.     *testButton.
  128.  
  129. Typing Ctrl-c-h (by default) will list the valid resources;
  130. Ctrl-c-Ctrl-h will list the valid resources, including the inherited
  131. ones. Depending on whether the button's parent is a constraint widget
  132. or not, you may or may not see constraint resources.
  133.  
  134. You have access to the on-line Motif man pages, provided that the man
  135. pages have been installed on your system. When you enter the command
  136. to bring up a man page, it prompts you for a widget class, which
  137. defaults to the widget's class that you are currently editing.
  138.  
  139. In the above example, typing Ctrl-c-m and then RETURN will bring up
  140. the man page for XmPushButton in another buffer.
  141.  
  142. 3. Run-time integration. In order to run the application, you need not
  143. leave the buffer containing the resource file. You just issue a
  144. command and the application that you've specified will be run, which
  145. is Mri by default.
  146.  
  147. 4. Automatic indentation. When you're about to specify the resource
  148. value, typing the tab key will automatically indent so that the point
  149. will be beneath the previous line's resource value.
  150.  
  151. In addition, there are commands to format a resource set or a region
  152. containing resource sets, in such a way that all resource values get
  153. aligned (by default at column 40). The latter two commands are
  154. especially useful after inserting a Dmacro, which may not indent the
  155. resource values.
  156.  
  157. 5. Navigation aid. XMR mode gives you the ability to quickly navigate
  158. around the widget hierarchy. When you're editing a resource set, you
  159. can jump to the widget's parent, its Nth child, or its next or
  160. previous sibling in the hierarchy.
  161.  
  162. 6. Miscellaneous. You can comment out a region of resource
  163. specification or uncommand a commented region of resource
  164. specification. Also, if you are editing a WCL resource file, you can
  165. have the widget hierarchy displayed in another buffer. This is useful
  166. if you want to see the actual widget hierarchy, which is often hard to
  167. tell from just looking at the user interface. This feature may be
  168. extended in the future so that you can use the displayed widget
  169. hierarchy to navigate around.
  170.  
  171.  
  172. What Dmacro is
  173. --------------
  174.  
  175. [
  176.   Name:        Dynamcic Macro
  177.   Author:      Wayne Mesard, WMesard@Oracle.com
  178.  
  179.   Dynamic Macro ("DM") is a facility for inserting structured text in
  180.   Emacs.  In addition to straight textual substitution (already available
  181.   through Emacs' Abbrev mode) DM will insert time- and date-stamps, your
  182.   name and user-id, the current file name, a file's contents, the results
  183.   of a shell command and anything else you can think of.  It can prompt
  184.   the user for strings.  It can also position the cursor within the
  185.   expanded text, and indent the expansion in whatever way is appropriate
  186.   to the current major mode.  DM will also allow you to bind dmacros to
  187.   keys and automatically insert dmacros in new files.
  188. ]
  189.  
  190.  
  191. Extending XMR mode
  192. ------------------
  193.  
  194. You can extend XMR mode in the following ways:
  195.  
  196.   - adding help information for other widget classes
  197.   - modifying XMR mode to work with other widget sets
  198.  
  199. [ to be continued ... ]
  200.  
  201.  
  202. Acknowledgements
  203. ----------------
  204.  
  205. Thanks to the following people's code/ideas:
  206.  
  207.     Gary Levine        Perl code (to be) used by xmr-database.sh
  208.     Ernst Lippe        code to comment/uncomment region
  209.     Eric Rose        man.el
  210.     Andrew Wason    listres suggestion
  211.     Larry Williamson    suggestions for improvement
  212.  
  213.  
  214. Local Variables:
  215. mode: indented-text
  216. eval: (progn (auto-fill-mode 1) (set-fill-column 70))
  217. End:
  218.