Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume4/vms-vi-2/part04

Internet Message Format | 1989-02-03 | 25.7 KB

Path: xanth!mcnc!gatech!bloom-beacon!bu-cs!mirror!necntc!ncoast!allbery
From: [e-mail] (Gregg Wonderly)
Newsgroups: comp.sources.misc
Subject: v04i095: TPUVI for VMS part 4 of 17
Message-ID: <[e-mail]>
Date: 26 Sep 88 01:49:13 GMT
Sender: [e-mail]
Reply-To: [e-mail] (Gregg Wonderly)
Lines: 701
Approved: [e-mail]

Posting-number: Volume 4, Issue 95
Submitted-by: "Gregg Wonderly" <[e-mail]>
Archive-name: vms-vi-2/Part04

$ show default
$ if f$search("DOC.DIR;1") .eqs. "" then -
     CREATE/LOG/DIRECTORY [.DOC]
$ write sys$output "Creating [.DOC]TUTOR.RNO"
$ create [.DOC]TUTOR.RNO
$ DECK/DOLLARS="*$*$*EOD*$*$*"
.! TUTOR.RNO - Learning to use VI
.! Written by Gregg Wonderly 12-NOV-1987
.!
.! RUNOFF operation instructions:
.!
.!     $ @VIDOC.COM TUTOR
.!
.!   to create a document for printing.
.!
.! We set the layout so that running page numbers are on the bottom
.!
.lo 1,2
.st
.!
.! Initial right margin - sections should never set it higher than this.
.! Set page size too.
.ps 57,70 .rm 65
.!
.! Header level setup
.sthl 6,0,0,8,9,1,1,9,2
.dhl D,D,lu,d,ll,ll
.!
.!
.flags bold
.flags overstrike
.!
.c;
.sk 2
.c;Learning to use VI written in TPU
.title Learning to use VI written in TPU
.sk 2
.c;Gregg Wonderly
.c;Mathematics Department
.c;Oklahoma State University
.sk 1
.c;12-NOV-1987
.!
.send toc .ifnot global
.hl 1 ^*Introduction\*
.X introduction
.send toc .endif global
.s
Editing text consists of only a few basic operations.  These operations can be
summarized by generalizations to be just insertions and deletions.  Most text
editors provide text insertion capabilities by allowing the user to just type.
.X deletion
.X insertion
Text deletions are then accomplished by the use of certain non-typing keystrokes
which are not allowed to insert text into the document being edited. These types
of editors are typically called modeless editors, because they apparently have
no special mode to distinguish between inserting and deleting text (just
different keystrokes).
.s
VI is not one of these types of editors.  VI is a moded editor, as it has
a specific mode for inserting text, and another mode (which makes use of
the normal typing keys) which allows deleting text.  Like anything different,
it can take some time to get used to this type of editing.  There are some
real benefits to be gained from it.  Some are quite significant, an others
while perhaps not terribly important, are deeply rooted in the progression
of computers and terminals.
.PAGE
.REQ 'TUTOR.RNT'
.PAGE
.P
There has never really been a standard terminal with a standard layout of
keys (other than the QWERTY keyboard).  This presents a real problem when
you have several different types of terminals that you use.  VI attempts
to solve the problem of dealing with different keyboards by making it
unnecessary to use anything but the QWERTY keyboard.
.s
This is advantageous when a particular site has different types of terminals.
This was the case at the University of California at Berkeley when Bill Joy
first wrote VI.  Bill was presented with the task of writing a full screen
editor that would be usable on all of the terminals that had been given to the
Computer Science folks there.  Out of this came two things, VI, and more
importantly, curses which allows terminal independent access to windowing
capabilities.  Quite an accomplishment Bill!
.s
Now that there is apparently a move towards standardizing the DEC VT-200 series
keyboards, and the ANSI 3.64 escape sequences, the idea of not using anything
but the QWERTY keyboard may diminish.  But, there will always be the argument
that the QWERTY keyboard is closer to your finger tips than the keypad is.
.!
.send toc .ifnot global
.hl 1 ^*Learning the power of VI\*
.send toc .endif global
.s
With that out of the way, lets move on to learning VI.  There are two modes of
operation that the VI editor can be in.  It is either in command mode, or in
insert mode.  When you first enter the editor, it is in command mode. One of the
.X escape
very first things to learn about VI is, when you are not sure, bang on the
escape key a few times until you hear a beep.  The escape key is used to change
modes from text insert mode to editing command mode, so banging on it a few
times will always get you to command mode, when you are in insert mode.
.s
VI allows you to perform many tasks with very few keystrokes.  This is good for
those who get tired of typing lots of keystrokes to perform editing operations.
This can be bad for those who make lots of typing mistakes. I say "can be bad"
.X undo
because VI allows you to recover from typing mistakes by undoing operations that
insert/delete text into/from a document.  Operations that alter a document are
explicit in VI.  There is a definite starting point, and a definite ending
point.  This is what allows VI to "know" how to undo what you last did. As long
as you only make one mistake at a time, you can undo that mistake by typing a
'u' (for undo) keystroke while in command mode.  This is perhaps the most
appreciated feature of VI.  There is another key stroke, 'U', which also allows
you to undo mistakes.  It will undo all changes made to the current line,
providing the cursor has not left that line since the changes were made.
.!
.send toc .ifnot global
.hl 2 ^*Inserting Text\*
.send toc .endif global
.s
VI incorporates several methods of inserting text into a document.
There are three different methods you can use while you are in command mode.
Typing an 'i' (for insert) keystroke allows you to insert characters
into the document at the point that the cursor is positioned.  As
mentioned above, typing the <ESC> (or escape) keystroke allows you to
exit (or escape) from insert mode.  Due to the many different places
that a person may want to insert text at, there are keystrokes other
than 'i', that place the editor directly into insert mode, after
moving the cursor.  These are outlined below.
.s
^&Insert commands\&
.lm+5
.LT
'i'         Allows you to insert at the current cursor
            position.
