(M-40132'): Unify GT-53970.

[chise/xemacs-chise.git-] / info / termcap.info-2

This is ../info/termcap.info, produced by makeinfo version 4.0 from
termcap.texi.

START-INFO-DIR-ENTRY
* Termcap: (termcap).           Termcap library of the GNU system.
END-INFO-DIR-ENTRY

   This file documents the termcap library of the GNU system.

   Copyright (C) 1988 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

\1f
File: termcap.info,  Node: Capabilities,  Next: Summary,  Prev: Data Base,  Up: Top

Definitions of the Terminal Capabilities
****************************************

   This section is divided into many subsections, each for one aspect of
use of display terminals.  For writing a display program, you usually
need only check the subsections for the operations you want to use.
For writing a terminal description, you must read each subsection and
fill in the capabilities described there.

   String capabilities that are display commands may require numeric
parameters (*note Parameters::).  Most such capabilities do not use
parameters.  When a capability requires parameters, this is explicitly
stated at the beginning of its definition.  In simple cases, the first
or second sentence of the definition mentions all the parameters, in
the order they should be given, using a name in upper case for each
one.  For example, the `rp' capability is a command that requires two
parameters; its definition begins as follows:

     String of commands to output a graphic character C, repeated N
     times.

   In complex cases or when there are many parameters, they are
described explicitly.

   When a capability is described as obsolete, this means that programs
should not be written to look for it, but terminal descriptions should
still be written to provide it.

   When a capability is described as very obsolete, this means that it
should be omitted from terminal descriptions as well.

* Menu:

* Basic::             Basic characteristics.
* Screen Size::       Screen size, and what happens when it changes.
* Cursor Motion::     Various ways to move the cursor.
* Scrolling::         Pushing text up and down on the screen.
* Wrapping::          What happens if you write a character in the last column.
* Windows::           Limiting the part of the window that output affects.
* Clearing::          Erasing one or many lines.
* Insdel Line::       Making new blank lines in mid-screen; deleting lines.
* Insdel Char::       Inserting and deleting characters within a line.
* Standout::          Highlighting some of the text.
* Underlining::       Underlining some of the text.
* Cursor Visibility:: Making the cursor more or less easy to spot.
* Bell::              Attracts user's attention; not localized on the screen.
* Keypad::            Recognizing when function keys or arrows are typed.
* Meta Key::          <META> acts like an extra shift key.
* Initialization::    Commands used to initialize or reset the terminal.
* Pad Specs::         Info for the kernel on how much padding is needed.
* Status Line::       A status line displays ``background'' information.
* Half-Line::         Moving by half-lines, for superscripts and subscripts.
* Printer::           Controlling auxiliary printers of display terminals.

\1f
File: termcap.info,  Node: Basic,  Next: Screen Size,  Prev: Capabilities,  Up: Capabilities

Basic Characteristics
=====================

   This section documents the capabilities that describe the basic and
nature of the terminal, and also those that are relevant to the output
of graphic characters.

`os'
     Flag whose presence means that the terminal can overstrike.  This
     means that outputting a graphic character does not erase whatever
     was present in the same character position before.  The terminals
     that can overstrike include printing terminals, storage tubes (all
     obsolete nowadays), and many bit-map displays.

`eo'
     Flag whose presence means that outputting a space can erase an
     overstrike.  If this is not present and overstriking is supported,
     output of a space has no effect except to move the cursor.

`gn'
     Flag whose presence means that this terminal type is a generic type
     which does not really describe any particular terminal.  Generic
     types are intended for use as the default type assigned when the
     user connects to the system, with the intention that the user
     should specify what type he really has.  One example of a generic
     type is the type `network'.

     Since the generic type cannot say how to do anything interesting
     with the terminal, termcap-using programs will always find that the
     terminal is too weak to be supported if the user has failed to
     specify a real terminal type in place of the generic one.  The
     `gn' flag directs these programs to use a different error message:
     "You have not specified your real terminal type", rather than
     "Your terminal is not powerful enough to be used".

`hc'
     Flag whose presence means this is a hardcopy terminal.

`rp'
     String of commands to output a graphic character C, repeated N
     times.  The first parameter value is the ASCII code for the desired
     character, and the second parameter is the number of times to
     repeat the character.  Often this command requires padding
     proportional to the number of times the character is repeated.
     This effect can be had by using parameter arithmetic with
     `%'-sequences to compute the amount of padding, then generating
     the result as a number at the front of the string so that `tputs'
     will treat it as padding.

`hz'
     Flag whose presence means that the ASCII character `~' cannot be
     output on this terminal because it is used for display commands.

     Programs handle this flag by checking all text to be output and
     replacing each `~' with some other character(s).  If this is not
     done, the screen will be thoroughly garbled.

     The old Hazeltine terminals that required such treatment are
     probably very rare today, so you might as well not bother to
     support this flag.

`CC'
     String whose presence means the terminal has a settable command
     character.  The value of the string is the default command
     character (which is usually <ESC>).

     All the strings of commands in the terminal description should be
     written to use the default command character.  If you are writing
     an application program that changes the command character, use the
     `CC' capability to figure out how to translate all the display
     commands to work with the new command character.

     Most programs have no reason to look at the `CC' capability.

`xb'
     Flag whose presence identifies Superbee terminals which are unable
     to transmit the characters <ESC> and `Control-C'.  Programs which
     support this flag are supposed to check the input for the code
     sequences sent by the <F1> and <F2> keys, and pretend that <ESC>
     or `Control-C' (respectively) had been read.  But this flag is
     obsolete, and not worth supporting.

\1f
File: termcap.info,  Node: Screen Size,  Next: Cursor Motion,  Prev: Basic,  Up: Capabilities

Screen Size
===========

   A terminal description has two capabilities, `co' and `li', that
describe the screen size in columns and lines.  But there is more to
the question of screen size than this.

   On some operating systems the "screen" is really a window and the
effective width can vary.  On some of these systems, `tgetnum' uses the
actual width of the window to decide what value to return for the `co'
capability, overriding what is actually written in the terminal
description.  On other systems, it is up to the application program to
check the actual window width using a system call.  For example, on BSD
4.3 systems, the system call `ioctl' with code `TIOCGWINSZ' will tell
you the current screen size.

   On all window systems, termcap is powerless to advise the application
program if the user resizes the window.  Application programs must deal
with this possibility in a system-dependent fashion.  On some systems
the C shell handles part of the problem by detecting changes in window
size and setting the `TERMCAP' environment variable appropriately.
This takes care of application programs that are started subsequently.
It does not help application programs already running.

   On some systems, including BSD 4.3, all programs using a terminal get
a signal named `SIGWINCH' whenever the screen size changes.  Programs
that use termcap should handle this signal by using `ioctl TIOCGWINSZ'
to learn the new screen size.

`co'
     Numeric value, the width of the screen in character positions.
     Even hardcopy terminals normally have a `co' capability.

`li'
     Numeric value, the height of the screen in lines.

\1f
File: termcap.info,  Node: Cursor Motion,  Next: Wrapping,  Prev: Screen Size,  Up: Capabilities

Cursor Motion
=============

   Termcap assumes that the terminal has a "cursor", a spot on the
screen where a visible mark is displayed, and that most display
commands take effect at the position of the cursor.  It follows that
moving the cursor to a specified location is very important.

   There are many terminal capabilities for different cursor motion
operations.  A terminal description should define as many as possible,
but most programs do not need to use most of them.  One capability,
`cm', moves the cursor to an arbitrary place on the screen; this by
itself is sufficient for any application as long as there is no need to
support hardcopy terminals or certain old, weak displays that have only
relative motion commands.  Use of other cursor motion capabilities is an
optimization, enabling the program to output fewer characters in some
common cases.

   If you plan to use the relative cursor motion commands in an
application program, you must know what the starting cursor position
is.  To do this, you must keep track of the cursor position and update
the records each time anything is output to the terminal, including
graphic characters.  In addition, it is necessary to know whether the
terminal wraps after writing in the rightmost column.  *Note Wrapping::.

   One other motion capability needs special mention: `nw' moves the
cursor to the beginning of the following line, perhaps clearing all the
starting line after the cursor, or perhaps not clearing at all.  This
capability is a least common denominator that is probably supported
even by terminals that cannot do most other things such as `cm' or `do'.
Even hardcopy terminals can support `nw'.

`cm'
     String of commands to position the cursor at line L, column C.
     Both parameters are origin-zero, and are defined relative to the
     screen, not relative to display memory.

     All display terminals except a few very obsolete ones support `cm',
     so it is acceptable for an application program to refuse to
     operate on terminals lacking `cm'.

`ho'
     String of commands to move the cursor to the upper left corner of
     the screen (this position is called the "home position").  In
     terminals where the upper left corner of the screen is not the
     same as the beginning of display memory, this command must go to
     the upper left corner of the screen, not the beginning of display
     memory.

     Every display terminal supports this capability, and many
     application programs refuse to operate if the `ho' capability is
     missing.

`ll'
     String of commands to move the cursor to the lower left corner of
     the screen.  On some terminals, moving up from home position does
     this, but programs should never assume that will work.  Just
     output the `ll' string (if it is provided); if moving to home
     position and then moving up is the best way to get there, the `ll'
     command will do that.

`cr'
     String of commands to move the cursor to the beginning of the line
     it is on.  If this capability is not specified, many programs
     assume they can use the ASCII carriage return character for this.

`le'
     String of commands to move the cursor left one column.  Unless the
     `bw' flag capability is specified, the effect is undefined if the
     cursor is at the left margin; do not use this command there.  If
     `bw' is present, this command may be used at the left margin, and
     it wraps the cursor to the last column of the preceding line.

`nd'
     String of commands to move the cursor right one column.  The
     effect is undefined if the cursor is at the right margin; do not
     use this command there, not even if `am' is present.

`up'
     String of commands to move the cursor vertically up one line.  The
     effect of sending this string when on the top line is undefined;
     programs should never use it that way.

`do'
     String of commands to move the cursor vertically down one line.
     The effect of sending this string when on the bottom line is
     undefined; programs should never use it that way.

     The original idea was that this string would not contain a newline
     character and therefore could be used without disabling the
     kernel's usual habit of converting of newline into a
     carriage-return newline sequence.  But many terminal descriptions
     do use newline in the `do' string, so this is not possible; a
     program which sends the `do' string must disable output conversion
     in the kernel (*note Initialize::).

`bw'
     Flag whose presence says that `le' may be used in column zero to
     move to the last column of the preceding line.  If this flag is
     not present, `le' should not be used in column zero.

`nw'
     String of commands to move the cursor to start of next line,
     possibly clearing rest of line (following the cursor) before
     moving.

`DO', `UP', `LE', `RI'
     Strings of commands to move the cursor N lines down vertically, up
     vertically, or N columns left or right.  Do not attempt to move
     past any edge of the screen with these commands; the effect of
     trying that is undefined.  Only a few terminal descriptions provide
     these commands, and most programs do not use them.

`CM'
     String of commands to position the cursor at line L, column C,
     relative to display memory.  Both parameters are origin-zero.
     This capability is present only in terminals where there is a
     difference between screen-relative and memory-relative addressing,
     and not even in all such terminals.

`ch'
     String of commands to position the cursor at column C in the same
     line it is on.  This is a special case of `cm' in which the
     vertical position is not changed.  The `ch' capability is provided
     only when it is faster to output than `cm' would be in this
     special case.  Programs should not assume most display terminals
     have `ch'.

`cv'
     String of commands to position the cursor at line L in the same
     column.  This is a special case of `cm' in which the horizontal
     position is not changed.  The `cv' capability is provided only
     when it is faster to output than `cm' would be in this special
     case.  Programs should not assume most display terminals have `cv'.

`sc'
     String of commands to make the terminal save the current cursor
     position.  Only the last saved position can be used.  If this
     capability is present, `rc' should be provided also.  Most
     terminals have neither.

`rc'
     String of commands to make the terminal restore the last saved
     cursor position.  If this capability is present, `sc' should be
     provided also.  Most terminals have neither.

`ff'
     String of commands to advance to the next page, for a hardcopy
     terminal.

`ta'
     String of commands to move the cursor right to the next hardware
     tab stop column.  Missing if the terminal does not have any kind of
     hardware tabs.  Do not send this command if the kernel's terminal
     modes say that the kernel is expanding tabs into spaces.

`bt'
     String of commands to move the cursor left to the previous hardware
     tab stop column.  Missing if the terminal has no such ability; many
     terminals do not.  Do not send this command if the kernel's
     terminal modes say that the kernel is expanding tabs into spaces.

   The following obsolete capabilities should be included in terminal
descriptions when appropriate, but should not be looked at by new
programs.

`nc'
     Flag whose presence means the terminal does not support the ASCII
     carriage return character as `cr'.  This flag is needed because
     old programs assume, when the `cr' capability is missing, that
     ASCII carriage return can be used for the purpose.  We use `nc' to
     tell the old programs that carriage return may not be used.

     New programs should not assume any default for `cr', so they need
     not look at `nc'.  However, descriptions should contain `nc'
     whenever they do not contain `cr'.

`xt'
     Flag whose presence means that the ASCII tab character may not be
     used for cursor motion.  This flag exists because old programs
     assume, when the `ta' capability is missing, that ASCII tab can be
     used for the purpose.  We use `xt' to tell the old programs not to
     use tab.

     New programs should not assume any default for `ta', so they need
     not look at `xt' in connection with cursor motion.  Note that `xt'
     also has implications for standout mode (*note Standout::).  It is
     obsolete in regard to cursor motion but not in regard to standout.

     In fact, `xt' means that the terminal is a Teleray 1061.

`bc'
     Very obsolete alternative name for the `le' capability.

`bs'
     Flag whose presence means that the ASCII character backspace may be
     used to move the cursor left.  Obsolete; look at `le' instead.

`nl'
     Obsolete capability which is a string that can either be used to
     move the cursor down or to scroll.  The same string must scroll
     when used on the bottom line and move the cursor when used on any
     other line.  New programs should use `do' or `sf', and ignore `nl'.

     If there is no `nl' capability, some old programs assume they can
     use the newline character for this purpose.  These programs follow
     a bad practice, but because they exist, it is still desirable to
     define the `nl' capability in a terminal description if the best
     way to move down is _not_ a newline.

\1f
File: termcap.info,  Node: Wrapping,  Next: Scrolling,  Prev: Cursor Motion,  Up: Capabilities

Wrapping
========

   "Wrapping" means moving the cursor from the right margin to the left
margin of the following line.  Some terminals wrap automatically when a
graphic character is output in the last column, while others do not.
Most application programs that use termcap need to know whether the
terminal wraps.  There are two special flag capabilities to describe
what the terminal does when a graphic character is output in the last
column.

`am'
     Flag whose presence means that writing a character in the last
     column causes the cursor to wrap to the beginning of the next line.

     If `am' is not present, writing in the last column leaves the
     cursor at the place where the character was written.

     Writing in the last column of the last line should be avoided on
     terminals with `am', as it may or may not cause scrolling to occur
     (*note Scrolling::).  Scrolling is surely not what you would
     intend.

     If your program needs to check the `am' flag, then it also needs
     to check the `xn' flag which indicates that wrapping happens in a
     strange way.  Many common terminals have the `xn' flag.

`xn'
     Flag whose presence means that the cursor wraps in a strange way.
     At least two distinct kinds of strange behavior are known; the
     termcap data base does not contain anything to distinguish the two.

     On Concept-100 terminals, output in the last column wraps the
     cursor almost like an ordinary `am' terminal.  But if the next
     thing output is a newline, it is ignored.

     DEC VT-100 terminals (when the wrap switch is on) do a different
     strange thing: the cursor wraps only if the next thing output is
     another graphic character.  In fact, the wrap occurs when the
     following graphic character is received by the terminal, before the
     character is placed on the screen.

     On both of these terminals, after writing in the last column a
     following graphic character will be displayed in the first column
     of the following line.  But the effect of relative cursor motion
     characters such as newline or backspace at such a time depends on
     the terminal.  The effect of erase or scrolling commands also
     depends on the terminal.  You can't assume anything about what
     they will do on a terminal that has `xn'.  So, to be safe, you
     should never do these things at such a time on such a terminal.

     To be sure of reliable results on a terminal which has the `xn'
     flag, output a `cm' absolute positioning command after writing in
     the last column.  Another safe thing to do is to output
     carriage-return newline, which will leave the cursor at the
     beginning of the following line.

\1f
File: termcap.info,  Node: Scrolling,  Next: Windows,  Prev: Wrapping,  Up: Capabilities

Scrolling
=========

   "Scrolling" means moving the contents of the screen up or down one or
more lines.  Moving the contents up is "forward scrolling"; moving them
down is "reverse scrolling".

   Scrolling happens after each line of output during ordinary output
on most display terminals.  But in an application program that uses
termcap for random-access output, scrolling happens only when
explicitly requested with the commands in this section.

   Some terminals have a "scroll region" feature.  This lets you limit
the effect of scrolling to a specified range of lines.  Lines outside
the range are unaffected when scrolling happens.  The scroll region
feature is available if either `cs' or `cS' is present.

`sf'
     String of commands to scroll the screen one line up, assuming it is
     output with the cursor at the beginning of the bottom line.

`sr'
     String of commands to scroll the screen one line down, assuming it
     is output with the cursor at the beginning of the top line.

`SF'
     String of commands to scroll the screen N lines up, assuming it is
     output with the cursor at the beginning of the bottom line.

`SR'
     String of commands to scroll the screen N line down, assuming it
     is output with the cursor at the beginning of the top line.

`cs'
     String of commands to set the scroll region.  This command takes
     two parameters, START and END, which are the line numbers
     (origin-zero) of the first line to include in the scroll region
     and of the last line to include in it.  When a scroll region is
     set, scrolling is limited to the specified range of lines; lines
     outside the range are not affected by scroll commands.

     Do not try to move the cursor outside the scroll region.  The
     region remains set until explicitly removed.  To remove the scroll
     region, use another `cs' command specifying the full height of the
     screen.

     The cursor position is undefined after the `cs' command is set, so
     position the cursor with `cm' immediately afterward.

`cS'
     String of commands to set the scroll region using parameters in
     different form.  The effect is the same as if `cs' were used.
     Four parameters are required:

       1. Total number of lines on the screen.

       2. Number of lines above desired scroll region.

       3. Number of lines below (outside of) desired scroll region.

       4. Total number of lines on the screen, the same as the first
          parameter.

     This capability is a GNU extension that was invented to allow the
     Ann Arbor Ambassador's scroll-region command to be described; it
     could also be done by putting non-Unix `%'-sequences into a `cs'
     string, but that would have confused Unix programs that used the
     `cs' capability with the Unix termcap.  Currently only GNU Emacs
     uses the `cS' capability.

`ns'
     Flag which means that the terminal does not normally scroll for
     ordinary sequential output.  For modern terminals, this means that
     outputting a newline in ordinary sequential output with the cursor
     on the bottom line wraps to the top line.  For some obsolete
     terminals, other things may happen.

     The terminal may be able to scroll even if it does not normally do
     so.  If the `sf' capability is provided, it can be used for
     scrolling regardless of `ns'.

`da'
     Flag whose presence means that lines scrolled up off the top of the
     screen may come back if scrolling down is done subsequently.

     The `da' and `db' flags do not, strictly speaking, affect how to
     scroll.  But programs that scroll usually need to clear the lines
     scrolled onto the screen, if these flags are present.

`db'
     Flag whose presence means that lines scrolled down off the bottom
     of the screen may come back if scrolling up is done subsequently.

`lm'
     Numeric value, the number of lines of display memory that the
     terminal has.  A value of zero means that the terminal has more
     display memory than can fit on the screen, but no fixed number of
     lines.  (The number of lines may depend on the amount of text in
     each line.)

   Any terminal description that defines `SF' should also define `sf';
likewise for `SR' and `sr'.  However, many terminals can only scroll by
one line at a time, so it is common to find `sf' and not `SF', or `sr'
without `SR'.

   Therefore, all programs that use the scrolling facilities should be
prepared to work with `sf' in the case that `SF' is absent, and
likewise with `sr'.  On the other hand, an application program that
uses only `sf' and not `SF' is acceptable, though slow on some
terminals.

   When outputting a scroll command with `tputs', the NLINES argument
should be the total number of lines in the portion of the screen being
scrolled.  Very often these commands require padding proportional to
this number of lines.  *Note Padding::.

\1f
File: termcap.info,  Node: Windows,  Next: Clearing,  Prev: Scrolling,  Up: Capabilities

Windows
=======

   A "window", in termcap, is a rectangular portion of the screen to
which all display operations are restricted.  Wrapping, clearing,
scrolling, insertion and deletion all operate as if the specified
window were all the screen there was.

`wi'
     String of commands to set the terminal output screen window.  This
     string requires four parameters, all origin-zero:
       1. The first line to include in the window.

       2. The last line to include in the window.

       3. The first column to include in the window.

       4. The last column to include in the window.

   Most terminals do not support windows.

\1f
File: termcap.info,  Node: Clearing,  Next: Insdel Line,  Prev: Windows,  Up: Capabilities

Clearing Parts of the Screen
============================

   There are several terminal capabilities for clearing parts of the
screen to blank.  All display terminals support the `cl' string, and
most display terminals support all of these capabilities.

`cl'
     String of commands to clear the entire screen and position the
     cursor at the upper left corner.

`cd'
     String of commands to clear the line the cursor is on, and all the
     lines below it, down to the bottom of the screen.  This command
     string should be used only with the cursor in column zero; their
     effect is undefined if the cursor is elsewhere.

`ce'
     String of commands to clear from the cursor to the end of the
     current line.

`ec'
     String of commands to clear N characters, starting with the
     character that the cursor is on.  This command string is expected
     to leave the cursor position unchanged.  The parameter N should
     never be large enough to reach past the right margin; the effect
     of such a large parameter would be undefined.

   Clear to end of line (`ce') is extremely important in programs that
maintain an updating display.  Nearly all display terminals support this
operation, so it is acceptable for a an application program to refuse to
work if `ce' is not present.  However, if you do not want this
limitation, you can accomplish clearing to end of line by outputting
spaces until you reach the right margin.  In order to do this, you must
know the current horizontal position.  Also, this technique assumes
that writing a space will erase.  But this happens to be true on all
the display terminals that fail to support `ce'.

\1f
File: termcap.info,  Node: Insdel Line,  Next: Insdel Char,  Prev: Clearing,  Up: Capabilities

Insert/Delete Line
==================

   "Inserting a line" means creating a blank line in the middle of the
screen, and pushing the existing lines of text apart.  In fact, the
lines above the insertion point do not change, while the lines below
move down, and one is normally lost at the bottom of the screen.

   "Deleting a line" means causing the line to disappear from the
screen, closing up the gap by moving the lines below it upward.  A new
line appears at the bottom of the screen.  Usually this line is blank,
but on terminals with the `db' flag it may be a line previously moved
off the screen bottom by scrolling or line insertion.

   Insertion and deletion of lines is useful in programs that maintain
an updating display some parts of which may get longer or shorter.
They are also useful in editors for scrolling parts of the screen, and
for redisplaying after lines of text are killed or inserted.

   Many terminals provide commands to insert or delete a single line at
the cursor position.  Some provide the ability to insert or delete
several lines with one command, using the number of lines to insert or
delete as a parameter.  Always move the cursor to column zero before
using any of these commands.

`al'
     String of commands to insert a blank line before the line the
     cursor is on.  The existing line, and all lines below it, are
     moved down.  The last line in the screen (or in the scroll region,
     if one is set) disappears and in most circumstances is discarded.
     It may not be discarded if the `db' is present (*note Scrolling::).

     The cursor must be at the left margin before this command is used.
     This command does not move the cursor.

`dl'
     String of commands to delete the line the cursor is on.  The
     following lines move up, and a blank line appears at the bottom of
     the screen (or bottom of the scroll region).  If the terminal has
     the `db' flag, a nonblank line previously pushed off the screen
     bottom may reappear at the bottom.

     The cursor must be at the left margin before this command is used.
     This command does not move the cursor.

`AL'
     String of commands to insert N blank lines before the line that
     the cursor is on.  It is like `al' repeated N times, except that
     it is as fast as one `al'.

`DL'
     String of commands to delete N lines starting with the line that
     the cursor is on.  It is like `dl' repeated N times, except that
     it is as fast as one `dl'.

   Any terminal description that defines `AL' should also define `al';
likewise for `DL' and `dl'.  However, many terminals can only insert or
delete one line at a time, so it is common to find `al' and not `AL',
or `dl' without `DL'.

   Therefore, all programs that use the insert and delete facilities
should be prepared to work with `al' in the case that `AL' is absent,
and likewise with `dl'.  On the other hand, it is acceptable to write
an application that uses only `al' and `dl' and does not look for `AL'
or `DL' at all.

   If a terminal does not support line insertion and deletion directly,
but does support a scroll region, the effect of insertion and deletion
can be obtained with scrolling.  However, it is up to the individual
user program to check for this possibility and use the scrolling
commands to get the desired result.  It is fairly important to implement
this alternate strategy, since it is the only way to get the effect of
line insertion and deletion on the popular VT100 terminal.

   Insertion and deletion of lines is affected by the scroll region on
terminals that have a settable scroll region.  This is useful when it is
desirable to move any few consecutive lines up or down by a few lines.
*Note Scrolling::.

   The line pushed off the bottom of the screen is not lost if the
terminal has the `db' flag capability; instead, it is pushed into
display memory that does not appear on the screen.  This is the same
thing that happens when scrolling pushes a line off the bottom of the
screen.  Either reverse scrolling or deletion of a line can bring the
apparently lost line back onto the bottom of the screen.  If the
terminal has the scroll region feature as well as `db', the pushed-out
line really is lost if a scroll region is in effect.

   When outputting an insert or delete command with `tputs', the NLINES
argument should be the total number of lines from the cursor to the
bottom of the screen (or scroll region).  Very often these commands
require padding proportional to this number of lines.  *Note Padding::.

   For `AL' and `DL' the NLINES argument should _not_ depend on the
number of lines inserted or deleted; only the total number of lines
affected.  This is because it is just as fast to insert two or N lines
with `AL' as to insert one line with `al'.

\1f
File: termcap.info,  Node: Insdel Char,  Next: Standout,  Prev: Insdel Line,  Up: Capabilities

Insert/Delete Character
=======================

   "Inserting a character" means creating a blank space in the middle
of a line, and pushing the rest of the line rightward.  The character
in the rightmost column is lost.

   "Deleting a character" means causing the character to disappear from
the screen, closing up the gap by moving the rest of the line leftward.
A blank space appears in the rightmost column.

   Insertion and deletion of characters is useful in programs that
maintain an updating display some parts of which may get longer or
shorter.  It is also useful in editors for redisplaying the results of
editing within a line.

   Many terminals provide commands to insert or delete a single
character at the cursor position.  Some provide the ability to insert
or delete several characters with one command, using the number of
characters to insert or delete as a parameter.

   Many terminals provide an insert mode in which outputting a graphic
character has the added effect of inserting a position for that
character.  A special command string is used to enter insert mode and
another is used to exit it.  The reason for designing a terminal with
an insert mode rather than an insert command is that inserting
character positions is usually followed by writing characters into
them.  With insert mode, this is as fast as simply writing the
characters, except for the fixed overhead of entering and leaving
insert mode.  However, when the line speed is great enough, padding may
be required for the graphic characters output in insert mode.

   Some terminals require you to enter insert mode and then output a
special command for each position to be inserted.  Or they may require
special commands to be output before or after each graphic character to
be inserted.

   Deletion of characters is usually accomplished by a straightforward
command to delete one or several positions; but on some terminals, it
is necessary to enter a special delete mode before using the delete
command, and leave delete mode afterward.  Sometimes delete mode and
insert mode are the same mode.

   Some terminals make a distinction between character positions in
which a space character has been output and positions which have been
cleared.  On these terminals, the effect of insert or delete character
runs to the first cleared position rather than to the end of the line.
In fact, the effect may run to more than one line if there is no
cleared position to stop the shift on the first line.  These terminals
are identified by the `in' flag capability.

   On terminals with the `in' flag, the technique of skipping over
characters that you know were cleared, and then outputting text later
on in the same line, causes later insert and delete character
operations on that line to do nonstandard things.  A program that has
any chance of doing this must check for the `in' flag and must be
careful to write explicit space characters into the intermediate
columns when `in' is present.

   A plethora of terminal capabilities are needed to describe all of
this complexity.  Here is a list of them all.  Following the list, we
present an algorithm for programs to use to take proper account of all
of these capabilities.

`im'
     String of commands to enter insert mode.

     If the terminal has no special insert mode, but it can insert
     characters with a special command, `im' should be defined with a
     null value, because the `vi' editor assumes that insertion of a
     character is impossible if `im' is not provided.

     New programs should not act like `vi'.  They should pay attention
     to `im' only if it is defined.

`ei'
     String of commands to leave insert mode.  This capability must be
     present if `im' is.

     On a few old terminals the same string is used to enter and exit
     insert mode.  This string turns insert mode on if it was off, and
     off if it was on.  You can tell these terminals because the `ei'
     string equals the `im' string.  If you want to support these
     terminals, you must always remember accurately whether insert mode
     is in effect.  However, these terminals are obsolete, and it is
     reasonable to refuse to support them.  On all modern terminals, you
     can safely output `ei' at any time to ensure that insert mode is
     turned off.

`ic'
     String of commands to insert one character position at the cursor.
     The cursor does not move.

     If outputting a graphic character while in insert mode is
     sufficient to insert the character, then the `ic' capability
     should be defined with a null value.

     If your terminal offers a choice of ways to insert--either use
     insert mode or use a special command--then define `im' and do not
     define `ic', since this gives the most efficient operation when
     several characters are to be inserted.  _Do not_ define both
     strings, for that means that _both_ must be used each time
     insertion is done.

`ip'
     String of commands to output following an inserted graphic
     character in insert mode.  Often it is used just for a padding
     spec, when padding is needed after an inserted character (*note
     Padding::).

`IC'
     String of commands to insert N character positions at and after
     the cursor.  It has the same effect as repeating the `ic' string
     and a space, N times.

     If `IC' is provided, application programs may use it without first
     entering insert mode.

`mi'
     Flag whose presence means it is safe to move the cursor while in
     insert mode and assume the terminal remains in insert mode.

`in'
     Flag whose presence means that the terminal distinguishes between
     character positions in which space characters have been output and
     positions which have been cleared.

   An application program can assume that the terminal can do character
insertion if _any one of_ the capabilities `IC', `im', `ic' or `ip' is
provided.

   To insert N blank character positions, move the cursor to the place
to insert them and follow this algorithm:

  1. If an `IC' string is provided, output it with parameter N and you
     are finished.  Otherwise (or if you don't want to bother to look
     for an `IC' string) follow the remaining steps.

  2. Output the `im' string, if there is one, unless the terminal is
     already in insert mode.

  3. Repeat steps 4 through 6, N times.

  4. Output the `ic' string if any.

  5. Output a space.

  6. Output the `ip' string if any.

  7. Output the `ei' string, eventually, to exit insert mode.  There is
     no need to do this right away.  If the `mi' flag is present, you
     can move the cursor and the cursor will remain in insert mode;
     then you can do more insertion elsewhere without reentering insert
     mode.

   To insert N graphic characters, position the cursor and follow this
algorithm:

  1. If an `IC' string is provided, output it with parameter N, then
     output the graphic characters, and you are finished.  Otherwise
     (or if you don't want to bother to look for an `IC' string) follow
     the remaining steps.

  2. Output the `im' string, if there is one, unless the terminal is
     already in insert mode.

  3. For each character to be output, repeat steps 4 through 6.

  4. Output the `ic' string if any.

  5. Output the next graphic character.

  6. Output the `ip' string if any.

  7. Output the `ei' string, eventually, to exit insert mode.  There is
     no need to do this right away.  If the `mi' flag is present, you
     can move the cursor and the cursor will remain in insert mode;
     then you can do more insertion elsewhere without reentering insert
     mode.

   Note that this is not the same as the original Unix termcap
specifications in one respect: it assumes that the `IC' string can be
used without entering insert mode.  This is true as far as I know, and
it allows you be able to avoid entering and leaving insert mode, and
also to be able to avoid the inserted-character padding after the
characters that go into the inserted positions.

   Deletion of characters is less complicated; deleting one column is
done by outputting the `dc' string.  However, there may be a delete
mode that must be entered with `dm' in order to make `dc' work.

`dc'
     String of commands to delete one character position at the cursor.
     If `dc' is not present, the terminal cannot delete characters.

`DC'
     String of commands to delete N characters starting at the cursor.
     It has the same effect as repeating the `dc' string N times.  Any
     terminal description that has `DC' also has `dc'.

`dm'
     String of commands to enter delete mode.  If not present, there is
     no delete mode, and `dc' can be used at any time (assuming there is
     a `dc').

`ed'
     String of commands to exit delete mode.  This must be present if
     `dm' is.

   To delete N character positions, position the cursor and follow these
steps:

  1. If the `DC' string is present, output it with parameter N and you
     are finished.  Otherwise, follow the remaining steps.

  2. Output the `dm' string, unless you know the terminal is already in
     delete mode.

  3. Output the `dc' string N times.

  4. Output the `ed' string eventually.  If the flag capability `mi' is
     present, you can move the cursor and do more deletion without
     leaving and reentering delete mode.

   As with the `IC' string, we have departed from the original termcap
specifications by assuming that `DC' works without entering delete mode
even though `dc' would not.

   If the `dm' and `im' capabilities are both present and have the same
value, it means that the terminal has one mode for both insertion and
deletion.  It is useful for a program to know this, because then it can
do insertions after deletions, or vice versa, without leaving
insert/delete mode and reentering it.