TERMCAP environment variable. (I am going to get flamed for this).

[Dan Mercer]

In article <1990Jun5.082147.26326 at athena.mit.edu> jik at athena.mit.edu (Jonathan I. Kamens) writes:
:In article <quan.644391709 at sol>, quan at sol.surv.utas.oz (Stephen Quan) writes:
:|> I known I am going to get flamed for this one, so I just say that I
:|> can expect someone from around the corner to tell me to RTFM.
:|> (RTFM almost = Read the Fine Manual).
:
:  OK, since you expect it, I'll do it.  RTFM.
:
:|> Can someone explain the parameters, I just need to know the essential
:|> ones are to get vi going.  At the moment we have one but sometimes it
:|> plays up on me, so have to constantly redraw -  I would like to have
:|> a go making my own.
:
:  Have you looked at the man page termcap(5)?  It very clearly describes
:what the entries in /etc/termcap mean, how to format them, and which
:ones are the most important in any termcap entry.  Any attempt by
:someone on the net to answer your question would probably just be an
:attempt to summarize in less space what is already contained in the man page.
:
:  If you don't have the man page at your site, let me know in E-mail and
:I'll mail you a copy.  But you should.
:
:Jonathan Kamens                          USnail:
:MIT Project Athena             11 Ashford Terrace
:jik at Athena.MIT.EDU             Allston, MA  02134
:Office: 617-253-8495                 Home: 617-782-0710

RTFM'ing is not always the answer.  My manual notes more than 
100 capabilities.  No entry gets more than 20 words commentary.
Most of the capabilities are not used by vi.  The manual entry runs
12 pages long and is written in typical techno-gibberish.  IF you
know UNIX,  and IF you are a programmer,  and IF you know asynch
terminals,  eventually,  it all makes sense.

The problem with UNIX is that it came out of a computer environment -
AT&T's labs and Berkeley's computer school.  But UNIX has been slowly
gaining acceptance in non-technical markets.  All too often,  unfortunately,
the prejudices of the techies have inhibited that
acceptance.  (I have a long flame here for those who have ported
UNIX to PC's without thinking long and hard about those who will
use those machines,  but I'll forego it).

Most people don't have time to RTFM.  Their job is using UNIX or vi,
or whatever,  not making it work.  

So,  off the soap box now, here's a brief set of suggestions:

Capabilities are of three types: boolean flags,  integers,  and strings.
If a boolean flag is named,  it's value is 1, else zero.  Integers take
the form capname#number.  Strings take the form capname=[delay*]string.

Major booleans used by vi:

am - if included,  says that your terminal will automatically advance
the cursor from the last column on the line to the first column on the
next.  VT100's and other ANSI terminals (including PC's using ANSI.SYS
and its clones) may be run either with auto margins or without.  There
is a bug in the VT100 in am mode,  however,  that causes a line feed
after column 80 to be treated as an ordinary character.
This causes a dual line feed to be generated (one for the auto margin
plus the actual line feed).  The screen will paint all wrong and the
cursor will not go to the right spot.  For vt100's,  am should be
excluded and the termcap should force the terminal into non-am
mode.

bs - ^H causes physical backspace.

mi - safe to move while in insert mode.  It is more efficient to insert
characters using the terminal's capabilities than to have vi insert
them.  If your terminal supports an insert mode and it is safe to
move the cursor while in it,  use this. 

ns - set if terminal does not autoscroll.

Major integers used by vi:

co - number of columns in display.

li - number of lines in display.

Major strings used by vi:

cursor positioning: cursor motion, home, up, down, left, right,
                    carriage return