.EL
.S
.LT
'I'         Allows you to begin inserting at the beginning
            of the line, no matter where the cursor is
            positioned on the current line.

.EL
.lm-5
^&Open commands\&
.lm+5
.LT
'o'         Allows you to begin inserting on a new, empty
            line that is opened for you, below the current
            line.
.EL
.S
.LT
'O'         Allows you to begin inserting on a new, empty
            line that is opened for you, above the current
            line.

.EL
.lm-5
^&Append commands\&
.lm+5
.LT
'a'         Allows you to begin inserting after the
            character (append) that the cursor is
            positioned on.
.EL
.S
.LT
'A'         Allows you to begin inserting at the end of the
            current line, no matter where the cursor is
            positioned on that line.
.EL
.lm-5
.s
There are other commands that place you in insert mode.  These commands are
used to perform substitutions of text.  That is, the deletion of old text
and the insertion of new text, all in a single operation.  These commands
will be discussed further on because the are actually macros of the
change command.
.!
.send toc .ifnot global
.hl 2 ^*Deleting Copying and Changing\*
.send toc .endif global
.s
The next three operations we will discuss will be deleting, copying, and
changing.  These three will be discussed together because the methods of
describing the text that these commands operate on is identical.
.s
There are well over 30 different ways that you can tell VI to move the
cursor to a new location in the document.  These movements can also be
used to describe sections of the document that you wish to perform operations
on.  Typically, you will type a single keystroke which describes the
type of operation you wish to perform, e.g. 'd' to delete.  There are several
commands that allow you to use a normal movement command to describe a portion
of the document you are editing.  These commands are outlined below.
.s
.lm+5
.LT
'd'         Delete text.
'y'         Copy text (that is, yank it into a holding
            area for later use).
'c'         Change text from one thing to another, which
            you will type.
'!'         Filter text through a program.
'<'         Shift a region of text to the left.
'>'         Shift a region of text to the right.
.EL
.lm-5
.s
.c;Figure 1.
.s
The first three are the basic text operations that allow you to alter a
document by deleting, copying and changing the text in it.  The last three are
more advanced operations that are useful and handy to have.
.!
.send toc .ifnot global
.hl 1 ^*Single Key Movements\*
.send toc .endif global
.s
Following one of the commands identifying keystrokes listed in Figure 1, you
must tell VI what portion of the document to perform the operation on.
This is done by typing a keystroke that indicates a movement command.
Most of these are outlined below.  The more complicated movements will be
described later on.  Each character is surrounded by single quotes.
.s
.lm+5
.LT
'`'         Move the cursor to a previously marked location
            in the document.
