home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / vile-src.zip / vile-8.1 / doc / visvile.doc < prev    next >
Text File  |  1998-09-28  |  9KB  |  221 lines
  1.                       VisVile -- Developer Studio Support
  2.                       ===================================
  3. Within a limited context, winvile may be substituted as the default
  4. Developer Studio editor.
  5.  
  6.  
  7. Preconditions
  8. =============
  9. + You must be using Developer Studio version 5 (or later), which exposes
  10.   OLE automation "hooks" that permit winvile to augment and/or replace the
  11.   default editor.  The implementation described within this document will
  12.   not work with earlier versions of DevStudio.
  13.  
  14. + Obtain or build a version of winvile that supports OLE Automation.
  15.   Register same.  For further details, refer to the file oleauto.doc,
  16.   stored in the same directory as this document.  When reading oleauto.doc,
  17.   note that:
  18.  
  19.   - step 1 (building the editor) is optional if using pre-built versions
  20.     of _both_ winvile.exe and visvile.dll .
  21.  
  22.   - step 2 (configuring the editor as a server) is mandatory, and
  23.  
  24.   - step 3 (manipulating winvile via an automation client) is described
  25.     in great detail within this document :-) .
  26.  
  27.  
  28. Installation
  29. ============
  30. 1) Obtain or build visvile.dll, a Developer Studio add-in that actually
  31.    invokes winvile.  To build visvile, follow these steps:
  32.  
  33.    a) First build winvile using the syntax described in oleauto.doc .
  34.       This is an important step, since the build process creates a file
  35.       called winviletlb.h that is included by visvile.dll's sources.
  36.  
  37.    b) Use Developer Studio to open the visvile source directory as a
  38.       project.
  39.  
  40.    c) Set the "active project configuration" (see the Build Menu) as
  41.       "VisVile - Win32 Release".
  42.  
  43.    d) Press F7 (which builds visvile.dll in the Release subdirectory).
  44.  
  45. 2) Copy Release/visvile.dll to a directory location of your choice.
  46.    It may or may not be important for the destination directory to be a
  47.    member of your PATH.  On a Win95 host, it is not.
  48.  
  49. 3) On a WinNT host it may be necessary to formally register visvile.dll's
  50.    type information in the Win32 registry (on a Win95 host it is not).
  51.    Type registration is accomplished like so:
  52.  
  53.    a) login to an account with Admin rights,
  54.    b) open a dos box,
  55.    c) cd to the destination directory chosen in step 2 above,
  56.    d) execute this command:    regsvr32 visvile.dll
  57.  
  58. 4) Almost done :-) .  Invoke Developer Studio and incorporate visvile.dll
  59.    as an add-in using these steps:
  60.  
  61.    a) Invoke the add-in dialog box via these menus:
  62.  
  63.           Tools
  64.              Customize...
  65.                 Add-Ins and Macro Files
  66.  
  67.    b) Click the Browse button and point Developer Studio at visvile.dll .
  68.    c) Select visvile.dll (it will be registered as an add-in).
  69.    d) Close the Customize dialog box.
  70.  
  71. 5) You should immediately notice a new VisVile Toolbar.  Click the first
  72.    toolbar icon to configure VisVile (configuration options and toolbar
  73.    icons are discussed shortly).
  74.  
  75. That's it.  Now, every time Developer Studio is invoked, visvile.dll is
  76. automatically loaded as an add-in.
  77.  
  78.  
  79. Configuration Options
  80. =====================
  81.  
  82. Option Name       Explanation
  83. -----------       -----------
  84. Add-in enabled    VisVile causes winvile to open any new or existing _text_
  85.                   document accessed by DevStudio, provided that the default
  86.                   editor doesn't already have that document open (see next
  87.                   option).
  88.  
  89. Close DevStudio copy of text document
  90.                   VisVile closes DevStudio's copy of an open text document
  91.                   after winvile has opened its copy.  This feature keeps
  92.                   DevStudio from issuing a warning message each time a
  93.                   project file is modified by an external editor.  If
  94.                   unchecked, winvile and the DevStudio text editor co-exist
  95.                   side by side.  But see the Caveats section below.
  96.  
  97. CWD set from opened document's path
  98.                   Winvile's current working directory is set to match the
  99.                   path of any document opened by VisVile.
  100.  
  101. Write all modified buffers to disk prior to build
  102.                   VisVile forces winvile to flush all modified buffers to
  103.                   disk before a DevStudio build begins.  Note that
  104.                   DevStudio (v5, at least) decides which files must be
  105.                   compiled _prior_ to notifying VisVile of an imminent
  106.                   build.  This is arguably a DevStudio (v5) bug and it does
  107.                   diminish the usefulness of this option.
  108.  
  109.                   One workaround is to press the build accelerator key (F7)
  110.                   twice for each build.  The first key press builds
  111.                   whatever files are out-of-date before modified winvile
  112.                   buffers are written to disk.  The second key press forces
  113.                   DevStudio to re-examine its dependencies and build
  114.                   everything affected by the last winvile buffer flush.
  115.  
  116.                   Another workaround is to become accustomed to typing :ww
  117.                   within winvile prior to starting a DevStudio build.
  118.  
  119. Build log -> errbuf if build reports errs/warnings
  120.                   Assuming DevStudio has been configured to create an error
  121.                   log (refer to the Tools->Customize->Build dialog box),
  122.                   then when the current DevStudio build reports errors or
  123.                   warnings, VisVile causes winvile to use the build log as
  124.                   its error buffer.  In this configuration, the source code
  125.                   associated with each error/warning message may be
  126.                   directly accessed by simply typing ^X-^X.  For a complete
  127.                   description of ^X-^X, browse vile's help and search for
  128.                   the string "error finder".
  129.  
  130.  
  131. DevStudio Operations Affected By VisVile
  132. ========================================
  133. When VisVile is enabled, any operation that causes DevStudio to open a text
  134. file will instead/also cause winvile to open that file.  Note too that
  135. repeatedly pressing the F4 key within DevStudio following a failed build
  136. causes winvile to be positioned at the source code line(s) triggering error
  137. and/or warning messages.  However, _each_ error or warning message accessed
  138. via the F4 key requires a manual switch between winvile and DevStudio.  For
  139. that reason, the "Build log -> errbuf..." option is much more convenient
  140. (no switching required).
  141.  
  142.  
  143. Toolbar Icons
  144. =============
  145. The first icon, bound to command name "VisVileConfigCmd", configures VisVile.
  146.  
  147. The second and third icons provide shortcuts for enabling and disabling
  148. VisVile.  Note that it makes sense to disable VisVile before debugging an
  149. application (otherwise, the debugger pops up winvile whenever a breakpoint
  150. is taken).  These icons are bound to command names "VisVileEnableCmd" and
  151. "VisVileDisableCmd", respectively.
  152.  
  153. The fourth icon, bound to command name "VisVileOpenDocCmd", forces winvile
  154. to unconditionally open the text document currently visible in the default
  155. text editor.  This icon is often useful when VisVile is disabled.
  156.  
  157.  
  158. Keyboard Shortcuts
  159. ==================
  160. Use this menu hierarchy:
  161.  
  162.       Tools
  163.          Customize...
  164.             Keyboard (category Add-ins)
  165.  
  166. to assign DevStudio keyboard shortcuts to any of the command names mentioned
  167. in the previous section of this document.
  168.  
  169.  
  170. Caveats
  171. =======
  172. + DevStudio sends VisVile a "document opened" event _only_ if the affected
  173.   document is not currently open in the default editor.  Keep this fact in
  174.   mind when configuring the "Close DevStudio copy of text document" option.
  175.   This caveat does not apply to the fourth toolbar icon.
  176.  
  177. + It makes sense to disable VisVile before debugging an application
  178.   (otherwise, the debugger pops up winvile whenever a breakpoint is taken).
  179.  
  180.  
  181. Uninstalling VisVile
  182. ====================
  183. 1) Invoke Developer Studio, invoke the Add-Ins and Macro Files dialog
  184.    box, and uncheck "Winvile Developer Studio Add-In".
  185.  
  186. 2) If it was necessary to register visvile.dll's type information, open a dos
  187.    box, cd to the destination directory chosen in installation step 2 above,
  188.    and execute this command:    regsvr32 -unregister visvile.dll  .
  189.  
  190.  
  191. Copyright And Acknowledgments
  192. =============================
  193. Copyright (C) 1998 Clark Morgan
  194.  
  195. VisVile is based upon VisVim, written by Heiko Erhardt (Copyright (C) 1997
  196. Heiko Erhardt).  VisVim is based upon VisEmacs, written by Christopher
  197. Payne (Copyright (C) Christopher Payne 1997).
  198.  
  199. VisVile is free software; you can redistribute it and/or modify
  200. it under the terms of the GNU General Public License as published by
  201. the Free Software Foundation; either version 2, or (at your option)
  202. any later version.
  203.  
  204. VisVile is distributed in the hope that it will be useful,
  205. but WITHOUT ANY WARRANTY; without even the implied warranty of
  206. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  207. GNU General Public License for more details.
  208.  
  209.  
  210. Known Differences Between VisVile and VisVim
  211. ============================================
  212. Unique to VisVile:
  213. - Context-sensitive configuration dialog box.
  214. - "Write all modified buffers to disk prior to build" option.
  215. - "Build log -> errbuf if build reports errs/warnings" option.
  216. - When winvile is in insert mode, visvile forces the editor to command mode
  217.   before sending command strings.
  218.  
  219. Unique to VisVim:
  220. - "CWD set to opened document's parent directory" option
  221.