windows-server-2003/sdktools/vi

The following is a concatenation of the relevent parts of the readme files

that came with the sources.



NOTE:   this is an incomplete VI that has not been fully tested.  Use at your

        own risk.



SEE VERSION.C FOR THE CURRENT STATUS OF THIS PROGRAM



         ======================================================



STEVIE Source Release - 3.68



This is a source release of the STEVIE editor, a public domain clone

of the UNIX editor 'vi'. The program was originally developed for the

Atari ST, but has been ported to UNIX, OS/2, DOS, and Minix-ST as well.

Ports done by others, but not directly supported by this release, include

Minix-PC, Amiga, and a Data General system of some sort.



The good news about stevie is that it is extremely portable. It supports

systems with virtually all combinations of integer size, pointer size,

and byte order. The only major issue remaining, for some environments,

is that the file is kept in memory. For most environments, this isn't a

problem, but for Minix-PC it is particularly annoying.



        =======================================================





                      STEVIE - An Aspiring VI Clone



                          User Reference - 3.69



                               Tony Andrews



                            NT port by tedm



       1.  Overview



       STEVIE is an editor designed to mimic the interface  of  the

       UNIX  editor  'vi'.  The name (ST Editor for VI Enthusiasts)

       comes from the fact that the editor was  first  written  for

       the  Atari ST. The current version also supports UNIX, Minix

       (ST), MS-DOS, and OS/2, but I've left the  name  intact  for

       now.



       This program is the result of many late  nights  of  hacking

       over  the last couple of years.  The first version was writ-

       ten by Tim Thompson and posted  to  USENET.  From  there,  I

       reworked  the  data  structures  completely,  added  LOTS of

       features, and generally improved the overall performance  in

       the process.



       I've labelled STEVIE an 'aspiring' vi clone as a warning  to

       those  who  may expect too much. On the whole, the editor is

       pretty complete.  Nearly all of the visual mode commands are

       supported.   And several of the more important 'ex' commands

       are supported as well.  I've tried hard to capture the  feel

       of vi by getting the little things right.  Making lines wrap

       correctly, supporting true operators, and even  getting  the

       cursor  to  land on the right place for tabs are all a pain,

       but really help make the editor feel right.  I've  tried  to

       resist  the  temptation  to deviate from the behavior of vi,

       even where I disagree with the original design.



       The biggest problem remaining has to do with the  fact  that

       the  edit  buffer is maintained entirely in memory, limiting

       the size of files that can be edited in  some  environments.

       Other  missing  features  include  named buffers and macros.

       Performance is generally  reasonable,  although  the  screen

       update code could be more efficient.  This is generally only

       visible on fairly slow systems.



       STEVIE may be freely distributed.  The  source  isn't  copy-

       righted  or  restricted  in any way. If you pass the program

       along, please include all the documentation and, if  practi-

       cal, the source as well. I'm not fanatical about this, but I

       tried to make STEVIE fairly portable and I'd like to see  as

       many people have access to the source as possible.



       The remainder of this document describes  the  operation  of

       the  editor.   This  is  intended  as  a reference for users

       already familiar with the real vi editor.









                                  - 1 -















       STEVIE                                        User Reference







       2.  Starting_the_Editor



       The following command line forms are supported:



       stevie [file ...]   Edit the specified file(s)



       stevie -t tag       Start at the location of the given tag



       stevie + file       Edit file starting at end



       stevie +n file      Edit file starting a line number 'n'



       stevie +/pat file   Edit file starting at pattern 'pat'



       If multiple files are given on the command line  (using  the

       first  form),  the  ":n" command goes to the next file, ":N"

       goes backward in the list, and ":rew" can be used to  rewind

       back to the start of the file list.





       3.  Set_Command_Options



       The ":set" command works as usual to  set  parameters.  Each

       parameter  has  a  long  and  an abbreviated name, either of

       which may be used. Boolean parameters are set as in:



            set showmatch



       or cleared by:



            set noshowmatch



       Numeric parameters are set as in:



            set scroll=5



       Several parameters may be set with a single command:



            set novb sm report=1



       To see the status of all parameters use ":set  all".  Typing

       ":set"  with  no  arguments  will show only those parameters

       that have been changed.   The  supported  parameters,  their

       names,  abbreviations,  defaults, and descriptions are shown

       below:



       autoindent  Short: ai, Default: noai, Type: Boolean

                   When in insert mode, start new lines at the same

                   column  as  the  prior  line. Unlike vi, you can

                   backspace over the indentation.









                                  - 2 -















       STEVIE                                        User Reference







       backup      Short: bk, Default: nobk, Type: Boolean

                   Leave a backup on file writes.



       errorbells  Short: eb, Default: noeb, Type: Boolean

                   Ring bell when error messages are shown.



       ignorecase  Short: ic, Default: noic, Type: Boolean

                   Ignore case in string searches.



       lines       Short: lines, Default: lines=25, Type: Numeric

                   Number of physical  lines  on  the  screen.  The

                   default  value  actually  depends  on  the  host

                   machine, but is generally 25.



       list        Short: list, Default: nolist, Type: Boolean

                   Show tabs and newlines graphically.



       modelines   Short: ml, Default: noml, Type: Boolean

                   Enable processing of modelines in files.



       number      Short: nu, Default: nonu, Type: Boolean

                   Display lines on  the  screen  with  their  line

                   numbers.



       report      Short: report, Default: report=5, Type: Numeric

                   Minimum number of lines to report operations on.



       return      Short: cr, Default: cr, Type: Boolean

                   End lines with cr-lf when writing files.



       scroll      Short: scroll, Default: scroll=12, Type: Numeric

                   Number of lines to scroll for ^D & ^U.



       showmatch   Short: sm, Default: nosm, Type: Boolean

                   When a ), }, or ] is typed, show the matching (,

                   {,  or [ if it's on the current screen by moving

                   the cursor there briefly.



       showmode    Short: mo, Default: nomo, Type: Boolean

                   Show on status line when in insert mode.



       tabstop     Short: ts, Default: ts=8, Type: Numeric

                   Number of spaces in a tab.



       terse       Short: terse, Default: noterse, Type: Boolean

                   This option is currently ignored.   It  is  pro-

                   vided only for compatibility with vi.



       tildeop     Short: to, Default: noto, Type: Boolean

                   If set, tilde is an operator.  Otherwise,  tilde

                   acts as normal.







                                  - 3 -















       STEVIE                                        User Reference







       wrapscan    Short: ws, Default: ws, Type: Boolean

                   String searches wrap  around  the  ends  of  the

                   file.



       vbell       Short: vb, Default: vb, Type: Boolean

                   Use a visual bell, if possible. (novb for  audi-

                   ble bell)



       The EXINIT environment variable can be used  to  modify  the

       default values on startup as in:



            setenv EXINIT="set sm ts=4"



       The 'backup' parameter, if set, causes the editor to  retain

       a  backup of any files that are written. During file writes,

       a backup is always kept for safety until the write  is  com-

       pleted.  At  that  point,  the 'backup' parameter determines

       whether the backup file is deleted.



       In environments (e.g. OS/2 or TOS) where lines are  normally

       terminated  by CR-LF, the 'return' parameter allows files to

       be written with only a LF terminator (if  the  parameter  is

       cleared).  This parameter is ignored on UNIX systems.



       The 'lines' parameter tells the editor how many lines  there

       are  on  the  screen.  This is useful on systems like the ST

       (or OS/2 machines with an EGA adapter) where various  screen

       resolutions  may  be  used.  By using the 'lines' parameter,

       different screen sizes can be easily handled.





       4.  Colon_Commands



       Several of the normal 'vi' colon commands are  supported  by

       STEVIE.   Some  commands  may  be  preceded  by a line range

       specification.  For commands that accept a range  of  lines,

       the following address forms are supported:



            addr

            addr + number

            addr - number



       where 'addr' may be one of the following:



            a line number

            a mark (as in 'a or 'b)

            '.' (the current line)

            '$' (the last line)



       An address range of "%" is accepted as  an  abbreviation  of

       "1,$".







                                  - 4 -















       STEVIE                                        User Reference







       4.1  Mode_Lines



       Mode lines are a little-known, but often useful, feature  of

       vi.   To use this feature, special strings are placed in the

       first or last five lines  in  a  file.   When  the  file  is

       edited,  these  strings are detected and processed as though

       typed as a colon command.  One instance where  this  can  be

       useful  is  to  set  the  "tabstop"  parameter on a per-file

       basis.  The following are examples of mode lines:



            vi:set ts=4 noai:

            ex:45:



       Mode lines are characterized by the string "vi" or "ex" fol-

       lowed  by  a  command  surrounded  by colons. Other text may

       appear on the line, and multiple mode lines may be  present.

       No  guarantee  is made regarding the order in which multiple

       mode lines will be processed.



       The processing of mode lines is enabled by setting the  "ml"

       parameter.  This  should be done in the "EXINIT" environment

       variable, so that mode line processing is enabled as soon as

       the  editor begins.  By default, mode lines are disabled for

       security reasons.



       4.2  The_Global_Command



       A limited form of the global command is supported, accepting

       the following command form:



            g/pattern/X



       where X may be either 'd' or 'p' to delete  or  print  lines

       that  match  the  given  pattern.  If a line range is given,

       only those lines are checked for a match with  the  pattern.

       If no range is given, all lines are checked.



       If  the  trailing  command  character  is  omitted,  'p'  is

       assumed.  In this case, the trailing slash is also optional.

       The current version of the editor does not support the  undo

       operation  following  the  deletion of lines with the global

       command.



       4.3  The_Substitute_Command



       The substitute command provides  a  powerful  mechanism  for

       making  more complex substitutions than can be done directly

       from visual mode.  The general form of the command is:



            s/pattern/replacement/g









                                  - 5 -















       STEVIE                                        User Reference







       Each line in the given range (or the  current  line,  if  no

       range  was  given)  is scanned for the given regular expres-

       sion.  When found, the string that matched  the  pattern  is

       replaced with the given replacement string.  If the replace-

       ment  string  is  null,  each  matching  pattern  string  is

       deleted.



       The trailing 'g' is optional and, if present, indicates that

       multiple  occurrences  of  'pattern' on a line should all be

       replaced.



       Some special sequences are  recognized  in  the  replacement

       string.  The  ampersand  character is replaced by the entire

       pattern that was matched.  For example, the  following  com-

       mand  could be used to put all occurrences of 'foo' or 'bar'

       within double quotes:



            1,$s/foo|bar/"&"/g



       The special sequence "\n" where 'n' is a digit from 1 to  9,

       is  replaced  by  the  string  the matched the corresponding

       parenthesized expression in the pattern. The following  com-

       mand could be used to swap the first two parameters in calls

       to the C function "foo":



            1,$s/foo\(([^,]*),([^,]*),/foo(\2,\1,/g



       Like the global command, substitutions can't be undone  with

       this version of the editor.



       4.4  File_Manipulation_Commands



       The following table shows the  supported  file  manipulation

       commands  as  well  as  some other 'ex' commands that aren't

       described elsewhere:







































                                  - 6 -















       STEVIE                                        User Reference







       :w              write the current file

       :wq             write and quit

       :x              write (if necessary) and quit

       ZZ              same as ":x"



       :e file         edit the named file

       :e!             re-edit the current file, discarding changes

       :e #            edit the alternate file



       :w file         write the buffer to the named file

       :x,yw file      write lines x through y to the named file

       :r file         read the named file into the buffer



       :n              edit the next file

       :N              edit the previous file

       :rew            rewind the file list



       :f              show the current file name

       :f name         change the current file name

       :x=             show the line number of address 'x'



       :ta tag         go to the named tag

       ^]              like ":ta" using the current word as the tag



       :help           display a command summary

       :ve             show the version number



       :sh             run an interactive shell

       :!cmd           run a command



       The ":help" command can also be invoked with the <HELP>  key

       on  the  Atari  ST. This actually displays a pretty complete

       summary of the real vi with unsupported  features  indicated

       appropriately.



       The commands above work pretty much like they  do  in  'vi'.

       Most  of  the commands support a '!' suffix (if appropriate)

       to discard any pending changes.





       5.  String_Searches



       String searches are supported, as in vi, accepting the usual

       regular  expression  syntax.  This was done using a modified

       form of Henry Spencer's regular expression library. I  added

       code outside the library to support the '\<' and '\>' exten-

       sions.  The parameter "ignorecase" can be set to ignore case

       in all string searches.













                                  - 7 -















       STEVIE                                        User Reference







       6.  Operators



       The vi operators (d, c, y, !, <, and >) work as true  opera-

       tors.   The tilde command may also be used as an operator if

       the parameter "tildeop"  has  been  set.  By  default,  this

       parameter is not set.





       7.  Tags



       Tags are implemented and a fairly simple version of  'ctags'

       is  supplied  with  the editor. The current version of ctags

       will find functions and macros  following  a  specific  (but

       common) form.  See 'ctags.doc' for a complete discussion.





       8.  System-Specific_Comments



       The following sections provide additional relevant  informa-

       tion for the systems to which STEVIE has been ported.



       8.1  Atari_ST



       8.1.1  TOS  The editor has been tested in all three  resolu-

       tions,  although  low  and  high  res.  are less tested than

       medium. The 50-line high res. mode can be  used  by  setting

       the  'lines' parameter to 50. Alternatively, the environment

       variable 'LINES' can be set. The editor doesn't actively set

       the  number  of  lines on the screen. It just operates using

       the number of lines it was told.



       The arrow keys, as well as the <INSERT>, <HELP>, and  <UNDO>

       keys are all mapped appropriately.



       8.1.2  Minix  The editor  is  pretty  much  the  same  under

       Minix,  but  many  of  the keyboard mappings aren't yet sup-

       ported.



       8.2  UNIX



       The editor has been ported to UNIX System  V  release  3  as

       well as 4.2 BSD.  This was done mainly to get some profiling

       data so I haven't put much effort into doing the  UNIX  ver-

       sion  right.   While the termcap routines are supported, the

       editor is still fairly picky about the capabilities it wants

       and makes little effort to do clever things with less intel-

       ligent terminals.















                                  - 8 -















       STEVIE                                        User Reference







       8.3  OS/2



       This port was done because the editor that  comes  with  the

       OS/2 developer's kit really stinks. Make sure 'ansi' mode is

       on (using the 'ansi'  command).   The  OS/2  console  driver

       doesn't  support  insert/delete line, so STEVIE bypasses the

       driver and makes  the  appropriate  system  calls  directly.

       This  is  all done in the system-specific part of the editor

       so the kludge is at least localized.



       The arrow keys, page up/down and home/end all do what  you'd

       expect. The function keys are hard-coded to some useful mac-

       ros until I can get true support for macros into the editor.

       The current mappings are:



            F1      :N <RETURN>

            F2      :n <RETURN>

            F3      :e # <RETURN>

            F4      :rew <RETURN>

            F5      [[

            F6      ]]

            F7      Convert C declaration to pseudo-english (uses cdecl)

            F8      Convert english-style declaration to C (uses cdecl)

            F9      :x <RETURN>

            F10     :help <RETURN>



            S-F1    :N! <RETURN>

            S-F2    :n! <RETURN>



       The macros for F7 and F8 assume that the "cdecl" program  is

       available.



       8.4  MSDOS



       STEVIE has been ported to MSDOS 3.3 using  the  Microsoft  C

       compiler,  version  5.1.  The keyboard mappings are the same

       as for OS/2.  The only problem with the PC version  is  that

       the inefficiency of the screen update code becomes painfully

       apparent on slower machines.



       The DOS version requires the  use  of  an  extended  console

       driver  that  can  insert and delete lines.  The distributed

       code uses "nansi.sys" which seems to be widely available.





       9.  Missing_Features



         1.  The ability to edit files larger  than  the  available

             memory.   This  isn't a problem on the machines I use,

             but it hits the Minix-PC people pretty hard.









                                  - 9 -















       STEVIE                                        User Reference







         2.  Macros with support for function keys.



         3.  More "set" options.



         4.  Many others...





       10.  Known_Bugs_and_Problems



         1.  The yank buffer uses statically allocated  memory,  so

             large  yanks  will  fail.  If  a  delete spans an area

             larger than the yank buffer, the program asks for con-

             firmation  before  proceeding.  That  way, if you were

             moving text, you don't get screwed by the limited yank

             buffer.  You  just  have  to  move smaller chunks at a

             time. All the  internal  buffers  (yank,  redo,  etc.)

             need  to  be  reworked to allocate memory dynamically.

             The 'undo' buffer is now dynamically allocated, so any

             change can be undone.



         2.  If you stay in insert mode for a long time, the insert

             buffer  can overflow.  The editor will print a message

             and dump you back into command mode.



         3.  The current version of the substitute and global  com-

             mands  (i.e.  ":s/foo/bar"  or  ":g/foo/d")  can't  be

             undone.  This is due to the current design of the undo

             code.   To undo these commands would generally involve

             unreasonable amounts of memory.



         4.  Several other less bothersome glitches...















































                                  - 10 -















       STEVIE                                        User Reference







       11.  Conclusion



       The editor has reached a pretty stable state,  and  performs

       well  on  the  systems  I  use  it on, so I'm pretty much in

       maintenance mode now.  There's still plenty to be done;  the

       screen  update  code  is  still  pretty  inefficient and the

       yank/put code is still primitive.  I'm still  interested  in

       bug  reports,  and I do still add a new feature from time to

       time, but the rate of change is way down now.



       I'd like to thank Tim Thompson for writing the original ver-

       sion  of  the  editor.  His  program was well structured and

       quite readable. Thanks for giving me a  good  base  to  work

       with.   Thanks also to many users of STEVIE who have sent in

       their changes.  Many of the  changes  I've  received  aren't

       portable  to  all  the systems I support, but I'm working to

       get portable  implementations  integrated  into  the  editor

       where possible.



       If you're reading this file, but didn't get the source  code

       for STEVIE, it can be had by sending a disk with return pos-

       tage to the address given below. I can write disks  for  the

       Atari  ST (SS or DS) or MSDOS (360K or 1.2M). Please be sure

       to include the return postage. I don't intend to make  money

       from this program, but I don't want to lose any either.



            Tony Andrews            UUCP: onecom!wldrdg!tony

            5902E Gunbarrel Ave.

            Boulder, CO 80301



















































                                  - 11 -















       STEVIE                                        User Reference







       Character_Function_Summary



       The following list describes the meaning of  each  character

       that's  used  by  the  editor. In some cases characters have

       meaning in both command  and  insert  mode;  these  are  all

       described.





       ^@      The null character. Not used in any mode. This char-

               acter may not be present in the file, as is the case

               with vi.



       ^B      Backward one screen.



       ^D      Scroll the window down one half screen.



       ^E      Scroll the screen up one line.



       ^F      Forward one screen.



       ^G      Same as ":f" command. Displays file information.



       ^H      (Backspace) Moves cursor left one space  in  command

               mode.   In  insert  mode,  erases the last character

               typed.



       ^J      Move the cursor down one line.



       ^L      Clear and redraw the screen.



       ^M      (Carriage return) Move to the first non-white  char-

               acter  in  the next line. In insert mode, a carriage

               return opens a new line for input.



       ^N      Move the cursor down a line.



       ^P      Move the cursor up a line.



       ^U      Scroll the window up one half screen.



       ^Y      Scroll the screen down one line.



       ^[      Escape cancels a pending command  in  command  mode,

               and is used to terminate insert mode.



       ^]      Moves to the tag whose name is given by the word  in

               which the cursor resides.



       ^`      Same as ":e #" if supported (system-dependent).











                                  - 12 -















       STEVIE                                        User Reference







       SPACE   Move the cursor right on column.



       !       The filter operator always operates on  a  range  of

               lines,  passing the lines as input to a program, and

               replacing them with the output of the  program.  The

               shorthand  command  "!!"  can  be  used  to filter a

               number of lines (specified by  a  preceding  count).

               The  command  "!"  is  replaced  by the last command

               used, so "!!!<RETURN>"  runs  the  given  number  of

               lines through the last specified command.



       $       Move to the end of the current line.



       %       If the cursor rests on a paren '()', brace '{}',  or

               bracket '[]', move to the matching one.



       '       Used to move the cursor to a previously marked posi-

               tion,  as in 'a or 'b. The cursor moves to the start

               of the marked line. The special mark  ''  refers  to

               the "previous context".



       +       Same as carriage return, in command mode.



       ,       Reverse of the last t, T, f, or F command.



       -       Move to the first non-white character in the  previ-

               ous line.



       .       Repeat the last edit command.



       /       Start of a forward  string  search  command.  String

               searches may be optionally terminated with a closing

               slash. To search for a slash use '\/' in the  search

               string.



       0       Move to the start of the  current  line.  Also  used

               within counts.



       1-9     Used to add 'count' prefixes to commands.



       :       Prefix character for "ex" commands.



       ;       Repeat last t, T, f, or F command.



       <       The 'left shift' operator.



       >       The 'right shift' operator.



       ?       Same as '/', but search backward.











                                  - 13 -















       STEVIE                                        User Reference







       A       Append at the end of the current line.



       B       Backward one blank-delimited word.



       C       Change the rest of the current line.



       D       Delete the rest of the current line.



       E       End of the end of a blank-delimited word.



       F       Find a character backward on the current line.



       G       Go to  the  given  line  number  (end  of  file,  by

               default).



       H       Move to the first non-white char. on the top  screen

               line.



       I       Insert before  the  first  non-white  char.  on  the

               current line.



       J       Join two lines.



       L       Move to the first  non-white  char.  on  the  bottom

               screen line.



       M       Move to the first  non-white  char.  on  the  middle

               screen line.



       N       Reverse the last string search.



       O       Open a new line above the current  line,  and  start

               inserting.



       P       Put the yank/delete buffer before the current cursor

               position.



       R       Replace characters until an  "escape"  character  is

               received.   Similar  to  insert  mode,  but replaces

               instead of inserting.  Typing a newline  in  replace

               mode  is  the  same as in insert mode, but replacing

               continues on the new line.



       T       Reverse search 'upto' the given character.



       U       Restore the current line to  its  state  before  you

               started changing it.



       W       Move forward one blank-delimited word.











                                  - 14 -















       STEVIE                                        User Reference







       X       Delete one character before the cursor.



       Y       Yank the current line. Same as 'yy'.



       ZZ      Exit from the editor, saving changes if necessary.



       [[      Move backward one C function.



       ]]      Move forward one C function.



       ^       Move to the first non-white on the current line.



       `       Move to the given mark, as with '.  The  distinction

               between the two commands is important when used with

               operators. I support the  difference  correctly.  If

               you  don't know what I'm talking about, don't worry,

               it won't matter to you.



       a       Append text after the cursor.



       b       Back one word.



       c       The change operator.



       d       The delete operator.



       e       Move to the end of a word.



       f       Find a character on the current line.



       h       Move left one column.



       i       Insert text before the cursor.



       j       Move down one line.



       k       Move up one line.



       l       Move right one column.



       m       Set a mark at the current position (e.g. ma or mb).



       n       Repeat the last string search.



       o       Open a new line and start inserting text.



       p       Put the yank/delete buffer after the cursor.



       r       Replace a character.











                                  - 15 -















       STEVIE                                        User Reference







       s       Replace characters.



       t       Move forward  'upto'  the  given  character  on  the

               current line.



       u       Undo the last edit.



       w       Move forward one word.



       x       Delete the character under the cursor.



       y       The yank operator.



       z       Redraw the screen with the current line at  the  top

               (zRETURN), the middle (z.), or the bottom (z-).



       |       Move to the column given by the preceding count.



       ~       Invert the case of the current character (if  alpha)

               and  move  to the right.  If the parameter "tildeop"

               is set, this command functions as an operator.



































































                                  - 16 -























                           STEVIE - User Guide



                                 CONTENTS





        1.  Overview...........................................   1



        2.  Starting the Editor................................   2



        3.  Set Command Options................................   2



        4.  Colon Commands.....................................   4

            4.1  Mode Lines....................................   5

            4.2  The Global Command............................   5

            4.3  The Substitute Command........................   5

            4.4  File Manipulation Commands....................   6



        5.  String Searches....................................   7



        6.  Operators..........................................   8



        7.  Tags...............................................   8



        8.  System-Specific Comments...........................   8

            8.1  Atari ST......................................   8

            8.2  UNIX..........................................   8

            8.3  OS/2..........................................   9

            8.4  MSDOS.........................................   9



        9.  Missing Features...................................   9



       10.  Known Bugs and Problems............................  10



       11.  Conclusion.........................................  11



       Character Function Summary..............................  12





































                                  - i -