.EL
.S
.LT
'$'         Move the cursor to the end of the current line,
            or if a count is specified, to the end of the
            (n-1)th line below the current line.
.EL
.S
.LT
'%'         Move the cursor to the matching parenthesis,
            bracket or brace.
.EL
.S
.LT
'^'         Move the cursor to the beginning of the line.
.EL
.S
.LT
'('         Move the cursor to the beginning of the previous
            sentence.
.EL
.S
.LT
')'         Move the cursor to the beginning of the next
            sentence.
.EL
.S
.LT
'-'         Move the cursor to the first non-blank character
            on the previous line.
.EL
.S
.LT
'+'         Move the cursor to the first non-blank character
            on the next line.
.EL
.S
.LT
'w'         Move the cursor to the beginning of the next
            type of character, where types are alphanumeric,
            punctuation, and spaces (words of this type are
            commonly refered to as logical words).
.EL
.S
.LT
'W'         Move the cursor to the next space separated
            word (words of this type are commonly refered
            to as physical words).
.EL
.S
.LT
'e'         Move the cursor to the end of the current type
            of character.
.EL
.S
.LT
'E'         Move the cursor to the end of non blank
            characters.
.EL
.S
.LT
't'         Move the cursor to the the character preceeding
            that cooresponding to the next character typed,
            moving forward.
.EL
.S
.LT
'T'         Same as 't' but movement is backward.
.EL
.S
.LT
'[['        Move the cursor to the beginning of the current
            section, where a section is outlined later.
.EL
.S
.LT
']]'        Move the cursor to the beginning of the next
            section, where a section is outlined later.
.EL
.S
.LT
'{'         Move the cursor to the beginning of the current
            paragraph.
.EL
.S
.LT
'}'         Move the cursor to the beginning of the next
            paragraph.
.EL
.S
.LT
'f'         Move the cursor to the next occurance (find
            character) of the character corresponding to
            the next keystroke typed, moving backwards.
.EL
.S
.LT
'F'         Same as 'f' but movement is backwards.
.EL
.S
.LT
'G'         Move the cursor to the line specified by the
            numeric keys typed preceeding this key, or to
            the end of the document if none were typed.
.EL
.S
.LT
'h'         Move the cursor to the left one character.
.EL
.S
.LT
'H'         Move the cursor to the top of the Screen, as
            opposed to the top of the document which may
            not be the same.
.EL
.S
.LT
'j'         Move the cursor to the same column of the line
            below the current line.
.EL
.S
.LT
'k'         Move the cursor to the same column of the line
            preceeding the current line.
.EL
.S
.LT
'l'         Move the cursor to the right one character.
.EL
.S
.LT
'L'         Move the cursor to the last line on the screen,
            as opposed to the last line of the document
            which may or may not be the same.
.EL
.S
.LT
';'         Repeat the last 't' or 'f' command, or the last
            'F' or 'T' command but in the forward direction.