cm - cursor motion.  What you define here is the formula for advancing
     the cursor to a given spot on the screen. 
     The following description is from the manual:

     Cursor addressing in the terminal is described by a cm
     string capability, with escapes like %x in it, similar to
     those of printf(3S).  These substitute to encodings of the
     current line or column position, while other characters are
     passed through unchanged.  If the cm string is thought of as
     being a function, then its arguments are the line and then
     the column to which motion is desired, and the % encodings
     have the following meanings:

        %d   as in printf, 0 origin
        %2   like %2d
        %3   like %3d
        %.   like %c
        %+x  adds x to value, then %
        %>xy if value > x adds y, no output
        %r   reverses order of line and column, no output
        %i   increments line/column (for 1 origin)
        %%   gives a single %
        %n   exclusive or row and column with 0140 (DM2500)
        %B   BCD (16*(x/10)) + (x%10), no output
        %D   Reverse coding (x-2*(x%16)), no output (Delta Data)

     Consider the HP2645, which, to get to row 3 and column 12,
     needs to be sent \E&a12c03Y padded for 6 milliseconds.  Note
     that the order of the rows and columns is inverted here, and
     that the row and column are printed as two digits.  Thus its
     cm capability is cm=6\E&%r%2c%2Y.

     The Microterm ACT-IV needs the current row and column sent
     preceded by a ^T, with the row and column simply encoded in
     binary, cm=^T%.%..

     Terminals which use %. need to be able to backspace the
     cursor (bs or bc), and to move the cursor up one line on the
     screen (up introduced below).  This is necessary because it
     is not always safe to transmit \t, \n ^D and \r, as the
     system may change or discard them.

      A final example is the LSI ADM-3a, which uses row and column
      offset by a blank character, thus cm=\E=%+ %+ .

ti - enter cursor motion mode - vi will send this out whenever it
     starts up (or returns from shell).  If you have a vt100,
     this is the place to put the string to prevent automargins -
                  ti=\E[?7l
     I also use this string to set my screen colors.

te - exit cm mode - vi sends this on exit to shell.  For a vt100,
     you can return to am mode with:
                     te=\E[?7h

ho - home cursor.  Home is considered to be upper left.  Older
     terminals frequently home to lower left.  If this is true,
     just code up a cursor positioning string to move cursor to
     upper left.

up - move cursor up.

do - move cursor down.

le - move cursor left (left out of my man pages)

bc - move cursor left - non destructive backspace - also works

nd - move cursor right - non destructive space 

cr - move cursor to first position on line.  Normally,  a carraige
     return does this.  But there is a bug in newer SYS V's in which
     a carriage return is followed by a null.  ANSI.SYS and clones
     print nulls as spaces,  so we've redefined cr as \E[80D.

area clearing:

cl - clear screen.  Vi will expect cursor to be in home (upper left)
     position.  If clear string does not move cursor appropriately,
     you should add home sequence to it.

cd - clear to end of display - likely culprit for mangled screens.

ce - clear to end of line - another likely culprit for mangled screens.

Editing functions:

al - insert a line.

dl - delete a line.

dc - delete one character.

ic - insert one character (shift data right one character from
       current position leaving cursor in current position.  Character
       written to this spot will not cause further shifting.  Pretty
       rare capability.

im - enter character insert mode (characters will be placed at
     current position forcing shift to right of other characters,
     and the character position will advance).  This is the more
     commonly used string.  Ic should not be defined if im is and
     vice versa.  In my manual pages,  im is incorrectly shown as
     a bool.

ei - exit insert mode.  With ADDS Viewpoint 90's,  insert mode
     is a single character toggle.  Curses sends out ei at
     irregular intervals (such as startup) to make sure terminal
     is not in insert mode,  of course putting the V90 into insert
     mode and clobbering screen.  We keep separate termcaps for
     V90's using vi and using curses.

Miscellaneous:

cs - set scrolling region.  Some terminals can set up just a 
     portion of the screen to scroll.  I don't advise setting this
     for beginners.  More experienced people should realize that
     vi will expect the cursor to be in the upper left position
     of the scrolling region and the string should provide for
     that.


I would suggest putting together a termcap with just these
capabilities and getting it to work,  then add capabilities from
your existing file and see what breaks it.

-- 

Dan Mercer
Reply-To: mercer at ncrstp.StPaul.NCR.COM (Dan Mercer)