home *** CD-ROM | disk | FTP | other *** search
/ Carousel Volume 2 #1 / carousel.iso / mactosh / utilfil / stevie31.sit / stevie.doc next >
Text File  |  1988-10-11  |  10KB  |  270 lines
  1.  
  2.              STEVIE - An Aspiring VI Clone
  3.  
  4.                  User Reference
  5.  
  6.                   Tony Andrews
  7.  
  8.                  3/6/88
  9.  
  10.               Macintosh Port by
  11.             Earle Horton 10/10/88
  12.  
  13.  
  14. Overview
  15. --------
  16.  
  17. STEVIE is an editor designed to mimic the interface of the UNIX editor
  18. 'vi'. The name (ST Editor for VI Enthusiasts) is due to the fact that
  19. the editor was first written for the Atari ST. The current version has
  20. been ported to UNIX and OS/2, but I've left the name intact for now.
  21.  
  22. I've labelled STEVIE an 'aspiring' vi clone as a warning to those who
  23. may expect too much. On the whole, the editor is pretty complete. Almost
  24. all of the visual mode commands are supported. The biggest failing at the
  25. moment is that the undo command is currently in a state of disrepair.
  26. Recent enhancements in other areas have required the undo command to be
  27. mostly disabled until it can catch up with the other changes. But don't be
  28. discouraged. I've tried very hard to capture the 'feel' of vi by getting
  29. the little things right. Making lines wrap correctly, supporting true
  30. operators, and even getting the cursor to land on the right place for
  31. tabs are all a real pain, but do much to make the editor feel right.
  32.  
  33. This program is the result of many late nights of hacking over the last
  34. several months. The first version was written by Tim Thompson and posted
  35. to USENET. From there, I reworked the data structures completely, added
  36. LOTS of features, and generally improved the overall performance in the
  37. process.
  38.  
  39. STEVIE may be freely distributed. The source isn't copyrighted or
  40. restricted in any way. If you pass the program along, please include all
  41. the documentation and, if practical, the source as well. I'm not fanatical
  42. about this, but I tried to make STEVIE fairly portable and that doesn't
  43. do any good if the source isn't available.
  44.  
  45. The remainder of this document describes the operation of the editor.
  46. This is intended as a reference for users already familiar with the real
  47. vi editor.
  48.  
  49.  
  50. Starting the Editor
  51. -------------------
  52.  
  53. The following command line forms are supported:
  54.  
  55.     vi [file ...]        Edit the specified file(s)
  56.  
  57.     vi -t tag        Start at location of the given tag
  58.  
  59.     vi + file        Edit file starting at end
  60.  
  61.     vi +n file        Edit file starting a line number 'n'
  62.  
  63.     vi +/pat file        Edit file starting at pattern 'pat'
  64.  
  65. If multiple files are given on the command line (using the first form),
  66. the ":n" command goes to the next file, ":p" goes backward in the list,
  67. and ":rew" can be used to rewind back to the start of the file list.
  68.  
  69.  
  70. Set Command Options
  71. -------------------
  72.  
  73. The ":set" command works as usual to set parameters. Each parameter has
  74. a long and an abbreviated name, either of which may be used. Boolean
  75. parameters are set as in:
  76.  
  77.     set showmatch
  78.  
  79. or cleared by:
  80.  
  81.     set noshowmatch
  82.  
  83. Numeric parameters are set as in:
  84.  
  85.     set scroll=5
  86.  
  87. Several parameters may be set with a single command:
  88.  
  89.     set novb sm report=1
  90.  
  91. To see the status of all parameters use ":set all". Typing ":set" with
  92. no arguments will show only those parameters that have been changed.
  93. The supported parameters, their names, defaults, and descriptions are
  94. shown below:
  95.  
  96. Full Name    Short    Default        Description
  97. ------------------------------------------------------------------------------
  98. vbell        vb    vb        Use visual bell (novb for audible bell)
  99. showmatch    sm    nosm        Showmatch mode
  100. wrapscan    ws    ws        Wrapscan (searches cross file start/end)
  101. errorbells    eb    noeb        Ring bell when error messages are shown
  102. showmode    mo    nomo        Show on status line when in insert mode
  103. backup        bk    nobk        Leave backup in *.bak on file writes
  104. return        cr    cr        End lines with cr-lf when writing
  105. list        list    nolist        Show tabs and newlines graphically
  106.  
  107. scroll        scroll    12        Number of lines to scroll for ^D and ^U
  108. tabstop        ts    8        Number of spaces in a tab
  109. report        report    5        Min # of lines to report operations on
  110. lines        lines    25        Number of lines on the screen
  111.  
  112.  
  113. The EXINIT environment variable can be used to modify the default values
  114. on startup as in:
  115.  
  116.         setenv EXINIT="set sm ts=4"
  117.  
  118. The 'backup' parameter, if set, causes the editor to retain a backup of any
  119. files that are written. During file writes, a backup is always kept for
  120. safety until the write is completed. At that point, the 'backup' parameter
  121. determines whether the backup file is deleted.
  122.  
  123. In environments (e.g. OS/2 or TOS) where lines are normally terminated by
  124. CR-LF, the 'return' parameter allows files to be written with only a LF
  125. terminator (if the parameter is cleared).
  126.  
  127. The 'lines' parameter tells the editor how many lines there are on the screen.
  128. This is useful on systems like the ST where various screen resolutions may be
  129. used. By using the 'lines' parameter, different screen sizes can be easily
  130. handled.
  131.  
  132.  
  133. File Manipulation Commands
  134. --------------------------
  135.  
  136. The following table shows the supported file manipulation commands as
  137. well as some other 'ex' commands that aren't described elsewhere:
  138.  
  139. :w        write the current file
  140. :wq        write and quit
  141. :x        write (if necessary) and quit
  142. ZZ        same as ":x"
  143.  
  144. :e file        edit the named file
  145. :e!        re-edit the current file, discarding any changes
  146. :e #        edit the alternate file
  147.  
  148. :w file        write the buffer to the named file
  149. :x,y w file    write lines x through y to the named file
  150. :r file        read the named file into the buffer
  151.  
  152. :n        edit the next file
  153. :p        edit the previous file
  154. :rew        rewind the file list
  155.  
  156. :f        show the current file name
  157. :f name        change the current file name
  158.  
  159. :ta tag        go to the named tag
  160. ^]        like ":ta" using the current word as the tag
  161.  
  162. :help        display a command summary
  163.  
  164. The ":help" command can also be invoke with the <HELP> key on the Atari
  165. ST. This actually displays a pretty complete summary of the real vi with
  166. unsupported features indicated appropriately.
  167.  
  168. The commands above work pretty much like they do in 'vi'. Most of the
  169. commands support a '!' suffix (if appropriate) to discard any pending
  170. changes.
  171.  
  172. When writing just part of the buffer, the following address forms are
  173. supported:
  174.  
  175.         addr [+- number]
  176.  
  177. where 'addr' may be one of the following:
  178.  
  179.         a line number
  180.         a mark (as in 'a or 'b)
  181.         '.' (the current line)
  182.         '$' (the last line)
  183.  
  184.  
  185. String Searches
  186. ---------------
  187.  
  188. String searches are supported, as in vi, accepting the usual regular
  189. expression syntax. This was done using Henry Spencer's regular expression
  190. library without modification. I added code outside the library to support
  191. the '\<' and '\>' extensions. This actually turned out to be pretty easy.
  192.  
  193.  
  194. Operators
  195. ---------
  196.  
  197. The vi operators (d, c, y, <, and >) work as true operators. The only
  198. exception is that the change operator works only for character-oriented
  199. changes (like cw or c%) and not for line-oriented changes (like cL or c3j).
  200.  
  201.  
  202. Tags
  203. ----
  204.  
  205. Tags are implemented and a fairly simple version of 'ctags' is supplied
  206. with the editor. The current version of ctags will find functions and
  207. macros following a specific (but common) form.  See 'ctags.doc' for a
  208. complete discussion.  [The full Ctags program is in the public domain;
  209. contact your nearest comp.sources.unix archive site; the primitive
  210. tags has been taken out of this c.s.u distribution.]
  211.  
  212.  
  213. System-Specific Comments
  214. ------------------------
  215.  
  216. The following sections provide additional relevant information for the
  217. systems to which STEVIE has been ported.
  218.  
  219.  
  220. Atari ST
  221. --------
  222.  
  223. The editor has been tested in all three resolutions, although low and
  224. high res. are less tested than medium. The 50-line high res. mode can
  225. be used by setting the 'l
  226.  
  227. Note:  It looks like the shar file I got the original copy from is
  228. missing a line or two here.  Sorry.  Earle
  229.  
  230. Macintosh  This section by Earle Horton
  231. ---------
  232.  
  233. The Macintosh version was ported by me and compiled using Aztec C v 3.6c.
  234. I made very few changes to the original code, but did provide a terminal
  235. emulator for the program to run in on the Mac, and also a faster malloc()
  236. than supplied with Aztec C.  The EXINIT environment variable mentioned
  237. above is mimiced by the 'STR ' resource named "EXINIT."  I have added a
  238. "columns" parameter to control the width of the terminal emulator window.
  239. You can take over most of the screen on a Mac II with the Apple color
  240. monitor by putting "set lines=36 columns=105" in the "EXINIT" resource
  241. using ResEdit, or by typing it on the command line.
  242.  
  243. The only major shortcomings in the Mac version of Stevie are the inability
  244. to change the current working directory, and my failure to use Standard
  245. File dialogs to access files.  But when did the real vi have these 
  246. features?  I realize that this behavior violates Apple User Interface
  247. Guidelines, but if I were to add Standard File dialogs, then it would
  248. loose the vi "Look and Feel," now wouldn't it?
  249.  
  250. So that no one will be inconvenienced by these un-Mac-ish items, allow
  251. me to describe how Stevie is used with HFS disks.  One launches Stevie
  252. by clicking on its icon or on a document icon.  The default folder for
  253. all file access is set to the folder Stevie is in, or to the folder
  254. containing THE LAST FILE IN THE FINDER PARAMETER LIST.  This is the
  255. last file passed to Stevie by the Finder.  Since there is no way to
  256. control which file this will be, it is unwise to launch Stevie from
  257. MPW Shell with a list of files in different folders.  Sorry.  All files
  258. which are not in the default folder thus defined must be accessed by
  259. pathname.  Either absolute pathnames or relative pathnames may be used.
  260. If relative pathnames are used, they must be defined with reference
  261. to the default Stevie folder.
  262.  
  263. One final note.  Stevie understands Macintosh extended character set
  264. characters, and can handle long lines, but it dislikes nul characters
  265. and breaks lines longer than 1023 characters.  For this reason it should
  266. not be used to edit binary files, although it may be used to view such
  267. files with impunity. I realize that this is unlike the behavior of the
  268. "real" vi, but one has to make concessions occasionally.
  269.  
  270.