.EL
.S
.LT
'''         Move the cursor to the first non-space character
            of the line that the the indicated marker is set
            on.
.EL
.lm-5
.s
You probably will not adopt the immediate use of all of these movements, but
it is possible to gain proficency in their use only by using them.
.!
.send toc .ifnot global
.hl 2 ^*Sample Use of the Single Key Movements\*
.send toc .endif global
.s
Perhaps some sample uses of these movements will make their use a little more
obvious.  Typically, a VI manual resolves to give the reader a list of the most
common keystroke combinations, without trying to describe the real reasoning
behind the keystrokes.  This is part of the reason that VI seems so
foreign to some people, they never discover the relationship of all the
keystrokes to one another.  However, since I have outlined the basic
relationship of the keystrokes, I feel that I can provide a similar chart
without causing any confusion.  The notation <n> means that you may type
one or more of the keys, 0-9, to indicate a repeat count that will cause
the movement indicated to be performed the indicated number of times.
e.g. 5dw will delete five logical words, 35dd will delete thirty five lines.
.!
.send toc .ifnot global
.hl 2 ^*Common Keystroke Combinations\*
.send toc .endif global
.s
.LM +5
.LT
<n>d$   Delete (including the current character),
        to the end of the (n-1)th line.
<n>d^   Delete (excluding the current character),
        to the beginning of the (n-1)th line.
<n>dE   Delete to the end of physical words
        (or TO the next space or tab character).
<n>de   Delete to the end of logical word.
<n>dd   Delete lines.
dG      Delete from the current line to the end
        of the document.
dH      Delete from the current line to the line
        shown at the top of the display, inclusive.
<n>dh   Delete n characters to the left of the
        cursor, 'X' is equivalent to this.
<n>dj   Delete the current line, and the n lines
        below it.
<n>dk   Delete the current line, and the n lines
        above it.
<n>dl   Delete n characters to the right of the
        cursor, including the one under it,
        'x' is equivalent to this.
<n>db   Delete back to the beginning of the
        nth previous logical word.
<n>dB   Delete back to the beginning of the
        nth previous physical word.
.LM-5
.EL

.NHD
.PAGE
.X Glossary
.SEND TOC .IFNOT GLOBAL
.HL 2 ^*Glossary\*
.SEND TOC .ENDIF GLOBAL
.S
.LM +5
.LT
logical word    A word that is made up of characters
                of a common class.  The classes are
                alphabetic/numeric and '_',
                punctuation, and space or tab.

Physical word   A word that is made up of non-space
                and non-tab characters.  Or put
                another way, words made up of
                printable characters.
.EL
.lm -5
.PAGE
.REQ 'TUTOR.RNX'
*$*$*EOD*$*$*
$ if f$search("DOC.DIR;1") .eqs. "" then -
     CREATE/LOG/DIRECTORY [.DOC]
$ write sys$output "Creating [.DOC]TUTOR.RNT"
$ create [.DOC]TUTOR.RNT
$ DECK/DOLLARS="*$*$*EOD*$*$*"
.! DSRTOC version V2.1-09
.! RUNOFF/CONTENTS/OUT=TUTOR TUTOR.BRN
.SAVE
.NO FLAGS ALL
.NO FLAGS BREAK        .NO FLAGS CAPITALIZE    .NO FLAGS ENDFOOTNOTE
.NO FLAGS HYPHENATE    .NO FLAGS INDEX        .NO FLAGS PERIOD
.NO FLAGS SPACE        .NO FLAGS SUBSTITUTE
.FLAGS ACCEPT _        .FLAGS BOLD *        .FLAGS COMMENT !
.FLAGS LOWERCASE \    .FLAGS OVERSTRIKE %    .FLAGS UNDERLINE &
.FLAGS UPPERCASE ^
.FLAGS ALL
.NO FILL        .NO JUSTIFY
.LEFT MARGIN 8        .RIGHT MARGIN 70    .PAGE SIZE , 70
.CENTER;CONTENTS
.BLANK
.ifnot global
1       Introduction . . . . . . . . . . . . . . . . . . . . 1
.endif global
.ifnot global
2       Learning the power of VI . . . . . . . . . . . . . . 3
.endif global
.ifnot global
2_.1       Inserting Text . . . . . . . . . . . . . . . . . . 4
.endif global
.ifnot global
2_.2       Deleting Copying and Changing  . . . . . . . . . . 5
.endif global
.ifnot global
3       Single Key Movements . . . . . . . . . . . . . . . . 5
.endif global
.ifnot global
3_.1       Sample Use of the Single Key Movements . . . . . . 7
.endif global
.ifnot global
3_.2       Common Keystroke Combinations  . . . . . . . . . . 8
.endif global
.IFNOT GLOBAL
3_.3       Glossary . . . . . . . . . . . . . . . . . . . . . 9
.ENDIF GLOBAL
.RESTORE
*$*$*EOD*$*$*
$ if f$search("DOC.DIR;1") .eqs. "" then -
     CREATE/LOG/DIRECTORY [.DOC]
$ write sys$output "Creating [.DOC]TUTOR.RNX"
$ create [.DOC]TUTOR.RNX
$ DECK/DOLLARS="*$*$*EOD*$*$*"
.! DSRINDEX version V2.1-12
.! RUNOFF/INDEX/OUT=TUTOR TUTOR.BRN
.SAVE
.NO FLAGS ALL
.NO FLAGS BREAK        .NO FLAGS CAPITALIZE    .NO FLAGS ENDFOOTNOTE
.NO FLAGS HYPHENATE    .NO FLAGS INDEX        .NO FLAGS LOWERCASE
.NO FLAGS PERIOD    .NO FLAGS SPACE        .NO FLAGS SUBSTITUTE
.NO FLAGS UPPERCASE
.FLAGS ACCEPT _        .FLAGS BOLD *        .FLAGS COMMENT !
.FLAGS OVERSTRIKE %    .FLAGS UNDERLINE &
.FLAGS ALL
.NO FILL        .NO JUSTIFY
.LEFT MARGIN 0        .RIGHT MARGIN 70    .PAGE SIZE , 70
.NUMBER INDEX        .NUMBER PAGE 1        .FIRST TITLE
.CENTER;INDEX
.BLANK3
Deletion, 1                         Insertion, 1
                                    Introduction, 1
Escape, 3

Glossary, 9                         Undo, 3
.RESTORE
*$*$*EOD*$*$*
$ if f$search("DOC.DIR;1") .eqs. "" then -
     CREATE/LOG/DIRECTORY [.DOC]
$ write sys$output "Creating [.DOC]HOW-VI-WORKS."
$ create [.DOC]HOW-VI-WORKS.
$ DECK/DOLLARS="*$*$*EOD*$*$*"
The operaton of the program is pretty straight forward.  It goes something
like this.

command_mode:

1) TPU$INIT_PROCEDURE arranges for vi$command_mode to be called whenever ANY
   key is pressed, passing it the key_name of the pressed key.
2) vi$command_mode then looks in the cmd_keys key_map for a definition of that
   key.  This is done to funnel each key stroke through one routine that can
   aid in remembering key strokes for '.' to replay.  There is some logic there
   that determines when a valid sequence that could be replayed has been typed.
3) The PROGRAM definition for the key is checked for 0 which indicates an
   undefined key, and such keystrokes are ignored.  Otherwise, the PROGRAM
   defined for the key is envoked.

4) There is also some code here to handle the U command.  Basically, we need
   to know when the cursor moves to a new line, so that is handled here.

5) That takes care of command mode.

movements:

1) vi$command_mode invokes a program (obtained using LOOKUP_KEY (PROGRAM...))
   that is a function call to a procedure which in turn envokes a generic
   routine that returns a marker indicating the destination of the movement.  If
   the marker is zero, then the position was not found (e.g. a search command
   failed to find an occurance).  vi$position is in charge of deciding whether
   or not a particular location can be moved to, since it keeps track of the '',
   and `` markers.  Thus a typical movement procedure looks something like:

      PROCEDURE vi$find_next (direction)
          vi$position (vi$search_next (vi$old_subs, direction), 1);
      ENDPROCEDURE;

   (The names of the variables above may or may not be correct) vi$position
   must be told to remember where we were prior to doing the movement to the
   marker passed to it, and that is what the second parameter does.

delete, change, yank, shift, filter:

1) These command each read one or more keys to determine what region is being
   operated on.  An existing select region always has precedence over any other
   type of movement, so if one is active, then NO keystrokes are read. The
   move_keys map describes all of the possible movements that these routines
   will recognize.  They recognize leading numeric counts on movements such as
   d3w which is synonomous with 3dw.  They do a lot of testing for directions so
   that they will know how to adjust markers which are returned from the
   movement routines.  The movement routines are the same generic ones that are
   called from the command mode movement procedures.

2) The global values, vi$start_pos, vi$endpos, and vi$new_endpos are used to
   mark the region to be worked on.  vi$start_pos is set prior to calling any
   movement procedure, and vi$new_endpos is set to zero.  Any routine that
   wishes to doctor up the value of vi$start_pos, may, and some do.
   vi$new_endpos allows for a generic movement procedure to be written that
   returns different values based on who is using it.  cw verses dw is a
   prime example.  dw removes trailing white space, while cw does not allow
   you to change it.  Therefore, the move by word routines set vi$new_endpos
   to a different value.  Granted, this could have really been done with
   conditional returns of different values I believe, but for some reason,
   I chose this method.  vi$endpos is assigned the value returned by the
   EXECUTE ( COMPILE ("vi$endpos:="+LOOKUP_KEY(keyn,COMMENT))); statement
   which builds an assignment and compiles and executes it on the fly.
   Following this, vi$endpos will be altered if vi$new_endpos is non-zero.

3) The region to manipulate is mapped out after some hanky panky with end
   points and such, and the action is performed.

Undo:

1) Deletes are made undoable by saving the deleted text into a buffer with
   a single line at the top of the buffer describing how the text was
   deleted (i.e. dw vs. dd).  Then, vi$undo_start is set to the location
   where the text should be restored.  vi$undo_end is set to zero in the
   case of delete, as it is used to mark the end of a region of text that
   must be deleted (vi$undo_start is the start) when undo is performed.

2) Puts, are made undoable by setting vi$undo_start to the start of the
   inserted regions, and vi$undo_end to the end.  The routine vi$kill_undo
   assures that no text will be inserted for the next undo.

3) Inserts follow the same strategy as puts.

4) Change commands make use of both facets of undoing.  There is a region
   to delete, that which was typed, and a region to restore, that which
   existed previously.

   vi$perform_undo, vi$kill_undo, vi$undo_start and vi$undo_end are the
   main variables and such that undo operations deal with.

Inserting:

1) All operations that insert text into a buffer by letting the user type
   text use the routine (after a little hopscotch) vi$line_edit to do
   the actual work.  This routine does a lot of things.  It recognizes
   when abbreviations have been used, and discovers which text has and
   hasn't been typed over by an 'R' command.  Basiclly, this routine
   and its interface is not pretty.  It accepts four parameters.  A starting
   marker where inserting actually begin (this may not be where the cursor
   is at function entry), a corresponding column offset, a return
   parameter which is the ending position, and a flag which determine if
   the 'R' command is active.  This flag is either 0, or the string image
   of the line that is being 'R'd over.  This string is replaced over the
   top of characters that are 'R'd over, but then backspaced over and then
   the user hits ESCAPE.

ex mode:

1) Ex mode is a series of operations, the first is reading a string.  Next,
   the beginning is parsed to try and locate a range specification.  This
   range is indicated in several ways inside vi$do_command.  There are
   markers, line numbers, and two ranges, one being the range by line, and
   the other being the range only.  The second range comes into affect
   when things are delimited with search ranges.

2) Once the range of the command has been determined, then the rest of
   the command line is placed into the variable, cmd.  The index variable,
   idx, is used to mark the current location in cmd where we have parsed to.
   All lower case alphabetic characters are extracted from the beginning of
   cmd to get the command to perform.

3) The command is then analyzed by doing simple string compares.  There is
   a certain order to the IF's that perform this activity, as we must
   distiguish between commands with common leading substrings.

4) A special routine handles each command, and that routine has a unique
   set of arguments based on its needs.

maps:

1) Maps are handled by placing all of the KEY_NAME values of the key stokes
   into a buffer, one per line.  Whenever a mapped key is detected, then its
   buffers contents are pushed into the typing stream by the function
   vi$insert_macro_keys.  TPU's key values are really strange, and I am not
   so sure that I like the way this is done, it is just that I originally
   wanted to be able to have maps with any keystroke in them, and that
   pretty much eliminated the use of strings (well okay, maybe).

2) The routine vi$do_macro MUST be called to initiate the processing of a
   map, as TPU's main loop does not know about the pushed keys in the input
   stream.  This routines performs all of the actions indicated by the mapped
   key strokes, and then returns control to the caller.  Note that vi$do_macro
   recognizes either strings or buffers of macro key strokes.  There are some
   command mode key strokes that are mapped to macros.

      D ==> d$
      s ==> cl
      C ==> c$   etc...

learn sequences:

1) Learn sequences are implemented by creating global variables on the
   fly to contain the LEARN program.  Then, a DEFINE_KEY is done to
   pass the program to a routine that knows what to do with it.

2) This routine checks the status of :set undomap, and then performs
   the necessary stuff to set up for undo if undomap is in effect.

3) Then, the program passed is executed.  When the EXECUTE returns,
   the LEARN sequence is complete.  Note that LEARN's are different
   from MAP's in that a map can be recursive, and will stop when it
   finds an error.  A learn sequence just keeps going if it is
   recursive, and NEVER stops.
*$*$*EOD*$*$*
$ exit