Return to termcap.texi CVS log

Up to [Apple XNU] / GNUtools / emacs / man

Annotation of GNUtools/emacs/man/termcap.texi, revision 1.1

1.1     ! root        1: \input texinfo  @c -*-texinfo-*-
        !             2: @setfilename ../info/termcap
        !             3: @settitle The Termcap Library
        !             4: @ifinfo
        !             5: This file documents the termcap library of the GNU system.
        !             6: 
        !             7: Copyright (C) 1988 Free Software Foundation, Inc.
        !             8: 
        !             9: Permission is granted to make and distribute verbatim copies of
        !            10: this manual provided the copyright notice and this permission notice
        !            11: are preserved on all copies.
        !            12: 
        !            13: @ignore
        !            14: Permission is granted to process this file through TeX and print the
        !            15: results, provided the printed document carries copying permission
        !            16: notice identical to this one except for the removal of this paragraph
        !            17: (this paragraph not being relevant to the printed manual).
        !            18: 
        !            19: @end ignore
        !            20: Permission is granted to copy and distribute modified versions of this
        !            21: manual under the conditions for verbatim copying, provided that the entire
        !            22: resulting derived work is distributed under the terms of a permission
        !            23: notice identical to this one.
        !            24: 
        !            25: Permission is granted to copy and distribute translations of this manual
        !            26: into another language, under the above conditions for modified versions,
        !            27: except that this permission notice may be stated in a translation approved
        !            28: by the Foundation.
        !            29: @end ifinfo
        !            30: 
        !            31: @setchapternewpage odd
        !            32: @titlepage
        !            33: @sp 6
        !            34: @center @titlefont{Termcap}
        !            35: @sp 1
        !            36: @center The Termcap Library and Data Base
        !            37: @sp 4
        !            38: @center Second Edition
        !            39: @sp 1
        !            40: @center August 1992
        !            41: @sp 5
        !            42: @center Richard M. Stallman
        !            43: @sp 1
        !            44: @center Free Software Foundation
        !            45: @page
        !            46: @vskip 0pt plus 1filll
        !            47: Copyright @copyright{} 1988 Free Software Foundation, Inc.
        !            48: 
        !            49: Published by the Free Software Foundation
        !            50: (675 Mass Ave, Cambridge MA 02139).
        !            51: Printed copies are available for $10 each.
        !            52: 
        !            53: Permission is granted to make and distribute verbatim copies of
        !            54: this manual provided the copyright notice and this permission notice
        !            55: are preserved on all copies.
        !            56: 
        !            57: Permission is granted to copy and distribute modified versions of this
        !            58: manual under the conditions for verbatim copying, provided that the entire
        !            59: resulting derived work is distributed under the terms of a permission
        !            60: notice identical to this one.
        !            61: 
        !            62: Permission is granted to copy and distribute translations of this manual
        !            63: into another language, under the above conditions for modified versions,
        !            64: except that this permission notice may be stated in a translation approved
        !            65: by the Foundation.
        !            66: @end titlepage
        !            67: @page
        !            68: 
        !            69: @synindex vr fn
        !            70: 
        !            71: @node Top, Introduction, (DIR), (DIR)
        !            72: 
        !            73: @menu
        !            74: * Introduction::What is termcap?  Why this manual?
        !            75: * Library::     The termcap library functions.
        !            76: * Data Base::   What terminal descriptions in @file{/etc/termcap} look like.
        !            77: * Capabilities::Definitions of the individual terminal capabilities:
        !            78:                  how to write them in descriptions, and how to use
        !            79:                  their values to do display updating.
        !            80: * Summary::    Brief table of capability names and their meanings.
        !            81: * Var Index::   Index of C functions and variables.
        !            82: * Cap Index::   Index of termcap capabilities.
        !            83: * Index::       Concept index.
        !            84: @end menu
        !            85: 
        !            86: @node Introduction, Library, Top, Top
        !            87: @unnumbered Introduction
        !            88: 
        !            89: @cindex termcap
        !            90: @dfn{Termcap} is a library and data base that enables programs to use
        !            91: display terminals in a terminal-independent manner.  It originated in
        !            92: Berkeley Unix.
        !            93: 
        !            94: The termcap data base describes the capabilities of hundreds of different
        !            95: display terminals in great detail.  Some examples of the information
        !            96: recorded for a terminal could include how many columns wide it is, what
        !            97: string to send to move the cursor to an arbitrary position (including how
        !            98: to encode the row and column numbers), how to scroll the screen up one or
        !            99: several lines, and how much padding is needed for such a scrolling
        !           100: operation.
        !           101: 
        !           102: The termcap library is provided for easy access this data base in programs
        !           103: that want to do terminal-independent character-based display output.
        !           104: 
        !           105: This manual describes the GNU version of the termcap library, which has
        !           106: some extensions over the Unix version.  All the extensions are identified
        !           107: as such, so this manual also tells you how to use the Unix termcap.
        !           108: 
        !           109: The GNU version of the termcap library is available free as source code,
        !           110: for use in free programs, and runs on Unix and VMS systems (at least).  You
        !           111: can find it in the GNU Emacs distribution in the files @file{termcap.c} and
        !           112: @file{tparam.c}.
        !           113: 
        !           114: This manual was written for the GNU project, whose goal is to develop a
        !           115: complete free operating system upward-compatible with Unix for user
        !           116: programs.  The project is approximately two thirds complete.  For more
        !           117: information on the GNU project, including the GNU Emacs editor and the
        !           118: mostly-portable optimizing C compiler, send one dollar to
        !           119: 
        !           120: @display
        !           121: Free Software Foundation
        !           122: 675 Mass Ave
        !           123: Cambridge, MA 02139
        !           124: @end display
        !           125: 
        !           126: @node Library, Data Base, Introduction, Top
        !           127: @chapter The Termcap Library
        !           128: 
        !           129: The termcap library is the application programmer's interface to the
        !           130: termcap data base.  It contains functions for the following purposes:
        !           131: 
        !           132: @itemize @bullet
        !           133: @item
        !           134: Finding the description of the user's terminal type (@code{tgetent}).
        !           135: 
        !           136: @item
        !           137: Interrogating the description for information on various topics
        !           138: (@code{tgetnum}, @code{tgetflag}, @code{tgetstr}).
        !           139: 
        !           140: @item
        !           141: Computing and performing padding (@code{tputs}).
        !           142: 
        !           143: @item
        !           144: Encoding numeric parameters such as cursor positions into the
        !           145: terminal-specific form required for display commands (@code{tparam},
        !           146: @code{tgoto}).
        !           147: @end itemize
        !           148: 
        !           149: @menu
        !           150: * Preparation:: Preparing to use the termcap library.
        !           151: * Find::        Finding the description of the terminal being used.
        !           152: * Interrogate:: Interrogating the description for particular capabilities.
        !           153: * Initialize::  Initialization for output using termcap.
        !           154: * Padding::     Outputting padding.
        !           155: * Parameters::  Encoding parameters such as cursor positions.
        !           156: @end menu
        !           157: 
        !           158: @node Preparation, Find, Library, Library
        !           159: @section Preparing to Use the Termcap Library
        !           160: 
        !           161: To use the termcap library in a program, you need two kinds of preparation:
        !           162: 
        !           163: @itemize @bullet
        !           164: @item
        !           165: The compiler needs declarations of the functions and variables in the
        !           166: library.
        !           167: 
        !           168: On GNU systems, it suffices to include the header file
        !           169: @file{termcap.h} in each source file that uses these functions and
        !           170: variables.@refill
        !           171: 
        !           172: On Unix systems, there is often no such header file.  Then you must
        !           173: explictly declare the variables as external.  You can do likewise for
        !           174: the functions, or let them be implicitly declared and cast their
        !           175: values from type @code{int} to the appropriate type.
        !           176: 
        !           177: We illustrate the declarations of the individual termcap library
        !           178: functions with ANSI C prototypes because they show how to pass the
        !           179: arguments.  If you are not using the GNU C compiler, you probably
        !           180: cannot use function prototypes, so omit the argument types and names
        !           181: from your declarations.
        !           182: 
        !           183: @item
        !           184: The linker needs to search the library.  Usually either
        !           185: @samp{-ltermcap} or @samp{-ltermlib} as an argument when linking will
        !           186: do this.@refill
        !           187: @end itemize
        !           188: 
        !           189: @node Find, Interrogate, Preparation, Library
        !           190: @section Finding a Terminal Description: @code{tgetent}
        !           191: 
        !           192: @findex tgetent
        !           193: An application program that is going to use termcap must first look up the
        !           194: description of the terminal type in use.  This is done by calling
        !           195: @code{tgetent}, whose declaration in ANSI Standard C looks like:
        !           196: 
        !           197: @example
        !           198: int tgetent (char *@var{buffer}, char *@var{termtype});
        !           199: @end example
        !           200: 
        !           201: @noindent
        !           202: This function finds the description and remembers it internally so that
        !           203: you can interrogate it about specific terminal capabilities
        !           204: (@pxref{Interrogate}).
        !           205: 
        !           206: The argument @var{termtype} is a string which is the name for the type of
        !           207: terminal to look up.  Usually you would obtain this from the environment
        !           208: variable @code{TERM} using @code{getenv ("TERM")}.
        !           209: 
        !           210: If you are using the GNU version of termcap, you can alternatively ask
        !           211: @code{tgetent} to allocate enough space.  Pass a null pointer for
        !           212: @var{buffer}, and @code{tgetent} itself allocates the storage using
        !           213: @code{malloc}.  In this case the returned value on success is the address
        !           214: of the storage, cast to @code{int}.  But normally there is no need for you
        !           215: to look at the address.  Do not free the storage yourself.@refill
        !           216: 
        !           217: With the Unix version of termcap, you must allocate space for the
        !           218: description yourself and pass the address of the space as the argument
        !           219: @var{buffer}.  There is no way you can tell how much space is needed, so
        !           220: the convention is to allocate a buffer 2048 characters long and assume that
        !           221: is enough.  (Formerly the convention was to allocate 1024 characters and
        !           222: assume that was enough.  But one day, for one kind of terminal, that was
        !           223: not enough.)
        !           224: 
        !           225: No matter how the space to store the description has been obtained,
        !           226: termcap records its address internally for use when you later interrogate
        !           227: the description with @code{tgetnum}, @code{tgetstr} or @code{tgetflag}.  If
        !           228: the buffer was allocated by termcap, it will be freed by termcap too if you
        !           229: call @code{tgetent} again.  If the buffer was provided by you, you must
        !           230: make sure that its contents remain unchanged for as long as you still plan
        !           231: to interrogate the description.@refill
        !           232: 
        !           233: The return value of @code{tgetent} is @minus{}1 if there is some difficulty
        !           234: accessing the data base of terminal types, 0 if the data base is accessible
        !           235: but the specified type is not defined in it, and some other value
        !           236: otherwise.
        !           237: 
        !           238: Here is how you might use the function @code{tgetent}:
        !           239: 
        !           240: @example
        !           241: #ifdef unix
        !           242: static char term_buffer[2048];
        !           243: #else
        !           244: #define term_buffer 0
        !           245: #endif
        !           246: 
        !           247: init_terminal_data ()
        !           248: @{
        !           249:   char *termtype = getenv ("TERM");
        !           250:   int success;
        !           251: 
        !           252:   if (termtype == 0)
        !           253:     fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");
        !           254: 
        !           255:   success = tgetent (term_buffer, termtype);
        !           256:   if (success < 0)
        !           257:     fatal ("Could not access the termcap data base.\n");
        !           258:   if (success == 0)
        !           259:     fatal ("Terminal type `%s' is not defined.\n", termtype);
        !           260: @}
        !           261: @end example
        !           262: 
        !           263: @noindent
        !           264: Here we assume the function @code{fatal} prints an error message and exits.
        !           265: 
        !           266: If the environment variable @code{TERMCAP} is defined, its value is used to
        !           267: override the terminal type data base.  The function @code{tgetent} checks
        !           268: the value of @code{TERMCAP} automatically.  If the value starts with
        !           269: @samp{/} then it is taken as a file name to use as the data base file,
        !           270: instead of @file{/etc/termcap} which is the standard data base.  If the
        !           271: value does not start with @samp{/} then it is itself used as the terminal
        !           272: description, provided that the terminal type @var{termtype} is among the
        !           273: types it claims to apply to.  @xref{Data Base}, for information on the
        !           274: format of a terminal description.@refill
        !           275: 
        !           276: @node Interrogate, Initialize, Find, Library
        !           277: @section Interrogating the Terminal Description
        !           278: 
        !           279: Each piece of information recorded in a terminal description is called a
        !           280: @dfn{capability}.  Each defined terminal capability has a two-letter code
        !           281: name and a specific meaning.  For example, the number of columns is named
        !           282: @samp{co}.  @xref{Capabilities}, for definitions of all the standard
        !           283: capability names.
        !           284: 
        !           285: Once you have found the proper terminal description with @code{tgetent}
        !           286: (@pxref{Find}), your application program must @dfn{interrogate} it for
        !           287: various terminal capabilities.  You must specify the two-letter code of
        !           288: the capability whose value you seek.
        !           289: 
        !           290: Capability values can be numeric, boolean (capability is either present or
        !           291: absent) or strings.  Any particular capability always has the same value
        !           292: type; for example, @samp{co} always has a numeric value, while @samp{am}
        !           293: (automatic wrap at margin) is always a flag, and @samp{cm} (cursor motion
        !           294: command) always has a string value.  The documentation of each capability
        !           295: says which type of value it has.@refill
        !           296: 
        !           297: There are three functions to use to get the value of a capability,
        !           298: depending on the type of value the capability has.  Here are their
        !           299: declarations in ANSI C:
        !           300: 
        !           301: @findex tgetnum
        !           302: @findex tgetflag
        !           303: @findex tgetstr
        !           304: @example
        !           305: int tgetnum (char *@var{name});
        !           306: int tgetflag (char *@var{name});
        !           307: char *tgetstr (char *@var{name}, char **@var{area});
        !           308: @end example
        !           309: 
        !           310: @table @code
        !           311: @item tgetnum
        !           312: Use @code{tgetnum} to get a capability value that is numeric.  The
        !           313: argument @var{name} is the two-letter code name of the capability.  If
        !           314: the capability is present, @code{tgetnum} returns the numeric value
        !           315: (which is nonnegative).  If the capability is not mentioned in the
        !           316: terminal description, @code{tgetnum} returns @minus{}1.
        !           317: 
        !           318: @item tgetflag
        !           319: Use @code{tgetflag} to get a boolean value.  If the capability
        !           320: @var{name} is present in the terminal description, @code{tgetflag}
        !           321: returns 1; otherwise, it returns 0.
        !           322: 
        !           323: @item tgetstr
        !           324: Use @code{tgetstr} to get a string value.  It returns a pointer to a
        !           325: string which is the capability value, or a null pointer if the
        !           326: capability is not present in the terminal description.
        !           327: 
        !           328: There are two ways @code{tgetstr} can find space to store the string value:
        !           329: 
        !           330: @itemize @bullet
        !           331: @item
        !           332: You can ask @code{tgetstr} to allocate the space.  Pass a null
        !           333: pointer for the argument @var{area}, and @code{tgetstr} will use
        !           334: @code{malloc} to allocate storage big enough for the value.
        !           335: Termcap will never free this storage or refer to it again; you
        !           336: should free it when you are finished with it.
        !           337: 
        !           338: This method is more robust, since there is no need to guess how
        !           339: much space is needed.  But it is supported only by the GNU
        !           340: termcap library.
        !           341: 
        !           342: @item
        !           343: You can provide the space.  Provide for the argument @var{area} the
        !           344: address of a pointer variable of type @code{char *}.  Before calling
        !           345: @code{tgetstr}, initialize the variable to point at available space.
        !           346: Then @code{tgetstr} will store the string value in that space and will
        !           347: increment the pointer variable to point after the space that has been
        !           348: used.  You can use the same pointer variable for many calls to
        !           349: @code{tgetstr}.
        !           350: 
        !           351: There is no way to determine how much space is needed for a single
        !           352: string, and no way for you to prevent or handle overflow of the area
        !           353: you have provided.  However, you can be sure that the total size of
        !           354: all the string values you will obtain from the terminal description is
        !           355: no greater than the size of the description (unless you get the same
        !           356: capability twice).  You can determine that size with @code{strlen} on
        !           357: the buffer you provided to @code{tgetent}.  See below for an example.
        !           358: 
        !           359: Providing the space yourself is the only method supported by the Unix
        !           360: version of termcap.
        !           361: @end itemize
        !           362: @end table
        !           363: 
        !           364: Note that you do not have to specify a terminal type or terminal
        !           365: description for the interrogation functions.  They automatically use the
        !           366: description found by the most recent call to @code{tgetent}.
        !           367: 
        !           368: Here is an example of interrogating a terminal description for various
        !           369: capabilities, with conditionals to select between the Unix and GNU methods
        !           370: of providing buffer space.
        !           371: 
        !           372: @example
        !           373: char *tgetstr ();
        !           374: 
        !           375: char *cl_string, *cm_string;
        !           376: int height;
        !           377: int width;
        !           378: int auto_wrap;
        !           379: 
        !           380: char PC;   /* For tputs.  */
        !           381: char *BC;  /* For tgoto.  */
        !           382: char *UP;
        !           383: 
        !           384: interrogate_terminal ()
        !           385: @{
        !           386: #ifdef UNIX
        !           387:   /* Here we assume that an explicit term_buffer
        !           388:      was provided to tgetent.  */
        !           389:   char *buffer
        !           390:     = (char *) malloc (strlen (term_buffer));
        !           391: #define BUFFADDR &buffer
        !           392: #else
        !           393: #define BUFFADDR 0
        !           394: #endif
        !           395: 
        !           396:   char *temp;
        !           397: 
        !           398:   /* Extract information we will use.  */
        !           399:   cl_string = tgetstr ("cl", BUFFADDR);
        !           400:   cm_string = tgetstr ("cm", BUFFADDR);
        !           401:   auto_wrap = tgetflag ("am");
        !           402:   height = tgetnum ("li");
        !           403:   width = tgetnum ("co");
        !           404: 
        !           405:   /* Extract information that termcap functions use.  */
        !           406:   temp = tgetstr ("pc", BUFFADDR);
        !           407:   PC = temp ? *temp : 0;
        !           408:   BC = tgetstr ("le", BUFFADDR);
        !           409:   UP = tgetstr ("up", BUFFADDR);
        !           410: @}
        !           411: @end example
        !           412: 
        !           413: @noindent
        !           414: @xref{Padding}, for information on the variable @code{PC}.  @xref{Using
        !           415: Parameters}, for information on @code{UP} and @code{BC}.
        !           416: 
        !           417: @node Initialize, Padding, Interrogate, Library
        !           418: @section Initialization for Use of Termcap
        !           419: @cindex terminal flags (kernel)
        !           420: 
        !           421: Before starting to output commands to a terminal using termcap,
        !           422: an application program should do two things:
        !           423: 
        !           424: @itemize @bullet
        !           425: @item
        !           426: Initialize various global variables which termcap library output
        !           427: functions refer to.  These include @code{PC} and @code{ospeed} for
        !           428: padding (@pxref{Output Padding}) and @code{UP} and @code{BC} for
        !           429: cursor motion (@pxref{tgoto}).@refill
        !           430: 
        !           431: @item
        !           432: Tell the kernel to turn off alteration and padding of horizontal-tab
        !           433: characters sent to the terminal.
        !           434: @end itemize
        !           435: 
        !           436: To turn off output processing in Berkeley Unix you would use @code{ioctl}
        !           437: with code @code{TIOCLSET} to set the bit named @code{LLITOUT}, and clear
        !           438: the bits @code{ANYDELAY} using @code{TIOCSETN}.  In POSIX or System V, you
        !           439: must clear the bit named @code{OPOST}.  Refer to the system documentation
        !           440: for details.@refill
        !           441: 
        !           442: If you do not set the terminal flags properly, some older terminals will
        !           443: not work.  This is because their commands may contain the characters that
        !           444: normally signify newline, carriage return and horizontal tab---characters
        !           445: which the kernel thinks it ought to modify before output.
        !           446: 
        !           447: When you change the kernel's terminal flags, you must arrange to restore
        !           448: them to their normal state when your program exits.  This implies that the
        !           449: program must catch fatal signals such as @code{SIGQUIT} and @code{SIGINT}
        !           450: and restore the old terminal flags before actually terminating.
        !           451: 
        !           452: Modern terminals' commands do not use these special characters, so if you
        !           453: do not care about problems with old terminals, you can leave the kernel's
        !           454: terminal flags unaltered.
        !           455: 
        !           456: @node Padding, Parameters, Initialize, Library
        !           457: @section Padding
        !           458: @cindex padding
        !           459: 
        !           460: @dfn{Padding} means outputting null characters following a terminal display
        !           461: command that takes a long time to execute.  The terminal description says
        !           462: which commands require padding and how much; the function @code{tputs},
        !           463: described below, outputs a terminal command while extracting from it the
        !           464: padding information, and then outputs the padding that is necessary.
        !           465: 
        !           466: @menu
        !           467: * Why Pad::          Explanation of padding.
        !           468: * Describe Padding:: The data base says how much padding a terminal needs.
        !           469: * Output Padding::   Using @code{tputs} to output the needed padding.
        !           470: @end menu
        !           471: 
        !           472: @node Why Pad, Describe Padding, Padding, Padding
        !           473: @subsection Why Pad, and How
        !           474: 
        !           475: Most types of terminal have commands that take longer to execute than they
        !           476: do to send over a high-speed line.  For example, clearing the screen may
        !           477: take 20msec once the entire command is received.  During that time, on a
        !           478: 9600 bps line, the terminal could receive about 20 additional output
        !           479: characters while still busy clearing the screen.  Every terminal has a
        !           480: certain amount of buffering capacity to remember output characters that
        !           481: cannot be processed yet, but too many slow commands in a row can cause the
        !           482: buffer to fill up.  Then any additional output that cannot be processed
        !           483: immediately will be lost.
        !           484: 
        !           485: To avoid this problem, we normally follow each display command with enough
        !           486: useless charaters (usually null characters) to fill up the time that the
        !           487: display command needs to execute.  This does the job if the terminal throws
        !           488: away null characters without using up space in the buffer (which most
        !           489: terminals do).  If enough padding is used, no output can ever be lost.  The
        !           490: right amount of padding avoids loss of output without slowing down
        !           491: operation, since the time used to transmit padding is time that nothing
        !           492: else could be done.
        !           493: 
        !           494: The number of padding characters needed for an operation depends on the
        !           495: line speed.  In fact, it is proportional to the line speed.  A 9600 baud
        !           496: line transmits about one character per msec, so the clear screen command in
        !           497: the example above would need about 20 characters of padding.  At 1200 baud,
        !           498: however, only about 3 characters of padding are needed to fill up 20msec.
        !           499: 
        !           500: @node Describe Padding, Output Padding, Why Pad, Padding
        !           501: @subsection Specifying Padding in a Terminal Description
        !           502: 
        !           503: In the terminal description, the amount of padding required by each display
        !           504: command is recorded as a sequence of digits at the front of the command.
        !           505: These digits specify the padding time in msec.  They can be followed
        !           506: optionally by a decimal point and one more digit, which is a number of
        !           507: tenths of msec.
        !           508: 
        !           509: Sometimes the padding needed by a command depends on the cursor position.
        !           510: For example, the time taken by an ``insert line'' command is usually
        !           511: proportional to the number of lines that need to be moved down or cleared.
        !           512: An asterisk (@samp{*}) following the padding time says that the time
        !           513: should be multiplied by the number of screen lines affected by the command.
        !           514: 
        !           515: @example
        !           516: :al=1.3*\E[L:
        !           517: @end example
        !           518: 
        !           519: @noindent
        !           520: is used to describe the ``insert line'' command for a certain terminal.
        !           521: The padding required is 1.3 msec per line affected.  The command itself is
        !           522: @samp{@key{ESC} [ L}.
        !           523: 
        !           524: The padding time specified in this way tells @code{tputs} how many pad
        !           525: characters to output.  @xref{Output Padding}.
        !           526: 
        !           527: Two special capability values affect padding for all commands.  These are
        !           528: the @samp{pc} and @samp{pb}.  The variable @samp{pc} specifies the
        !           529: character to pad with, and @samp{pb} the speed below which no padding is
        !           530: needed.  The defaults for these variables, a null character and 0,
        !           531: are correct for most terminals.  @xref{Pad Specs}.
        !           532: 
        !           533: @node Output Padding,, Describe Padding, Padding
        !           534: @subsection Performing Padding with @code{tputs}
        !           535: @cindex line speed
        !           536: 
        !           537: @findex tputs
        !           538: Use the termcap function @code{tputs} to output a string containing an
        !           539: optional padding spec of the form described above (@pxref{Describe
        !           540: Padding}).  The function @code{tputs} strips off and decodes the padding
        !           541: spec, outputs the rest of the string, and then outputs the appropriate
        !           542: padding.  Here is its declaration in ANSI C:
        !           543: 
        !           544: @example
        !           545: char PC;
        !           546: short ospeed;
        !           547: 
        !           548: int tputs (char *@var{string}, int @var{nlines}, int (*@var{outfun}) ());
        !           549: @end example
        !           550: 
        !           551: Here @var{string} is the string (including padding spec) to be output;
        !           552: @var{nlines} is the number of lines affected by the operation, which is
        !           553: used to multiply the amount of padding if the padding spec ends with a
        !           554: @samp{*}.  Finally, @var{outfun} is a function (such as @code{fputchar})
        !           555: that is called to output each character.  When actually called,
        !           556: @var{outfun} should expect one argument, a character.
        !           557: 
        !           558: @vindex ospeed
        !           559: @vindex PC
        !           560: The operation of @code{tputs} is controlled by two global variables,
        !           561: @code{ospeed} and @code{PC}.  The value of @code{ospeed} is supposed to be
        !           562: the terminal output speed, encoded as in the @code{ioctl} system call which
        !           563: gets the speed information.  This is needed to compute the number of
        !           564: padding characters.  The value of @code{PC} is the character used for
        !           565: padding.
        !           566: 
        !           567: You are responsible for storing suitable values into these variables before
        !           568: using @code{tputs}.  The value stored into the @code{PC} variable should be
        !           569: taken from the @samp{pc} capability in the terminal description (@pxref{Pad
        !           570: Specs}).  Store zero in @code{PC} if there is no @samp{pc}
        !           571: capability.@refill
        !           572: 
        !           573: The argument @var{nlines} requires some thought.  Normally, it should be
        !           574: the number of lines whose contents will be cleared or moved by the command.
        !           575: For cursor motion commands, or commands that do editing within one line,
        !           576: use the value 1.  For most commands that affect multiple lines, such as
        !           577: @samp{al} (insert a line) and @samp{cd} (clear from the cursor to the end
        !           578: of the screen), @var{nlines} should be the screen height minus the current
        !           579: vertical position (origin 0).  For multiple insert and scroll commands such
        !           580: as @samp{AL} (insert multiple lines), that same value for @var{nlines} is
        !           581: correct; the number of lines being inserted is @i{not} correct.@refill
        !           582: 
        !           583: If a ``scroll window'' feature is used to reduce the number of lines
        !           584: affected by a command, the value of @var{nlines} should take this into
        !           585: account.  This is because the delay time required depends on how much work
        !           586: the terminal has to do, and the scroll window feature reduces the work.
        !           587: @xref{Scrolling}.
        !           588: 
        !           589: Commands such as @samp{ic} and @samp{dc} (insert or delete characters) are
        !           590: problematical because the padding needed by these commands is proportional
        !           591: to the number of characters affected, which is the number of columns from
        !           592: the cursor to the end of the line.  It would be nice to have a way to
        !           593: specify such a dependence, and there is no need for dependence on vertical
        !           594: position in these commands, so it is an obvious idea to say that for these
        !           595: commands @var{nlines} should really be the number of columns affected.
        !           596: However, the definition of termcap clearly says that @var{nlines} is always
        !           597: the number of lines affected, even in this case, where it is always 1.  It
        !           598: is not easy to change this rule now, because too many programs and terminal
        !           599: descriptions have been written to follow it.
        !           600: 
        !           601: Because @var{nlines} is always 1 for the @samp{ic} and @samp{dc} strings,
        !           602: there is no reason for them to use @samp{*}, but some of them do.  These
        !           603: should be corrected by deleting the @samp{*}.  If, some day, such entries
        !           604: have disappeared, it may be possible to change to a more useful convention
        !           605: for the @var{nlines} argument for these operations without breaking any
        !           606: programs.
        !           607: 
        !           608: @node Parameters,, Padding, Library
        !           609: @section Filling In Parameters
        !           610: @cindex parameters
        !           611: 
        !           612: Some terminal control strings require numeric @dfn{parameters}.  For
        !           613: example, when you move the cursor, you need to say what horizontal and
        !           614: vertical positions to move it to.  The value of the terminal's @samp{cm}
        !           615: capability, which says how to move the cursor, cannot simply be a string of
        !           616: characters; it must say how to express the cursor position numbers and
        !           617: where to put them within the command.
        !           618: 
        !           619: The specifications of termcap include conventions as to which string-valued
        !           620: capabilities require parameters, how many parameters, and what the
        !           621: parameters mean; for example, it defines the @samp{cm} string to take
        !           622: two parameters, the vertical and horizontal positions, with 0,0 being the
        !           623: upper left corner.  These conventions are described where the individual
        !           624: commands are documented.
        !           625: 
        !           626: Termcap also defines a language used within the capability definition for
        !           627: specifying how and where to encode the parameters for output.  This language
        !           628: uses character sequences starting with @samp{%}.  (This is the same idea as
        !           629: @code{printf}, but the details are different.)  The language for parameter
        !           630: encoding is described in this section.
        !           631: 
        !           632: A program that is doing display output calls the functions @code{tparam} or
        !           633: @code{tgoto} to encode parameters according to the specifications.  These
        !           634: functions produce a string containing the actual commands to be output (as
        !           635: well a padding spec which must be processed with @code{tputs};
        !           636: @pxref{Padding}).
        !           637: 
        !           638: @menu
        !           639: * Encode Parameters:: The language for encoding parameters.
        !           640: * Using Parameters::  Outputting a string command with parameters.
        !           641: @end menu
        !           642: 
        !           643: @node Encode Parameters, Using Parameters, Parameters, Parameters
        !           644: @subsection Describing the Encoding
        !           645: @cindex %
        !           646: 
        !           647: A terminal command string that requires parameters contains special
        !           648: character sequences starting with @samp{%} to say how to encode the
        !           649: parameters.  These sequences control the actions of @code{tparam} and
        !           650: @code{tgoto}.
        !           651: 
        !           652: The parameters values passed to @code{tparam} or @code{tgoto} are
        !           653: considered to form a vector.  A pointer into this vector determines
        !           654: the next parameter to be processed.  Some of the @samp{%}-sequences
        !           655: encode one parameter and advance the pointer to the next parameter.
        !           656: Other @samp{%}-sequences alter the pointer or alter the parameter
        !           657: values without generating output.
        !           658: 
        !           659: For example, the @samp{cm} string for a standard ANSI terminal is written
        !           660: as @samp{\E[%i%d;%dH}.  (@samp{\E} stands for @key{ESC}.)  @samp{cm} by
        !           661: convention always requires two parameters, the vertical and horizontal goal
        !           662: positions, so this string specifies the encoding of two parameters.  Here
        !           663: @samp{%i} increments the two values supplied, and each @samp{%d} encodes
        !           664: one of the values in decimal.  If the cursor position values 20,58 are
        !           665: encoded with this string, the result is @samp{\E[21;59H}.
        !           666: 
        !           667: First, here are the @samp{%}-sequences that generate output.  Except for
        !           668: @samp{%%}, each of them encodes one parameter and advances the pointer
        !           669: to the following parameter.
        !           670: 
        !           671: @table @samp
        !           672: @item %%
        !           673: Output a single @samp{%}.  This is the only way to represent a literal
        !           674: @samp{%} in a terminal command with parameters.  @samp{%%} does not
        !           675: use up a parameter.
        !           676: 
        !           677: @item %d
        !           678: As in @code{printf}, output the next parameter in decimal.
        !           679: 
        !           680: @item %2
        !           681: Like @samp{%02d} in @code{printf}: output the next parameter in
        !           682: decimal, and always use at least two digits.
        !           683: 
        !           684: @item %3
        !           685: Like @samp{%03d} in @code{printf}: output the next parameter in
        !           686: decimal, and always use at least three digits.  Note that @samp{%4}
        !           687: and so on are @emph{not} defined.
        !           688: 
        !           689: @item %.
        !           690: Output the next parameter as a single character whose ASCII code is
        !           691: the parameter value.  Like @samp{%c} in @code{printf}.
        !           692: 
        !           693: @item %+@var{char}
        !           694: Add the next parameter to the character @var{char}, and output the
        !           695: resulting character.  For example, @samp{%+ } represents 0 as a space,
        !           696: 1 as @samp{!}, etc.
        !           697: @end table
        !           698: 
        !           699: The following @samp{%}-sequences specify alteration of the parameters
        !           700: (their values, or their order) rather than encoding a parameter for output.
        !           701: They generate no output; they are used only for their side effects
        !           702: on the parameters.  Also, they do not advance the ``next parameter'' pointer
        !           703: except as explicitly stated.  Only @samp{%i}, @samp{%r} and @samp{%>} are
        !           704: defined in standard Unix termcap.  The others are GNU extensions.@refill
        !           705: 
        !           706: @table @samp
        !           707: @item %i
        !           708: Increment the next two parameters.  This is used for terminals that
        !           709: expect cursor positions in origin 1.  For example, @samp{%i%d,%d} would
        !           710: output two parameters with @samp{1} for 0, @samp{2} for 1, etc.
        !           711: 
        !           712: @item %r
        !           713: Interchange the next two parameters.  This is used for terminals whose
        !           714: cursor positioning command expects the horizontal position first.
        !           715: 
        !           716: @item %s
        !           717: Skip the next parameter.  Do not output anything.
        !           718: 
        !           719: @item %b
        !           720: Back up one parameter.  The last parameter used will become once again
        !           721: the next parameter to be output, and the next output command will use
        !           722: it.  Using @samp{%b} more than once, you can back up any number of
        !           723: parameters, and you can refer to each parameter any number of times.
        !           724: 
        !           725: @item %>@var{c1}@var{c2}
        !           726: Conditionally increment the next parameter.  Here @var{c1} and
        !           727: @var{c2} are characters which stand for their ASCII codes as numbers.
        !           728: If the next parameter is greater than the ASCII code of @var{c1}, the
        !           729: ASCII code of @var{c2} is added to it.@refill
        !           730: 
        !           731: @item %a @var{op} @var{type} @var{pos}
        !           732: Perform arithmetic on the next parameter, do not use it up, and do not
        !           733: output anything.  Here @var{op} specifies the arithmetic operation,
        !           734: while @var{type} and @var{pos} together specify the other operand.
        !           735: 
        !           736: Spaces are used above to separate the operands for clarity; the spaces
        !           737: don't appear in the data base, where this sequence is exactly five
        !           738: characters long.
        !           739: 
        !           740: The character @var{op} says what kind of arithmetic operation to
        !           741: perform.  It can be any of these characters:
        !           742: 
        !           743: @table @samp
        !           744: @item =
        !           745: assign a value to the next parameter, ignoring its old value.
        !           746: The new value comes from the other operand.
        !           747: 
        !           748: @item +
        !           749: add the other operand to the next parameter.
        !           750: 
        !           751: @item -
        !           752: subtract the other operand from the next parameter.
        !           753: 
        !           754: @item *
        !           755: multiply the next parameter by the other operand.
        !           756: 
        !           757: @item /
        !           758: divide the next parameter by the other operand.
        !           759: @end table
        !           760: 
        !           761: The ``other operand'' may be another parameter's value or a constant;
        !           762: the character @var{type} says which.  It can be:
        !           763: 
        !           764: @table @samp
        !           765: @item p
        !           766: Use another parameter.  The character @var{pos} says which
        !           767: parameter to use.  Subtract 64 from its ASCII code to get the
        !           768: position of the desired parameter relative to this one.  Thus,
        !           769: the character @samp{A} as @var{pos} means the parameter after the
        !           770: next one; the character @samp{?} means the parameter before the
        !           771: next one.
        !           772: 
        !           773: @item c
        !           774: Use a constant value.  The character @var{pos} specifies the
        !           775: value of the constant.  The 0200 bit is cleared out, so that 0200
        !           776: can be used to represent zero.
        !           777: @end table
        !           778: @end table
        !           779: 
        !           780: The following @samp{%}-sequences are special purpose hacks to compensate
        !           781: for the weird designs of obscure terminals.  They modify the next parameter
        !           782: or the next two parameters but do not generate output and do not use up any
        !           783: parameters.  @samp{%m} is a GNU extension; the others are defined in
        !           784: standard Unix termcap.
        !           785: 
        !           786: @table @samp
        !           787: @item %n
        !           788: Exclusive-or the next parameter with 0140, and likewise the parameter
        !           789: after next.
        !           790: 
        !           791: @item %m
        !           792: Complement all the bits of the next parameter and the parameter after next.
        !           793: 
        !           794: @item %B
        !           795: Encode the next parameter in BCD.  It alters the value of the
        !           796: parameter by adding six times the quotient of the parameter by ten.
        !           797: Here is a C statement that shows how the new value is computed:
        !           798: 
        !           799: @example
        !           800: @var{parm} = (@var{parm} / 10) * 16 + @var{parm} % 10;
        !           801: @end example
        !           802: 
        !           803: @item %D
        !           804: Transform the next parameter as needed by Delta Data terminals.
        !           805: This involves subtracting twice the remainder of the parameter by 16.
        !           806: 
        !           807: @example
        !           808: @var{parm} -= 2 * (@var{parm} % 16);
        !           809: @end example
        !           810: @end table
        !           811: 
        !           812: @node Using Parameters,, Encode Parameters, Parameters
        !           813: @subsection Sending Display Commands with Parameters
        !           814: 
        !           815: The termcap library functions @code{tparam} and @code{tgoto} serve as the
        !           816: analog of @code{printf} for terminal string parameters.  The newer function
        !           817: @code{tparam} is a GNU extension, more general but missing from Unix
        !           818: termcap.  The original parameter-encoding function is @code{tgoto}, which
        !           819: is preferable for cursor motion.
        !           820: 
        !           821: @menu
        !           822: * tparam::   The general case, for GNU termcap only.
        !           823: * tgoto::    The special case of cursor motion.
        !           824: @end menu
        !           825: 
        !           826: @node tparam, tgoto, Using Parameters, Using Parameters
        !           827: @subsubsection @code{tparam}
        !           828: 
        !           829: @findex tparam
        !           830: The function @code{tparam} can encode display commands with any number of
        !           831: parameters and allows you to specify the buffer space.  It is the preferred
        !           832: function for encoding parameters for all but the @samp{cm} capability.  Its
        !           833: ANSI C declaration is as follows:
        !           834: 
        !           835: @example
        !           836: char *tparam (char *@var{ctlstring}, char *@var{buffer}, int @var{size}, int @var{parm1},...)
        !           837: @end example
        !           838: 
        !           839: The arguments are a control string @var{ctlstring} (the value of a terminal
        !           840: capability, presumably), an output buffer @var{buffer} and @var{size}, and
        !           841: any number of integer parameters to be encoded.  The effect of
        !           842: @code{tparam} is to copy the control string into the buffer, encoding
        !           843: parameters according to the @samp{%} sequences in the control string.
        !           844: 
        !           845: You describe the output buffer by its address, @var{buffer}, and its size
        !           846: in bytes, @var{size}.  If the buffer is not big enough for the data to be
        !           847: stored in it, @code{tparam} calls @code{malloc} to get a larger buffer.  In
        !           848: either case, @code{tparam} returns the address of the buffer it ultimately
        !           849: uses.  If the value equals @var{buffer}, your original buffer was used.
        !           850: Otherwise, a new buffer was allocated, and you must free it after you are
        !           851: done with printing the results.  If you pass zero for @var{size} and
        !           852: @var{buffer}, @code{tparam} always allocates the space with @code{malloc}.
        !           853: 
        !           854: All capabilities that require parameters also have the ability to specify
        !           855: padding, so you should use @code{tputs} to output the string produced by
        !           856: @code{tparam}.  @xref{Padding}.  Here is an example.
        !           857: 
        !           858: @example
        !           859: @{
        !           860:   char *buf;
        !           861:   char buffer[40];
        !           862: 
        !           863:   buf = tparam (command, buffer, 40, parm);
        !           864:   tputs (buf, 1, fputchar);
        !           865:   if (buf != buffer)
        !           866:     free (buf);
        !           867: @}
        !           868: @end example
        !           869: 
        !           870: If a parameter whose value is zero is encoded with @samp{%.}-style
        !           871: encoding, the result is a null character, which will confuse @code{tputs}.
        !           872: This would be a serious problem, but luckily @samp{%.} encoding is used
        !           873: only by a few old models of terminal, and only for the @samp{cm}
        !           874: capability.  To solve the problem, use @code{tgoto} rather than
        !           875: @code{tparam} to encode the @samp{cm} capability.@refill
        !           876: 
        !           877: @node tgoto,, tparam, Using Parameters
        !           878: @subsubsection @code{tgoto}
        !           879: 
        !           880: @findex tgoto
        !           881: The special case of cursor motion is handled by @code{tgoto}.  There
        !           882: are two reasons why you might choose to use @code{tgoto}:
        !           883: 
        !           884: @itemize @bullet
        !           885: @item
        !           886: For Unix compatibility, because Unix termcap does not have @code{tparam}.
        !           887: 
        !           888: @item
        !           889: For the @samp{cm} capability, since @code{tgoto} has a special feature
        !           890: to avoid problems with null characters, tabs and newlines on certain old
        !           891: terminal types that use @samp{%.} encoding for that capability.
        !           892: @end itemize
        !           893: 
        !           894: Here is how @code{tgoto} might be declared in ANSI C:
        !           895: 
        !           896: @example
        !           897: char *tgoto (char *@var{cstring}, int @var{hpos}, int @var{vpos})
        !           898: @end example
        !           899: 
        !           900: There are three arguments, the terminal description's @samp{cm} string and
        !           901: the two cursor position numbers; @code{tgoto} computes the parametrized
        !           902: string in an internal static buffer and returns the address of that buffer.
        !           903: The next time you use @code{tgoto} the same buffer will be reused.
        !           904: 
        !           905: @vindex UP
        !           906: @vindex BC
        !           907: Parameters encoded with @samp{%.} encoding can generate null characters,
        !           908: tabs or newlines.  These might cause trouble: the null character because
        !           909: @code{tputs} would think that was the end of the string, the tab because
        !           910: the kernel or other software might expand it into spaces, and the newline
        !           911: becaue the kernel might add a carriage-return, or padding characters
        !           912: normally used for a newline.  To prevent such problems, @code{tgoto} is
        !           913: careful to avoid these characters.  Here is how this works: if the target
        !           914: cursor position value is such as to cause a problem (that is to say, zero,
        !           915: nine or ten), @code{tgoto} increments it by one, then compensates by
        !           916: appending a string to move the cursor back or up one position.
        !           917: 
        !           918: The compensation strings to use for moving back or up are found in global
        !           919: variables named @code{BC} and @code{UP}.  These are actual external C
        !           920: variables with upper case names; they are declared @code{char *}.  It is up
        !           921: to you to store suitable values in them, normally obtained from the
        !           922: @samp{le} and @samp{up} terminal capabilities in the terminal description
        !           923: with @code{tgetstr}.  Alternatively, if these two variables are both zero,
        !           924: the feature of avoiding nulls, tabs and newlines is turned off.
        !           925: 
        !           926: It is safe to use @code{tgoto} for commands other than @samp{cm} only if
        !           927: you have stored zero in @code{BC} and @code{UP}.
        !           928: 
        !           929: Note that @code{tgoto} reverses the order of its operands: the horizontal
        !           930: position comes before the vertical position in the arguments to
        !           931: @code{tgoto}, even though the vertical position comes before the horizontal
        !           932: in the parameters of the @samp{cm} string.  If you use @code{tgoto} with a
        !           933: command such as @samp{AL} that takes one parameter, you must pass the
        !           934: parameter to @code{tgoto} as the ``vertical position''.@refill
        !           935: 
        !           936: @node Data Base, Capabilities, Library, Top
        !           937: @chapter The Format of the Data Base
        !           938: 
        !           939: The termcap data base of terminal descriptions is stored in the file
        !           940: @file{/etc/termcap}.  It contains terminal descriptions, blank lines, and
        !           941: comments.
        !           942: 
        !           943: A terminal description starts with one or more names for the terminal type.
        !           944: The information in the description is a series of @dfn{capability names}
        !           945: and values.  The capability names have standard meanings
        !           946: (@pxref{Capabilities}) and their values describe the terminal.
        !           947: 
        !           948: @menu
        !           949: * Format::            Overall format of a terminal description.
        !           950: * Capability Format:: Format of capabilities within a description.
        !           951: * Naming::            Naming conventions for terminal types.
        !           952: * Inheriting::        Inheriting part of a description from
        !           953:                         a related terminal type.
        !           954: @end menu
        !           955: 
        !           956: @node Format, Capability Format, Data Base, Data Base
        !           957: @section Terminal Description Format
        !           958: @cindex description format
        !           959: 
        !           960: Aside from comments (lines starting with @samp{#}, which are ignored), each
        !           961: nonblank line in the termcap data base is a terminal description.
        !           962: A terminal description is nominally a single line, but it can be split
        !           963: into multiple lines by inserting the two characters @samp{\ newline}.
        !           964: This sequence is ignored wherever it appears in a description.
        !           965: 
        !           966: The preferred way to split the description is between capabilities: insert
        !           967: the four characters @samp{: \ newline tab} immediately before any colon.
        !           968: This allows each sub-line to start with some indentation.  This works
        !           969: because, after the @samp{\ newline} are ignored, the result is @samp{: tab
        !           970: :}; the first colon ends the preceding capability and the second colon
        !           971: starts the next capability.  If you split with @samp{\ newline} alone, you
        !           972: may not add any indentation after them.
        !           973: 
        !           974: Here is a real example of a terminal description:
        !           975: 
        !           976: @example
        !           977: dw|vt52|DEC vt52:\
        !           978:         :cr=^M:do=^J:nl=^J:bl=^G:\
        !           979:         :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
        !           980:         :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        !           981:         :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
        !           982: @end example
        !           983: 
        !           984: Each terminal description begins with several names for the terminal type.
        !           985: The names are separated by @samp{|} characters, and a colon ends the last
        !           986: name.  The first name should be two characters long; it exists only for the
        !           987: sake of very old Unix systems and is never used in modern systems.  The
        !           988: last name should be a fully verbose name such as ``DEC vt52'' or ``Ann
        !           989: Arbor Ambassador with 48 lines''.  The other names should include whatever
        !           990: the user ought to be able to specify to get this terminal type, such as
        !           991: @samp{vt52} or @samp{aaa-48}.  @xref{Naming}, for information on how to
        !           992: choose terminal type names.
        !           993: 
        !           994: After the terminal type names come the terminal capabilities, separated by
        !           995: colons and with a colon after the last one.  Each capability has a
        !           996: two-letter name, such as @samp{cm} for ``cursor motion string'' or @samp{li}
        !           997: for ``number of display lines''.
        !           998: 
        !           999: @node Capability Format, Naming, Format, Data Base
        !          1000: @section Writing the Capabilities
        !          1001: 
        !          1002: There are three kinds of capabilities: flags, numbers, and strings.  Each
        !          1003: kind has its own way of being written in the description.  Each defined
        !          1004: capability has by convention a particular kind of value; for example,
        !          1005: @samp{li} always has a numeric value and @samp{cm} always a string value.
        !          1006: 
        !          1007: A flag capability is thought of as having a boolean value: the value is
        !          1008: true if the capability is present, false if not.  When the capability is
        !          1009: present, just write its name between two colons.
        !          1010: 
        !          1011: A numeric capability has a value which is a nonnegative number.  Write the
        !          1012: capability name, a @samp{#}, and the number, between two colons.  For
        !          1013: example, @samp{@dots{}:li#48:@dots{}} is how you specify the @samp{li}
        !          1014: capability for 48 lines.@refill
        !          1015: 
        !          1016: A string-valued capability has a value which is a sequence of characters.
        !          1017: Usually these are the characters used to perform some display operation.
        !          1018: Write the capability name, a @samp{=}, and the characters of the value,
        !          1019: between two colons.  For example, @samp{@dots{}:cm=\E[%i%d;%dH:@dots{}} is
        !          1020: how the cursor motion command for a standard ANSI terminal would be
        !          1021: specified.@refill
        !          1022: 
        !          1023: Special characters in the string value can be expressed using
        !          1024: @samp{\}-escape sequences as in C; in addition, @samp{\E} stands for
        !          1025: @key{ESC}.  @samp{^} is also a kind of escape character; @samp{^} followed
        !          1026: by @var{char} stands for the control-equivalent of @var{char}.  Thus,
        !          1027: @samp{^a} stands for the character control-a, just like @samp{\001}.
        !          1028: @samp{\} and @samp{^} themselves can be represented as @samp{\\} and
        !          1029: @samp{\^}.@refill
        !          1030: 
        !          1031: To include a colon in the string, you must write @samp{\072}.  You might
        !          1032: ask, ``Why can't @samp{\:} be used to represent a colon?''  The reason is
        !          1033: that the interrogation functions do not count slashes while looking for a
        !          1034: capability.  Even if @samp{:ce=ab\:cd:} were interpreted as giving the
        !          1035: @samp{ce} capability the value @samp{ab:cd}, it would also appear to define
        !          1036: @samp{cd} as a flag.
        !          1037: 
        !          1038: The string value will often contain digits at the front to specify padding
        !          1039: (@pxref{Padding}) and/or @samp{%}-sequences within to specify how to encode
        !          1040: parameters (@pxref{Parameters}).  Although these things are not to be
        !          1041: output literally to the terminal, they are considered part of the value of
        !          1042: the capability.  They are special only when the string value is processed
        !          1043: by @code{tputs}, @code{tparam} or @code{tgoto}.  By contrast, @samp{\} and
        !          1044: @samp{^} are considered part of the syntax for specifying the characters
        !          1045: in the string.
        !          1046: 
        !          1047: Let's look at the VT52 example again:
        !          1048: 
        !          1049: @example
        !          1050: dw|vt52|DEC vt52:\
        !          1051:         :cr=^M:do=^J:nl=^J:bl=^G:\
        !          1052:         :le=^H:bs:cd=\EJ:ce=\EK:cl=\EH\EJ:cm=\EY%+ %+ :co#80:li#24:\
        !          1053:         :nd=\EC:ta=^I:pt:sr=\EI:up=\EA:\
        !          1054:         :ku=\EA:kd=\EB:kr=\EC:kl=\ED:kb=^H:
        !          1055: @end example
        !          1056: 
        !          1057: Here we see the numeric-valued capabilities @samp{co} and @samp{li}, the
        !          1058: flags @samp{bs} and @samp{pt}, and many string-valued capabilities.  Most
        !          1059: of the strings start with @key{ESC} represented as @samp{\E}.  The rest
        !          1060: contain control characters represented using @samp{^}.  The meanings of the
        !          1061: individual capabilities are defined elsewhere (@pxref{Capabilities}).
        !          1062: 
        !          1063: @node Naming, Inheriting, Capability Format, Data Base
        !          1064: @section Terminal Type Name Conventions
        !          1065: @cindex names of terminal types
        !          1066: 
        !          1067: There are conventions for choosing names of terminal types.  For one thing,
        !          1068: all letters should be in lower case.  The terminal type for a terminal in
        !          1069: its most usual or most fundamental mode of operation should not have a
        !          1070: hyphen in it.
        !          1071: 
        !          1072: If the same terminal has other modes of operation which require
        !          1073: different terminal descriptions, these variant descriptions are given
        !          1074: names made by adding suffixes with hyphens.  Such alternate descriptions
        !          1075: are used for two reasons:
        !          1076: 
        !          1077: @itemize @bullet
        !          1078: @item
        !          1079: When the terminal has a switch that changes its behavior.  Since the
        !          1080: computer cannot tell how the switch is set, the user must tell the
        !          1081: computer by choosing the appropriate terminal type name.
        !          1082: 
        !          1083: @cindex wrapping
        !          1084: For example, the VT-100 has a setup flag that controls whether the
        !          1085: cursor wraps at the right margin.  If this flag is set to ``wrap'',
        !          1086: you must use the terminal type @samp{vt100-am}.  Otherwise you must
        !          1087: use @samp{vt100-nam}.  Plain @samp{vt100} is defined as a synonym for
        !          1088: either @samp{vt100-am} or @samp{vt100-nam} depending on the
        !          1089: preferences of the local site.@refill
        !          1090: 
        !          1091: The standard suffix @samp{-am} stands for ``automatic margins''.
        !          1092: 
        !          1093: @item
        !          1094: To give the user a choice in how to use the terminal.  This is done
        !          1095: when the terminal has a switch that the computer normally controls.
        !          1096: 
        !          1097: @cindex screen size
        !          1098: For example, the Ann Arbor Ambassador can be configured with many
        !          1099: screen sizes ranging from 20 to 60 lines.  Fewer lines make bigger
        !          1100: characters but more lines let you see more of what you are editing.
        !          1101: As a result, users have different preferences.  Therefore, termcap
        !          1102: provides terminal types for many screen sizes.  If you choose type
        !          1103: @samp{aaa-30}, the terminal will be configured to use 30 lines; if you
        !          1104: choose @samp{aaa-48}, 48 lines will be used, and so on.
        !          1105: @end itemize
        !          1106: 
        !          1107: Here is a list of standard suffixes and their conventional meanings:
        !          1108: 
        !          1109: @table @samp
        !          1110: @item -w
        !          1111: Short for ``wide''.  This is a mode that gives the terminal more
        !          1112: columns than usual.  This is normally a user option.
        !          1113: 
        !          1114: @item -am
        !          1115: ``Automatic margins''.  This is an alternate description for use when
        !          1116: the terminal's margin-wrap switch is on; it contains the @samp{am}
        !          1117: flag.  The implication is that normally the switch is off and the
        !          1118: usual description for the terminal says that the switch is off.
        !          1119: 
        !          1120: @item -nam
        !          1121: ``No automatic margins''.  The opposite of @samp{-am}, this names an
        !          1122: alternative description which lacks the @samp{am} flag.  This implies
        !          1123: that the terminal is normally operated with the margin-wrap switch
        !          1124: turned on, and the normal description of the terminal says so.
        !          1125: 
        !          1126: @item -na
        !          1127: ``No arrows''.  This terminal description initializes the terminal to
        !          1128: keep its arrow keys in local mode.  This is a user option.
        !          1129: 
        !          1130: @item -rv
        !          1131: ``Reverse video''.  This terminal description causes text output for
        !          1132: normal video to appear as reverse, and text output for reverse video
        !          1133: to come out as normal.  Often this description differs from the usual
        !          1134: one by interchanging the two strings which turn reverse video on and
        !          1135: off.@refill
        !          1136: 
        !          1137: This is a user option; you can choose either the ``reverse video''
        !          1138: variant terminal type or the normal terminal type, and termcap will
        !          1139: obey.
        !          1140: 
        !          1141: @item -s
        !          1142: ``Status''.  Says to enable use of a status line which ordinary output
        !          1143: does not touch (@pxref{Status Line}).
        !          1144: 
        !          1145: Some terminals have a special line that is used only as a status line.
        !          1146: For these terminals, there is no need for an @samp{-s} variant; the
        !          1147: status line commands should be defined by default.  On other
        !          1148: terminals, enabling a status line means removing one screen line from
        !          1149: ordinary use and reducing the effective screen height.  For these
        !          1150: terminals, the user can choose the @samp{-s} variant type to request
        !          1151: use of a status line.
        !          1152: 
        !          1153: @item -@var{nlines}
        !          1154: Says to operate with @var{nlines} lines on the screen, for terminals
        !          1155: such as the Ambassador which provide this as an option.  Normally this
        !          1156: is a user option; by choosing the terminal type, you control how many
        !          1157: lines termcap will use.
        !          1158: 
        !          1159: @item -@var{npages}p
        !          1160: Says that the terminal has @var{npages} pages worth of screen memory,
        !          1161: for terminals where this is a hardware option.
        !          1162: 
        !          1163: @item -unk
        !          1164: Says that description is not for direct use, but only for reference in
        !          1165: @samp{tc} capabilities.  Such a description is a kind of subroutine,
        !          1166: because it describes the common characteristics of several variant
        !          1167: descriptions that would use other suffixes in place of @samp{-unk}.
        !          1168: @end table
        !          1169: 
        !          1170: @node Inheriting,, Naming, Data Base
        !          1171: @section Inheriting from Related Descriptions
        !          1172: 
        !          1173: @cindex inheritance
        !          1174: When two terminal descriptions are similar, their identical parts do not
        !          1175: need to be given twice.  Instead, one of the two can be defined in terms of
        !          1176: the other, using the @samp{tc} capability.  We say that one description
        !          1177: @dfn{refers to} the other, or @dfn{inherits from} the other.
        !          1178: 
        !          1179: The @samp{tc} capability must be the last one in the terminal description,
        !          1180: and its value is a string which is the name of another terminal type which
        !          1181: is referred to.  For example,
        !          1182: 
        !          1183: @example
        !          1184: N9|aaa|ambassador|aaa-30|ann arbor ambassador/30 lines:\
        !          1185:         :ti=\E[2J\E[30;0;0;30p:\
        !          1186:         :te=\E[60;0;0;30p\E[30;1H\E[J:\
        !          1187:         :li#30:tc=aaa-unk:
        !          1188: @end example
        !          1189: 
        !          1190: @noindent
        !          1191: defines the terminal type @samp{aaa-30} (also known as plain @samp{aaa}) in
        !          1192: terms of @samp{aaa-unk}, which defines everything about the Ambassador that
        !          1193: is independent of screen height.  The types @samp{aaa-36}, @samp{aaa-48}
        !          1194: and so on for other screen heights are likewise defined to inherit from
        !          1195: @samp{aaa-unk}.
        !          1196: 
        !          1197: The capabilities overridden by @samp{aaa-30} include @samp{li}, which says
        !          1198: how many lines there are, and @samp{ti} and @samp{te}, which configure the
        !          1199: terminal to use that many lines.
        !          1200: 
        !          1201: The effective terminal description for type @samp{aaa} consists of the text
        !          1202: shown above followed by the text of the description of @samp{aaa-unk}.  The
        !          1203: @samp{tc} capability is handled automatically by @code{tgetent}, which
        !          1204: finds the description thus referenced and combines the two descriptions
        !          1205: (@pxref{Find}).  Therefore, only the implementor of the terminal
        !          1206: descriptions needs to think about using @samp{tc}.  Users and application
        !          1207: programmers do not need to be concerned with it.
        !          1208: 
        !          1209: Since the reference terminal description is used last, capabilities
        !          1210: specified in the referring description override any specifications of the
        !          1211: same capabilities in the reference description.
        !          1212: 
        !          1213: The referring description can cancel out a capability without specifying
        !          1214: any new value for it by means of a special trick.  Write the capability in
        !          1215: the referring description, with the character @samp{@@} after the capability
        !          1216: name, as follows:
        !          1217: 
        !          1218: @example
        !          1219: NZ|aaa-30-nam|ann arbor ambassador/30 lines/no automatic-margins:\
        !          1220:         :am@@:tc=aaa-30:
        !          1221: @end example
        !          1222: 
        !          1223: @node Capabilities, Summary, Data Base, Top
        !          1224: @chapter Definitions of the Terminal Capabilities
        !          1225: 
        !          1226: This section is divided into many subsections, each for one aspect of
        !          1227: use of display terminals.  For writing a display program, you usually need
        !          1228: only check the subsections for the operations you want to use.  For writing
        !          1229: a terminal description, you must read each subsection and fill in the
        !          1230: capabilities described there.
        !          1231: 
        !          1232: String capabilities that are display commands may require numeric
        !          1233: parameters (@pxref{Parameters}).  Most such capabilities do not use
        !          1234: parameters.  When a capability requires parameters, this is explicitly
        !          1235: stated at the beginning of its definition.  In simple cases, the first or
        !          1236: second sentence of the definition mentions all the parameters, in the order
        !          1237: they should be given, using a name
        !          1238: @iftex
        !          1239: in italics
        !          1240: @end iftex
        !          1241: @ifinfo
        !          1242: in upper case
        !          1243: @end ifinfo
        !          1244: for each one.  For example, the @samp{rp} capability is a command that
        !          1245: requires two parameters; its definition begins as follows:
        !          1246: 
        !          1247: @quotation
        !          1248: String of commands to output a graphic character @var{c}, repeated @var{n}
        !          1249: times.
        !          1250: @end quotation
        !          1251: 
        !          1252: In complex cases or when there are many parameters, they are described
        !          1253: explicitly.
        !          1254: 
        !          1255: When a capability is described as obsolete, this means that programs should
        !          1256: not be written to look for it, but terminal descriptions should still be
        !          1257: written to provide it.
        !          1258: 
        !          1259: When a capability is described as very obsolete, this means that it should
        !          1260: be omitted from terminal descriptions as well.
        !          1261: 
        !          1262: @menu
        !          1263: * Basic::             Basic characteristics.
        !          1264: * Screen Size::       Screen size, and what happens when it changes.
        !          1265: * Cursor Motion::     Various ways to move the cursor.
        !          1266: * Scrolling::         Pushing text up and down on the screen.
        !          1267: * Wrapping::          What happens if you write a character in the last column.
        !          1268: * Windows::           Limiting the part of the window that output affects.
        !          1269: * Clearing::          Erasing one or many lines.
        !          1270: * Insdel Line::       Making new blank lines in mid-screen; deleting lines.
        !          1271: * Insdel Char::       Inserting and deleting characters within a line.
        !          1272: * Standout::          Highlighting some of the text.
        !          1273: * Underlining::       Underlining some of the text.
        !          1274: * Cursor Visibility:: Making the cursor more or less easy to spot.
        !          1275: * Bell::              Attracts user's attention; not localized on the screen.
        !          1276: * Keypad::            Recognizing when function keys or arrows are typed.
        !          1277: * Meta Key::          @key{META} acts like an extra shift key.
        !          1278: * Initialization::    Commands used to initialize or reset the terminal.
        !          1279: * Pad Specs::         Info for the kernel on how much padding is needed.
        !          1280: * Status Line::       A status line displays ``background'' information.
        !          1281: * Half-Line::         Moving by half-lines, for superscripts and subscripts.
        !          1282: * Printer::           Controlling auxiliary printers of display terminals.
        !          1283: @end menu
        !          1284: 
        !          1285: @node Basic, Screen Size, Capabilities, Capabilities
        !          1286: @section Basic Characteristics
        !          1287: 
        !          1288: This section documents the capabilities that describe the basic and
        !          1289: nature of the terminal, and also those that are relevant to the output
        !          1290: of graphic characters.
        !          1291: 
        !          1292: @table @samp
        !          1293: @item os
        !          1294: @kindex os
        !          1295: @cindex overstrike
        !          1296: Flag whose presence means that the terminal can overstrike.  This
        !          1297: means that outputting a graphic character does not erase whatever was
        !          1298: present in the same character position before.  The terminals that can
        !          1299: overstrike include printing terminals, storage tubes (all obsolete
        !          1300: nowadays), and many bit-map displays.
        !          1301: 
        !          1302: @item eo
        !          1303: @kindex eo
        !          1304: Flag whose presence means that outputting a space erases a character
        !          1305: position even if the terminal supports overstriking.  If this flag is
        !          1306: not present and overstriking is supported, output of a space has no
        !          1307: effect except to move the cursor.
        !          1308: 
        !          1309: (On terminals that do not support overstriking, you can always assume
        !          1310: that outputting a space at a position erases whatever character was
        !          1311: previously displayed there.)
        !          1312: 
        !          1313: @item gn
        !          1314: @kindex gn
        !          1315: @cindex generic terminal type
        !          1316: Flag whose presence means that this terminal type is a generic type
        !          1317: which does not really describe any particular terminal.  Generic types
        !          1318: are intended for use as the default type assigned when the user
        !          1319: connects to the system, with the intention that the user should
        !          1320: specify what type he really has.  One example of a generic type
        !          1321: is the type @samp{network}.
        !          1322: 
        !          1323: Since the generic type cannot say how to do anything interesting with
        !          1324: the terminal, termcap-using programs will always find that the
        !          1325: terminal is too weak to be supported if the user has failed to specify
        !          1326: a real terminal type in place of the generic one.  The @samp{gn} flag
        !          1327: directs these programs to use a different error message: ``You have
        !          1328: not specified your real terminal type'', rather than ``Your terminal
        !          1329: is not powerful enough to be used''.
        !          1330: 
        !          1331: @item hc
        !          1332: @kindex hc
        !          1333: Flag whose presence means this is a hardcopy terminal.
        !          1334: 
        !          1335: @item rp
        !          1336: @kindex rp
        !          1337: @cindex repeat output
        !          1338: String of commands to output a graphic character @var{c}, repeated @var{n}
        !          1339: times.  The first parameter value is the ASCII code for the desired
        !          1340: character, and the second parameter is the number of times to repeat the
        !          1341: character.  Often this command requires padding proportional to the 
        !          1342: number of times the character is repeated.  This effect can be had by
        !          1343: using parameter arithmetic with @samp{%}-sequences to compute the
        !          1344: amount of padding, then generating the result as a number at the front
        !          1345: of the string so that @code{tputs} will treat it as padding.
        !          1346: 
        !          1347: @item hz
        !          1348: @kindex hz
        !          1349: Flag whose presence means that the ASCII character @samp{~} cannot be
        !          1350: output on this terminal because it is used for display commands.
        !          1351: 
        !          1352: Programs handle this flag by checking all text to be output and
        !          1353: replacing each @samp{~} with some other character(s).  If this is not
        !          1354: done, the screen will be thoroughly garbled.
        !          1355: 
        !          1356: The old Hazeltine terminals that required such treatment are probably
        !          1357: very rare today, so you might as well not bother to support this flag.
        !          1358: 
        !          1359: @item CC
        !          1360: @kindex CC
        !          1361: @cindex command character
        !          1362: String whose presence means the terminal has a settable command
        !          1363: character.  The value of the string is the default command character
        !          1364: (which is usually @key{ESC}).
        !          1365: 
        !          1366: All the strings of commands in the terminal description should be
        !          1367: written to use the default command character.  If you are writing an
        !          1368: application program that changes the command character, use the
        !          1369: @samp{CC} capability to figure out how to translate all the display
        !          1370: commands to work with the new command character.
        !          1371: 
        !          1372: Most programs have no reason to look at the @samp{CC} capability.
        !          1373: 
        !          1374: @item xb
        !          1375: @kindex xb
        !          1376: @cindex Superbee
        !          1377: Flag whose presence identifies Superbee terminals which are unable to
        !          1378: transmit the characters @key{ESC} and @kbd{Control-C}.  Programs which
        !          1379: support this flag are supposed to check the input for the code sequences
        !          1380: sent by the @key{F1} and @key{F2} keys, and pretend that @key{ESC}
        !          1381: or @kbd{Control-C} (respectively) had been read.  But this flag is
        !          1382: obsolete, and not worth supporting.
        !          1383: @end table
        !          1384: 
        !          1385: @node Screen Size, Cursor Motion, Basic, Capabilities
        !          1386: @section Screen Size
        !          1387: @cindex screen size
        !          1388: 
        !          1389: A terminal description has two capabilities, @samp{co} and @samp{li},
        !          1390: that describe the screen size in columns and lines.  But there is more
        !          1391: to the question of screen size than this.
        !          1392: 
        !          1393: On some operating systems the ``screen'' is really a window and the
        !          1394: effective width can vary.  On some of these systems, @code{tgetnum}
        !          1395: uses the actual width of the window to decide what value to return for
        !          1396: the @samp{co} capability, overriding what is actually written in the
        !          1397: terminal description.  On other systems, it is up to the application
        !          1398: program to check the actual window width using a system call.  For
        !          1399: example, on BSD 4.3 systems, the system call @code{ioctl} with code
        !          1400: @code{TIOCGWINSZ} will tell you the current screen size.
        !          1401: 
        !          1402: On all window systems, termcap is powerless to advise the application
        !          1403: program if the user resizes the window.  Application programs must
        !          1404: deal with this possibility in a system-dependent fashion.  On some
        !          1405: systems the C shell handles part of the problem by detecting changes
        !          1406: in window size and setting the @code{TERMCAP} environment variable
        !          1407: appropriately.  This takes care of application programs that are
        !          1408: started subsequently.  It does not help application programs already
        !          1409: running.
        !          1410: 
        !          1411: On some systems, including BSD 4.3, all programs using a terminal get
        !          1412: a signal named @code{SIGWINCH} whenever the screen size changes.
        !          1413: Programs that use termcap should handle this signal by using
        !          1414: @code{ioctl TIOCGWINSZ} to learn the new screen size.
        !          1415: 
        !          1416: @table @samp
        !          1417: @item co
        !          1418: @kindex co
        !          1419: @cindex screen size
        !          1420: Numeric value, the width of the screen in character positions.  Even
        !          1421: hardcopy terminals normally have a @samp{co} capability.
        !          1422: 
        !          1423: @item li
        !          1424: @kindex li
        !          1425: Numeric value, the height of the screen in lines.
        !          1426: @end table
        !          1427: 
        !          1428: @node Cursor Motion, Wrapping, Screen Size, Capabilities
        !          1429: @section Cursor Motion
        !          1430: @cindex cursor motion
        !          1431: 
        !          1432: Termcap assumes that the terminal has a @dfn{cursor}, a spot on the screen
        !          1433: where a visible mark is displayed, and that most display commands take
        !          1434: effect at the position of the cursor.  It follows that moving the cursor
        !          1435: to a specified location is very important.
        !          1436: 
        !          1437: There are many terminal capabilities for different cursor motion
        !          1438: operations.  A terminal description should define as many as possible, but
        !          1439: most programs do not need to use most of them.  One capability, @samp{cm},
        !          1440: moves the cursor to an arbitrary place on the screen; this by itself is
        !          1441: sufficient for any application as long as there is no need to support
        !          1442: hardcopy terminals or certain old, weak displays that have only relative
        !          1443: motion commands.  Use of other cursor motion capabilities is an
        !          1444: optimization, enabling the program to output fewer characters in some
        !          1445: common cases.
        !          1446: 
        !          1447: If you plan to use the relative cursor motion commands in an application
        !          1448: program, you must know what the starting cursor position is.  To do this,
        !          1449: you must keep track of the cursor position and update the records each
        !          1450: time anything is output to the terminal, including graphic characters.
        !          1451: In addition, it is necessary to know whether the terminal wraps after
        !          1452: writing in the rightmost column.  @xref{Wrapping}.
        !          1453: 
        !          1454: One other motion capability needs special mention: @samp{nw} moves the
        !          1455: cursor to the beginning of the following line, perhaps clearing all the
        !          1456: starting line after the cursor, or perhaps not clearing at all.  This
        !          1457: capability is a least common denominator that is probably supported even by
        !          1458: terminals that cannot do most other things such as @samp{cm} or @samp{do}.
        !          1459: Even hardcopy terminals can support @samp{nw}.
        !          1460: 
        !          1461: @table @asis
        !          1462: @item @samp{cm}
        !          1463: @kindex cm
        !          1464: String of commands to position the cursor at line @var{l}, column @var{c}.
        !          1465: Both parameters are origin-zero, and are defined relative to the
        !          1466: screen, not relative to display memory.
        !          1467: 
        !          1468: All display terminals except a few very obsolete ones support @samp{cm},
        !          1469: so it is acceptable for an application program to refuse to operate on
        !          1470: terminals lacking @samp{cm}.
        !          1471: 
        !          1472: @item @samp{ho}
        !          1473: @kindex ho
        !          1474: @cindex home position
        !          1475: String of commands to move the cursor to the upper left corner of the
        !          1476: screen (this position is called the @dfn{home position}).  In
        !          1477: terminals where the upper left corner of the screen is not the same as
        !          1478: the beginning of display memory, this command must go to the upper
        !          1479: left corner of the screen, not the beginning of display memory.
        !          1480: 
        !          1481: Every display terminal supports this capability, and many application
        !          1482: programs refuse to operate if the @samp{ho} capability is missing.
        !          1483: 
        !          1484: @item @samp{ll}
        !          1485: @kindex ll
        !          1486: String of commands to move the cursor to the lower left corner of the
        !          1487: screen.  On some terminals, moving up from home position does this,
        !          1488: but programs should never assume that will work.  Just output the
        !          1489: @samp{ll} string (if it is provided); if moving to home position and
        !          1490: then moving up is the best way to get there, the @samp{ll} command
        !          1491: will do that.
        !          1492: 
        !          1493: @item @samp{cr}
        !          1494: @kindex cr
        !          1495: String of commands to move the cursor to the beginning of the line it
        !          1496: is on.  If this capability is not specified, many programs assume
        !          1497: they can use the ASCII carriage return character for this.
        !          1498: 
        !          1499: @item @samp{le}
        !          1500: @kindex le
        !          1501: String of commands to move the cursor left one column.  Unless the
        !          1502: @samp{bw} flag capability is specified, the effect is undefined if the
        !          1503: cursor is at the left margin; do not use this command there.  If
        !          1504: @samp{bw} is present, this command may be used at the left margin, and
        !          1505: it wraps the cursor to the last column of the preceding line.
        !          1506: 
        !          1507: @item @samp{nd}
        !          1508: @kindex nd
        !          1509: String of commands to move the cursor right one column.  The effect is
        !          1510: undefined if the cursor is at the right margin; do not use this
        !          1511: command there, not even if @samp{am} is present.
        !          1512: 
        !          1513: @item @samp{up}
        !          1514: @kindex up
        !          1515: String of commands to move the cursor vertically up one line.  The
        !          1516: effect of sending this string when on the top line is undefined;
        !          1517: programs should never use it that way.
        !          1518: 
        !          1519: @item @samp{do}
        !          1520: @kindex do
        !          1521: String of commands to move the cursor vertically down one line.  The
        !          1522: effect of sending this string when on the bottom line is undefined;
        !          1523: programs should never use it that way.
        !          1524: 
        !          1525: The original idea was that this string would not contain a newline
        !          1526: character and therefore could be used without disabling the kernel's usual
        !          1527: habit of converting of newline into a carriage-return newline sequence.
        !          1528: But many terminal descriptions do use newline in the @samp{do} string, so
        !          1529: this is not possible; a program which sends the @samp{do} string must
        !          1530: disable output conversion in the kernel (@pxref{Initialize}).
        !          1531: 
        !          1532: @item @samp{bw}
        !          1533: @kindex bw
        !          1534: Flag whose presence says that @samp{le} may be used in column zero
        !          1535: to move to the last column of the preceding line.  If this flag
        !          1536: is not present, @samp{le} should not be used in column zero.
        !          1537: 
        !          1538: @item @samp{nw}
        !          1539: @kindex nw
        !          1540: String of commands to move the cursor to start of next line, possibly
        !          1541: clearing rest of line (following the cursor) before moving.
        !          1542: 
        !          1543: @item @samp{DO}, @samp{UP}, @samp{LE}, @samp{RI}
        !          1544: @kindex DO
        !          1545: @kindex LE
        !          1546: @kindex RI
        !          1547: @kindex UP
        !          1548: Strings of commands to move the cursor @var{n} lines down vertically,
        !          1549: up vertically, or @var{n} columns left or right.  Do not attempt to
        !          1550: move past any edge of the screen with these commands; the effect of
        !          1551: trying that is undefined.  Only a few terminal descriptions provide
        !          1552: these commands, and most programs do not use them.
        !          1553: 
        !          1554: @item @samp{CM}
        !          1555: @kindex CM
        !          1556: String of commands to position the cursor at line @var{l}, column
        !          1557: @var{c}, relative to display memory.  Both parameters are origin-zero.
        !          1558: This capability is present only in terminals where there is a
        !          1559: difference between screen-relative and memory-relative addressing, and
        !          1560: not even in all such terminals.
        !          1561: 
        !          1562: @item @samp{ch}
        !          1563: @kindex ch
        !          1564: String of commands to position the cursor at column @var{c} in the
        !          1565: same line it is on.  This is a special case of @samp{cm} in which the
        !          1566: vertical position is not changed.  The @samp{ch} capability is
        !          1567: provided only when it is faster to output than @samp{cm} would be in
        !          1568: this special case.  Programs should not assume most display terminals
        !          1569: have @samp{ch}.
        !          1570: 
        !          1571: @item @samp{cv}
        !          1572: @kindex cv
        !          1573: String of commands to position the cursor at line @var{l} in the same
        !          1574: column.  This is a special case of @samp{cm} in which the horizontal
        !          1575: position is not changed.  The @samp{cv} capability is provided only
        !          1576: when it is faster to output than @samp{cm} would be in this special
        !          1577: case.  Programs should not assume most display terminals have
        !          1578: @samp{cv}.
        !          1579: 
        !          1580: @item @samp{sc}
        !          1581: @kindex sc
        !          1582: String of commands to make the terminal save the current cursor
        !          1583: position.  Only the last saved position can be used.  If this
        !          1584: capability is present, @samp{rc} should be provided also.  Most
        !          1585: terminals have neither.
        !          1586: 
        !          1587: @item @samp{rc}
        !          1588: @kindex rc
        !          1589: String of commands to make the terminal restore the last saved cursor
        !          1590: position.  If this capability is present, @samp{sc} should be provided
        !          1591: also.  Most terminals have neither.
        !          1592: 
        !          1593: @item @samp{ff}
        !          1594: @kindex ff
        !          1595: String of commands to advance to the next page, for a hardcopy
        !          1596: terminal.
        !          1597: 
        !          1598: @item @samp{ta}
        !          1599: @kindex ta
        !          1600: String of commands to move the cursor right to the next hardware tab
        !          1601: stop column.  Missing if the terminal does not have any kind of
        !          1602: hardware tabs.  Do not send this command if the kernel's terminal
        !          1603: modes say that the kernel is expanding tabs into spaces.
        !          1604: 
        !          1605: @item @samp{bt}
        !          1606: @kindex bt
        !          1607: String of commands to move the cursor left to the previous hardware
        !          1608: tab stop column.  Missing if the terminal has no such ability; many
        !          1609: terminals do not.  Do not send this command if the kernel's terminal
        !          1610: modes say that the kernel is expanding tabs into spaces.
        !          1611: @end table
        !          1612: 
        !          1613: The following obsolete capabilities should be included in terminal
        !          1614: descriptions when appropriate, but should not be looked at by new programs.
        !          1615: 
        !          1616: @table @samp
        !          1617: @item nc
        !          1618: @kindex nc
        !          1619: Flag whose presence means the terminal does not support the ASCII
        !          1620: carriage return character as @samp{cr}.  This flag is needed because
        !          1621: old programs assume, when the @samp{cr} capability is missing, that
        !          1622: ASCII carriage return can be used for the purpose.  We use @samp{nc}
        !          1623: to tell the old programs that carriage return may not be used.
        !          1624: 
        !          1625: New programs should not assume any default for @samp{cr}, so they need
        !          1626: not look at @samp{nc}.  However, descriptions should contain @samp{nc}
        !          1627: whenever they do not contain @samp{cr}.
        !          1628: 
        !          1629: @item xt
        !          1630: @kindex xt
        !          1631: Flag whose presence means that the ASCII tab character may not be used
        !          1632: for cursor motion.  This flag exists because old programs assume, when
        !          1633: the @samp{ta} capability is missing, that ASCII tab can be used for
        !          1634: the purpose.  We use @samp{xt} to tell the old programs not to use tab.
        !          1635: 
        !          1636: New programs should not assume any default for @samp{ta}, so they need
        !          1637: not look at @samp{xt} in connection with cursor motion.  Note that
        !          1638: @samp{xt} also has implications for standout mode (@pxref{Standout}).
        !          1639: It is obsolete in regard to cursor motion but not in regard to
        !          1640: standout.
        !          1641: 
        !          1642: In fact, @samp{xt} means that the terminal is a Teleray 1061.
        !          1643: 
        !          1644: @item bc
        !          1645: @kindex bc
        !          1646: Very obsolete alternative name for the @samp{le} capability.
        !          1647: 
        !          1648: @item bs
        !          1649: @kindex bs
        !          1650: Flag whose presence means that the ASCII character backspace may be
        !          1651: used to move the cursor left.  Obsolete; look at @samp{le} instead.
        !          1652: 
        !          1653: @item nl
        !          1654: @kindex nl
        !          1655: Obsolete capability which is a string that can either be used to move
        !          1656: the cursor down or to scroll.  The same string must scroll when used
        !          1657: on the bottom line and move the cursor when used on any other line.
        !          1658: New programs should use @samp{do} or @samp{sf}, and ignore @samp{nl}.
        !          1659: 
        !          1660: If there is no @samp{nl} capability, some old programs assume they can
        !          1661: use the newline character for this purpose.  These programs follow a
        !          1662: bad practice, but because they exist, it is still desirable to define
        !          1663: the @samp{nl} capability in a terminal description if the best way to
        !          1664: move down is @emph{not} a newline.
        !          1665: @end table
        !          1666: 
        !          1667: @node Wrapping, Scrolling, Cursor Motion, Capabilities
        !          1668: @section Wrapping
        !          1669: @cindex wrapping
        !          1670: 
        !          1671: @dfn{Wrapping} means moving the cursor from the right margin to the left
        !          1672: margin of the following line.  Some terminals wrap automatically when a
        !          1673: graphic character is output in the last column, while others do not.  Most
        !          1674: application programs that use termcap need to know whether the terminal
        !          1675: wraps.  There are two special flag capabilities to describe what the
        !          1676: terminal does when a graphic character is output in the last column.
        !          1677: 
        !          1678: @table @samp
        !          1679: @item am
        !          1680: @kindex am
        !          1681: Flag whose presence means that writing a character in the last column
        !          1682: causes the cursor to wrap to the beginning of the next line.
        !          1683: 
        !          1684: If @samp{am} is not present, writing in the last column leaves the
        !          1685: cursor at the place where the character was written.
        !          1686: 
        !          1687: Writing in the last column of the last line should be avoided on
        !          1688: terminals with @samp{am}, as it may or may not cause scrolling to
        !          1689: occur (@pxref{Scrolling}).  Scrolling is surely not what you would
        !          1690: intend.
        !          1691: 
        !          1692: If your program needs to check the @samp{am} flag, then it also needs
        !          1693: to check the @samp{xn} flag which indicates that wrapping happens in a
        !          1694: strange way.  Many common terminals have the @samp{xn} flag.
        !          1695: 
        !          1696: @item xn
        !          1697: @kindex xn
        !          1698: Flag whose presence means that the cursor wraps in a strange way.  At
        !          1699: least two distinct kinds of strange behavior are known; the termcap
        !          1700: data base does not contain anything to distinguish the two.
        !          1701: 
        !          1702: On Concept-100 terminals, output in the last column wraps the cursor
        !          1703: almost like an ordinary @samp{am} terminal.  But if the next thing
        !          1704: output is a newline, it is ignored.
        !          1705: 
        !          1706: DEC VT-100 terminals (when the wrap switch is on) do a different
        !          1707: strange thing: the cursor wraps only if the next thing output is
        !          1708: another graphic character.  In fact, the wrap occurs when the
        !          1709: following graphic character is received by the terminal, before the
        !          1710: character is placed on the screen.
        !          1711: 
        !          1712: On both of these terminals, after writing in the last column a
        !          1713: following graphic character will be displayed in the first column of
        !          1714: the following line.  But the effect of relative cursor motion
        !          1715: characters such as newline or backspace at such a time depends on the
        !          1716: terminal.  The effect of erase or scrolling commands also depends on
        !          1717: the terminal.  You can't assume anything about what they will do on a
        !          1718: terminal that has @samp{xn}.  So, to be safe, you should never do
        !          1719: these things at such a time on such a terminal.
        !          1720: 
        !          1721: To be sure of reliable results on a terminal which has the @samp{xn}
        !          1722: flag, output a @samp{cm} absolute positioning command after writing in
        !          1723: the last column.  Another safe thing to do is to output carriage-return
        !          1724: newline, which will leave the cursor at the beginning of the following
        !          1725: line.
        !          1726: @end table
        !          1727: 
        !          1728: @node Scrolling, Windows, Wrapping, Capabilities
        !          1729: @section Scrolling
        !          1730: @cindex scrolling
        !          1731: 
        !          1732: @dfn{Scrolling} means moving the contents of the screen up or down one or
        !          1733: more lines.  Moving the contents up is @dfn{forward scrolling}; moving them
        !          1734: down is @dfn{reverse scrolling}.
        !          1735: 
        !          1736: Scrolling happens after each line of output during ordinary output on most
        !          1737: display terminals.  But in an application program that uses termcap for
        !          1738: random-access output, scrolling happens only when explicitly requested with
        !          1739: the commands in this section.
        !          1740: 
        !          1741: Some terminals have a @dfn{scroll region} feature.  This lets you limit
        !          1742: the effect of scrolling to a specified range of lines.  Lines outside the
        !          1743: range are unaffected when scrolling happens.  The scroll region feature
        !          1744: is available if either @samp{cs} or @samp{cS} is present.
        !          1745: 
        !          1746: @table @samp
        !          1747: @item sf
        !          1748: @kindex sf
        !          1749: String of commands to scroll the screen one line up, assuming it is
        !          1750: output with the cursor at the beginning of the bottom line.
        !          1751: 
        !          1752: @item sr
        !          1753: @kindex sr
        !          1754: String of commands to scroll the screen one line down, assuming it is
        !          1755: output with the cursor at the beginning of the top line.
        !          1756: 
        !          1757: @item SF
        !          1758: @kindex SF
        !          1759: String of commands to scroll the screen @var{n} lines up, assuming it
        !          1760: is output with the cursor at the beginning of the bottom line.
        !          1761: 
        !          1762: @item SR
        !          1763: @kindex SR
        !          1764: String of commands to scroll the screen @var{n} line down, assuming it
        !          1765: is output with the cursor at the beginning of the top line.
        !          1766: 
        !          1767: @item cs
        !          1768: @kindex cs
        !          1769: String of commands to set the scroll region.  This command takes two
        !          1770: parameters, @var{start} and @var{end}, which are the line numbers
        !          1771: (origin-zero) of the first line to include in the scroll region and of
        !          1772: the last line to include in it.  When a scroll region is set,
        !          1773: scrolling is limited to the specified range of lines; lines outside
        !          1774: the range are not affected by scroll commands.
        !          1775: 
        !          1776: Do not try to move the cursor outside the scroll region.  The region
        !          1777: remains set until explicitly removed.  To remove the scroll region,
        !          1778: use another @samp{cs} command specifying the full height of the
        !          1779: screen.
        !          1780: 
        !          1781: The cursor position is undefined after the @samp{cs} command is set,
        !          1782: so position the cursor with @samp{cm} immediately afterward.
        !          1783: 
        !          1784: @item cS
        !          1785: @kindex cS
        !          1786: String of commands to set the scroll region using parameters in
        !          1787: different form.  The effect is the same as if @samp{cs} were used.
        !          1788: Four parameters are required:
        !          1789: 
        !          1790: @enumerate
        !          1791: @item
        !          1792: Total number of lines on the screen.
        !          1793: @item
        !          1794: Number of lines above desired scroll region.
        !          1795: @item
        !          1796: Number of lines below (outside of) desired scroll region.
        !          1797: @item
        !          1798: Total number of lines on the screen, the same as the first parameter.
        !          1799: @end enumerate
        !          1800: 
        !          1801: This capability is a GNU extension that was invented to allow the Ann
        !          1802: Arbor Ambassador's scroll-region command to be described; it could
        !          1803: also be done by putting non-Unix @samp{%}-sequences into a @samp{cs}
        !          1804: string, but that would have confused Unix programs that used the
        !          1805: @samp{cs} capability with the Unix termcap.  Currently only GNU Emacs
        !          1806: uses the @samp{cS} capability.
        !          1807: 
        !          1808: @item ns
        !          1809: @kindex ns
        !          1810: Flag which means that the terminal does not normally scroll for
        !          1811: ordinary sequential output.  For modern terminals, this means that
        !          1812: outputting a newline in ordinary sequential output with the cursor on
        !          1813: the bottom line wraps to the top line.  For some obsolete terminals,
        !          1814: other things may happen.
        !          1815: 
        !          1816: The terminal may be able to scroll even if it does not normally do so.
        !          1817: If the @samp{sf} capability is provided, it can be used for scrolling
        !          1818: regardless of @samp{ns}.
        !          1819: 
        !          1820: @item da
        !          1821: @kindex da
        !          1822: Flag whose presence means that lines scrolled up off the top of the
        !          1823: screen may come back if scrolling down is done subsequently.
        !          1824: 
        !          1825: The @samp{da} and @samp{db} flags do not, strictly speaking, affect
        !          1826: how to scroll.  But programs that scroll usually need to clear the
        !          1827: lines scrolled onto the screen, if these flags are present.
        !          1828: 
        !          1829: @item db
        !          1830: @kindex db
        !          1831: Flag whose presence means that lines scrolled down off the bottom of
        !          1832: the screen may come back if scrolling up is done subsequently.
        !          1833: 
        !          1834: @item lm
        !          1835: @kindex lm
        !          1836: Numeric value, the number of lines of display memory that the terminal
        !          1837: has.  A value of zero means that the terminal has more display memory
        !          1838: than can fit on the screen, but no fixed number of lines.  (The number
        !          1839: of lines may depend on the amount of text in each line.)
        !          1840: @end table
        !          1841: 
        !          1842: Any terminal description that defines @samp{SF} should also define @samp{sf};
        !          1843: likewise for @samp{SR} and @samp{sr}.  However, many terminals can only
        !          1844: scroll by one line at a time, so it is common to find @samp{sf} and not
        !          1845: @samp{SF}, or @samp{sr} without @samp{SR}.@refill
        !          1846: 
        !          1847: Therefore, all programs that use the scrolling facilities should be
        !          1848: prepared to work with @samp{sf} in the case that @samp{SF} is absent, and
        !          1849: likewise with @samp{sr}.  On the other hand, an application program that
        !          1850: uses only @samp{sf} and not @samp{SF} is acceptable, though slow on some
        !          1851: terminals.@refill
        !          1852: 
        !          1853: When outputting a scroll command with @code{tputs}, the @var{nlines}
        !          1854: argument should be the total number of lines in the portion of the screen
        !          1855: being scrolled.  Very often these commands require padding proportional to
        !          1856: this number of lines.  @xref{Padding}.
        !          1857: 
        !          1858: @node Windows, Clearing, Scrolling, Capabilities
        !          1859: @section Windows
        !          1860: @cindex window
        !          1861: 
        !          1862: A @dfn{window}, in termcap, is a rectangular portion of the screen to which
        !          1863: all display operations are restricted.  Wrapping, clearing, scrolling,
        !          1864: insertion and deletion all operate as if the specified window were all the
        !          1865: screen there was.
        !          1866: 
        !          1867: @table @samp
        !          1868: @item wi
        !          1869: @kindex wi
        !          1870: String of commands to set the terminal output screen window.
        !          1871: This string requires four parameters, all origin-zero:
        !          1872: @enumerate
        !          1873: @item
        !          1874: The first line to include in the window.
        !          1875: @item
        !          1876: The last line to include in the window.
        !          1877: @item
        !          1878: The first column to include in the window.
        !          1879: @item
        !          1880: The last column to include in the window.
        !          1881: @end enumerate
        !          1882: @end table
        !          1883: 
        !          1884: Most terminals do not support windows.
        !          1885: 
        !          1886: @node Clearing, Insdel Line, Windows, Capabilities
        !          1887: @section Clearing Parts of the Screen
        !          1888: @cindex erasing
        !          1889: @cindex clearing the screen
        !          1890: 
        !          1891: There are several terminal capabilities for clearing parts of the screen
        !          1892: to blank.  All display terminals support the @samp{cl} string, and most
        !          1893: display terminals support all of these capabilities.
        !          1894: 
        !          1895: @table @samp
        !          1896: @item cl
        !          1897: @kindex cl
        !          1898: String of commands to clear the entire screen and position the cursor
        !          1899: at the upper left corner.
        !          1900: 
        !          1901: @item cd
        !          1902: @kindex cd
        !          1903: String of commands to clear the line the cursor is on, and all the
        !          1904: lines below it, down to the bottom of the screen.  This command string
        !          1905: should be used only with the cursor in column zero; their effect is
        !          1906: undefined if the cursor is elsewhere.
        !          1907: 
        !          1908: @item ce
        !          1909: @kindex ce
        !          1910: String of commands to clear from the cursor to the end of the current
        !          1911: line.
        !          1912: 
        !          1913: @item ec
        !          1914: @kindex ec
        !          1915: String of commands to clear @var{n} characters, starting with the
        !          1916: character that the cursor is on.  This command string is expected to
        !          1917: leave the cursor position unchanged.  The parameter @var{n} should never
        !          1918: be large enough to reach past the right margin; the effect of such a
        !          1919: large parameter would be undefined.
        !          1920: @end table
        !          1921: 
        !          1922: Clear to end of line (@samp{ce}) is extremely important in programs that
        !          1923: maintain an updating display.  Nearly all display terminals support this
        !          1924: operation, so it is acceptable for a an application program to refuse to
        !          1925: work if @samp{ce} is not present.  However, if you do not want this
        !          1926: limitation, you can accomplish clearing to end of line by outputting spaces
        !          1927: until you reach the right margin.  In order to do this, you must know the
        !          1928: current horizontal position.  Also, this technique assumes that writing a
        !          1929: space will erase.  But this happens to be true on all the display terminals
        !          1930: that fail to support @samp{ce}.
        !          1931: 
        !          1932: @node Insdel Line, Insdel Char, Clearing, Capabilities
        !          1933: @section Insert/Delete Line
        !          1934: 
        !          1935: @cindex insert line
        !          1936: @cindex delete line
        !          1937: @dfn{Inserting a line} means creating a blank line in the middle
        !          1938: of the screen, and pushing the existing lines of text apart.  In fact,
        !          1939: the lines above the insertion point do not change, while the lines below
        !          1940: move down, and one is normally lost at the bottom of the screen.
        !          1941: 
        !          1942: @dfn{Deleting a line} means causing the line to disappear from the screen,
        !          1943: closing up the gap by moving the lines below it upward.  A new line
        !          1944: appears at the bottom of the screen.  Usually this line is blank, but
        !          1945: on terminals with the @samp{db} flag it may be a line previously moved
        !          1946: off the screen bottom by scrolling or line insertion.
        !          1947: 
        !          1948: Insertion and deletion of lines is useful in programs that maintain an
        !          1949: updating display some parts of which may get longer or shorter.  They are
        !          1950: also useful in editors for scrolling parts of the screen, and for
        !          1951: redisplaying after lines of text are killed or inserted.
        !          1952: 
        !          1953: Many terminals provide commands to insert or delete a single line at the
        !          1954: cursor position.  Some provide the ability to insert or delete several
        !          1955: lines with one command, using the number of lines to insert or delete as a
        !          1956: parameter.  Always move the cursor to column zero before using any of
        !          1957: these commands.
        !          1958: 
        !          1959: @table @samp
        !          1960: @item al
        !          1961: @kindex al
        !          1962: String of commands to insert a blank line before the line the cursor
        !          1963: is on.  The existing line, and all lines below it, are moved down.
        !          1964: The last line in the screen (or in the scroll region, if one is set)
        !          1965: disappears and in most circumstances is discarded.  It may not be
        !          1966: discarded if the @samp{db} is present (@pxref{Scrolling}).
        !          1967: 
        !          1968: The cursor must be at the left margin before this command is used.
        !          1969: This command does not move the cursor.
        !          1970: 
        !          1971: @item dl
        !          1972: @kindex dl
        !          1973: String of commands to delete the line the cursor is on.  The following
        !          1974: lines move up, and a blank line appears at the bottom of the screen
        !          1975: (or bottom of the scroll region).  If the terminal has the @samp{db}
        !          1976: flag, a nonblank line previously pushed off the screen bottom may
        !          1977: reappear at the bottom.
        !          1978: 
        !          1979: The cursor must be at the left margin before this command is used.
        !          1980: This command does not move the cursor.
        !          1981: 
        !          1982: @item AL
        !          1983: @kindex AL
        !          1984: String of commands to insert @var{n} blank lines before the line that
        !          1985: the cursor is on.  It is like @samp{al} repeated @var{n} times, except
        !          1986: that it is as fast as one @samp{al}.
        !          1987: 
        !          1988: @item DL
        !          1989: @kindex DL
        !          1990: String of commands to delete @var{n} lines starting with the line that
        !          1991: the cursor is on.  It is like @samp{dl} repeated @var{n} times, except
        !          1992: that it is as fast as one @samp{dl}.
        !          1993: @end table
        !          1994: 
        !          1995: Any terminal description that defines @samp{AL} should also define
        !          1996: @samp{al}; likewise for @samp{DL} and @samp{dl}.  However, many terminals
        !          1997: can only insert or delete one line at a time, so it is common to find
        !          1998: @samp{al} and not @samp{AL}, or @samp{dl} without @samp{DL}.@refill
        !          1999: 
        !          2000: Therefore, all programs that use the insert and delete facilities should be
        !          2001: prepared to work with @samp{al} in the case that @samp{AL} is absent, and
        !          2002: likewise with @samp{dl}.  On the other hand, it is acceptable to write
        !          2003: an application that uses only @samp{al} and @samp{dl} and does not look
        !          2004: for @samp{AL} or @samp{DL} at all.@refill
        !          2005: 
        !          2006: If a terminal does not support line insertion and deletion directly,
        !          2007: but does support a scroll region, the effect of insertion and deletion
        !          2008: can be obtained with scrolling.  However, it is up to the individual
        !          2009: user program to check for this possibility and use the scrolling
        !          2010: commands to get the desired result.  It is fairly important to implement
        !          2011: this alternate strategy, since it is the only way to get the effect of
        !          2012: line insertion and deletion on the popular VT100 terminal.
        !          2013: 
        !          2014: Insertion and deletion of lines is affected by the scroll region on
        !          2015: terminals that have a settable scroll region.  This is useful when it is
        !          2016: desirable to move any few consecutive lines up or down by a few lines.
        !          2017: @xref{Scrolling}.
        !          2018: 
        !          2019: The line pushed off the bottom of the screen is not lost if the terminal
        !          2020: has the @samp{db} flag capability; instead, it is pushed into display
        !          2021: memory that does not appear on the screen.  This is the same thing that
        !          2022: happens when scrolling pushes a line off the bottom of the screen.
        !          2023: Either reverse scrolling or deletion of a line can bring the apparently
        !          2024: lost line back onto the bottom of the screen.  If the terminal has the
        !          2025: scroll region feature as well as @samp{db}, the pushed-out line really
        !          2026: is lost if a scroll region is in effect.
        !          2027: 
        !          2028: When outputting an insert or delete command with @code{tputs}, the
        !          2029: @var{nlines} argument should be the total number of lines from the cursor
        !          2030: to the bottom of the screen (or scroll region).  Very often these commands
        !          2031: require padding proportional to this number of lines.  @xref{Padding}.
        !          2032: 
        !          2033: For @samp{AL} and @samp{DL} the @var{nlines} argument should @emph{not}
        !          2034: depend on the number of lines inserted or deleted; only the total number of
        !          2035: lines affected.  This is because it is just as fast to insert two or
        !          2036: @var{n} lines with @samp{AL} as to insert one line with @samp{al}.
        !          2037: 
        !          2038: @node Insdel Char, Standout, Insdel Line, Capabilities
        !          2039: @section Insert/Delete Character
        !          2040: @cindex insert character
        !          2041: @cindex delete character
        !          2042: 
        !          2043: @dfn{Inserting a character} means creating a blank space in the middle of a
        !          2044: line, and pushing the rest of the line rightward.  The character in the
        !          2045: rightmost column is lost.
        !          2046: 
        !          2047: @dfn{Deleting a character} means causing the character to disappear from
        !          2048: the screen, closing up the gap by moving the rest of the line leftward.  A
        !          2049: blank space appears in the rightmost column.
        !          2050: 
        !          2051: Insertion and deletion of characters is useful in programs that maintain an
        !          2052: updating display some parts of which may get longer or shorter.  It is also
        !          2053: useful in editors for redisplaying the results of editing within a line.
        !          2054: 
        !          2055: Many terminals provide commands to insert or delete a single character at
        !          2056: the cursor position.  Some provide the ability to insert or delete several
        !          2057: characters with one command, using the number of characters to insert or
        !          2058: delete as a parameter.
        !          2059: 
        !          2060: @cindex insert mode
        !          2061: Many terminals provide an insert mode in which outputting a graphic
        !          2062: character has the added effect of inserting a position for that character.
        !          2063: A special command string is used to enter insert mode and another is used
        !          2064: to exit it.  The reason for designing a terminal with an insert mode rather
        !          2065: than an insert command is that inserting character positions is usually
        !          2066: followed by writing characters into them.  With insert mode, this is as
        !          2067: fast as simply writing the characters, except for the fixed overhead of
        !          2068: entering and leaving insert mode.  However, when the line speed is great
        !          2069: enough, padding may be required for the graphic characters output in insert
        !          2070: mode.
        !          2071: 
        !          2072: Some terminals require you to enter insert mode and then output a special
        !          2073: command for each position to be inserted.  Or they may require special
        !          2074: commands to be output before or after each graphic character to be
        !          2075: inserted.
        !          2076: 
        !          2077: @cindex delete mode
        !          2078: Deletion of characters is usually accomplished by a straightforward command
        !          2079: to delete one or several positions; but on some terminals, it is necessary
        !          2080: to enter a special delete mode before using the delete command, and leave
        !          2081: delete mode afterward.  Sometimes delete mode and insert mode are the same
        !          2082: mode.
        !          2083: 
        !          2084: Some terminals make a distinction between character positions in which a
        !          2085: space character has been output and positions which have been cleared.  On
        !          2086: these terminals, the effect of insert or delete character runs to the first
        !          2087: cleared position rather than to the end of the line.  In fact, the effect
        !          2088: may run to more than one line if there is no cleared position to stop the
        !          2089: shift on the first line.  These terminals are identified by the @samp{in}
        !          2090: flag capability.
        !          2091: 
        !          2092: On terminals with the @samp{in} flag, the technique of skipping over
        !          2093: characters that you know were cleared, and then outputting text later on in
        !          2094: the same line, causes later insert and delete character operations on that
        !          2095: line to do nonstandard things.  A program that has any chance of doing this
        !          2096: must check for the @samp{in} flag and must be careful to write explicit
        !          2097: space characters into the intermediate columns when @samp{in} is present.
        !          2098: 
        !          2099: A plethora of terminal capabilities are needed to describe all of this
        !          2100: complexity.  Here is a list of them all.  Following the list, we present
        !          2101: an algorithm for programs to use to take proper account of all of these
        !          2102: capabilities.
        !          2103: 
        !          2104: @table @samp
        !          2105: @item im
        !          2106: @kindex im
        !          2107: String of commands to enter insert mode.
        !          2108: 
        !          2109: If the terminal has no special insert mode, but it can insert
        !          2110: characters with a special command, @samp{im} should be defined with a
        !          2111: null value, because the @samp{vi} editor assumes that insertion of a
        !          2112: character is impossible if @samp{im} is not provided.
        !          2113: 
        !          2114: New programs should not act like @samp{vi}.  They should pay attention
        !          2115: to @samp{im} only if it is defined.
        !          2116: 
        !          2117: @item ei
        !          2118: @kindex ei
        !          2119: String of commands to leave insert mode.  This capability must be
        !          2120: present if @samp{im} is.
        !          2121: 
        !          2122: On a few old terminals the same string is used to enter and exit
        !          2123: insert mode.  This string turns insert mode on if it was off, and off
        !          2124: it it was on.  You can tell these terminals because the @samp{ei}
        !          2125: string equals the @samp{im} string.  If you want to support these
        !          2126: terminals, you must always remember accurately whether insert mode is
        !          2127: in effect.  However, these terminals are obsolete, and it is
        !          2128: reasonable to refuse to support them.  On all modern terminals, you
        !          2129: can safely output @samp{ei} at any time to ensure that insert mode is
        !          2130: turned off.
        !          2131: 
        !          2132: @item ic
        !          2133: @kindex ic
        !          2134: String of commands to insert one character position at the cursor.
        !          2135: The cursor does not move.
        !          2136: 
        !          2137: If outputting a graphic character while in insert mode is sufficient
        !          2138: to insert the character, then the @samp{ic} capability should be
        !          2139: defined with a null value.
        !          2140: 
        !          2141: If your terminal offers a choice of ways to insert---either use insert
        !          2142: mode or use a special command---then define @samp{im} and do not define
        !          2143: @samp{ic}, since this gives the most efficient operation when several
        !          2144: characters are to be inserted.  @emph{Do not} define both strings, for
        !          2145: that means that @emph{both} must be used each time insertion is done.
        !          2146: 
        !          2147: @item ip
        !          2148: @kindex ip
        !          2149: String of commands to output following an inserted graphic character
        !          2150: in insert mode.  Often it is used just for a padding spec, when padding
        !          2151: is needed after an inserted character (@pxref{Padding}).
        !          2152: 
        !          2153: @item IC
        !          2154: @kindex IC
        !          2155: String of commands to insert @var{n} character positions at and after
        !          2156: the cursor.  It has the same effect as repeating the @samp{ic} string
        !          2157: and a space, @var{n} times.
        !          2158: 
        !          2159: If @samp{IC} is provided, application programs may use it without first
        !          2160: entering insert mode.
        !          2161: 
        !          2162: @item mi
        !          2163: @kindex mi
        !          2164: Flag whose presence means it is safe to move the cursor while in insert
        !          2165: mode and assume the terminal remains in insert mode.
        !          2166: 
        !          2167: @item in
        !          2168: @kindex in
        !          2169: Flag whose presence means that the terminal distinguishes between
        !          2170: character positions in which space characters have been output and
        !          2171: positions which have been cleared.
        !          2172: @end table
        !          2173: 
        !          2174: An application program can assume that the terminal can do character
        !          2175: insertion if @emph{any one of} the capabilities @samp{IC}, @samp{im},
        !          2176: @samp{ic} or @samp{ip} is provided.
        !          2177: 
        !          2178: To insert @var{n} blank character positions, move the cursor to the place
        !          2179: to insert them and follow this algorithm:
        !          2180: 
        !          2181: @enumerate
        !          2182: @item
        !          2183: If an @samp{IC} string is provided, output it with parameter @var{n}
        !          2184: and you are finished.  Otherwise (or if you don't want to bother to
        !          2185: look for an @samp{IC} string) follow the remaining steps.
        !          2186: 
        !          2187: @item
        !          2188: Output the @samp{im} string, if there is one, unless the terminal is
        !          2189: already in insert mode.
        !          2190: 
        !          2191: @item
        !          2192: Repeat steps 4 through 6, @var{n} times.
        !          2193: 
        !          2194: @item
        !          2195: Output the @samp{ic} string if any.
        !          2196: 
        !          2197: @item
        !          2198: Output a space.
        !          2199: 
        !          2200: @item
        !          2201: Output the @samp{ip} string if any.
        !          2202: 
        !          2203: @item
        !          2204: Output the @samp{ei} string, eventually, to exit insert mode.  There
        !          2205: is no need to do this right away.  If the @samp{mi} flag is present,
        !          2206: you can move the cursor and the cursor will remain in insert mode;
        !          2207: then you can do more insertion elsewhere without reentering insert
        !          2208: mode.
        !          2209: @end enumerate
        !          2210: 
        !          2211: To insert @var{n} graphic characters, position the cursor and follow this
        !          2212: algorithm:
        !          2213: 
        !          2214: @enumerate
        !          2215: @item
        !          2216: If an @samp{IC} string is provided, output it with parameter @var{n},
        !          2217: then output the graphic characters, and you are finished.  Otherwise
        !          2218: (or if you don't want to bother to look for an @samp{IC} string)
        !          2219: follow the remaining steps.
        !          2220: 
        !          2221: @item
        !          2222: Output the @samp{im} string, if there is one, unless the terminal is
        !          2223: already in insert mode.
        !          2224: 
        !          2225: @item
        !          2226: For each character to be output, repeat steps 4 through 6.
        !          2227: 
        !          2228: @item
        !          2229: Output the @samp{ic} string if any.
        !          2230: 
        !          2231: @item
        !          2232: Output the next graphic character.
        !          2233: 
        !          2234: @item
        !          2235: Output the @samp{ip} string if any.
        !          2236: 
        !          2237: @item
        !          2238: Output the @samp{ei} string, eventually, to exit insert mode.  There
        !          2239: is no need to do this right away.  If the @samp{mi} flag is present,
        !          2240: you can move the cursor and the cursor will remain in insert mode;
        !          2241: then you can do more insertion elsewhere without reentering insert
        !          2242: mode.
        !          2243: @end enumerate
        !          2244: 
        !          2245: Note that this is not the same as the original Unix termcap specifications
        !          2246: in one respect: it assumes that the @samp{IC} string can be used without
        !          2247: entering insert mode.  This is true as far as I know, and it allows you be
        !          2248: able to avoid entering and leaving insert mode, and also to be able to
        !          2249: avoid the inserted-character padding after the characters that go into the
        !          2250: inserted positions.
        !          2251: 
        !          2252: Deletion of characters is less complicated; deleting one column is done by
        !          2253: outputting the @samp{dc} string.  However, there may be a delete mode that
        !          2254: must be entered with @samp{dm} in order to make @samp{dc} work.
        !          2255: 
        !          2256: @table @samp
        !          2257: @item dc
        !          2258: @kindex dc
        !          2259: String of commands to delete one character position at the cursor.  If
        !          2260: @samp{dc} is not present, the terminal cannot delete characters.
        !          2261: 
        !          2262: @item DC
        !          2263: @kindex DC
        !          2264: String of commands to delete @var{n} characters starting at the cursor.
        !          2265: It has the same effect as repeating the @samp{dc} string @var{n} times.
        !          2266: Any terminal description that has @samp{DC} also has @samp{dc}.
        !          2267: 
        !          2268: @item dm
        !          2269: @kindex dm
        !          2270: String of commands to enter delete mode.  If not present, there is no
        !          2271: delete mode, and @samp{dc} can be used at any time (assuming there is
        !          2272: a @samp{dc}).
        !          2273: 
        !          2274: @item ed
        !          2275: @kindex ed
        !          2276: String of commands to exit delete mode.  This must be present if
        !          2277: @samp{dm} is.
        !          2278: @end table
        !          2279: 
        !          2280: To delete @var{n} character positions, position the cursor and follow these
        !          2281: steps:
        !          2282: 
        !          2283: @enumerate
        !          2284: @item
        !          2285: If the @samp{DC} string is present, output it with parameter @var{n}
        !          2286: and you are finished.  Otherwise, follow the remaining steps.
        !          2287: 
        !          2288: @item
        !          2289: Output the @samp{dm} string, unless you know the terminal is already
        !          2290: in delete mode.
        !          2291: 
        !          2292: @item
        !          2293: Output the @samp{dc} string @var{n} times.
        !          2294: 
        !          2295: @item
        !          2296: Output the @samp{ed} string eventually.  If the flag capability
        !          2297: @samp{mi} is present, you can move the cursor and do more deletion
        !          2298: without leaving and reentering delete mode.
        !          2299: @end enumerate
        !          2300: 
        !          2301: As with the @samp{IC} string, we have departed from the original termcap
        !          2302: specifications by assuming that @samp{DC} works without entering delete
        !          2303: mode even though @samp{dc} would not.
        !          2304: 
        !          2305: If the @samp{dm} and @samp{im} capabilities are both present and have the
        !          2306: same value, it means that the terminal has one mode for both insertion and
        !          2307: deletion.  It is useful for a program to know this, because then it can do
        !          2308: insertions after deletions, or vice versa, without leaving insert/delete
        !          2309: mode and reentering it.
        !          2310: 
        !          2311: @node Standout, Underlining, Insdel Char, Capabilities
        !          2312: @section Standout and Appearance Modes
        !          2313: @cindex appearance modes
        !          2314: @cindex standout
        !          2315: @cindex magic cookie
        !          2316: 
        !          2317: @dfn{Appearance modes} are modifications to the ways characters are
        !          2318: displayed.  Typical appearance modes include reverse video, dim, bright,
        !          2319: blinking, underlined, invisible, and alternate character set.  Each kind of
        !          2320: terminal supports various among these, or perhaps none.
        !          2321: 
        !          2322: For each type of terminal, one appearance mode or combination of them that
        !          2323: looks good for highlighted text is chosen as the @dfn{standout mode}.  The
        !          2324: capabilities @samp{so} and @samp{se} say how to enter and leave standout
        !          2325: mode.  Programs that use appearance modes only to highlight some text
        !          2326: generally use the standout mode so that they can work on as many terminals
        !          2327: as possible.  Use of specific appearance modes other than ``underlined''
        !          2328: and ``alternate character set'' is rare.
        !          2329: 
        !          2330: Terminals that implement appearance modes fall into two general classes as
        !          2331: to how they do it.
        !          2332: 
        !          2333: In some terminals, the presence or absence of any appearance mode is
        !          2334: recorded separately for each character position.  In these terminals, each
        !          2335: graphic character written is given the appearance modes current at the time
        !          2336: it is written, and keeps those modes until it is erased or overwritten.
        !          2337: There are special commands to turn the appearance modes on or off for
        !          2338: characters to be written in the future.
        !          2339: 
        !          2340: In other terminals, the change of appearance modes is represented by a
        !          2341: marker that belongs to a certain screen position but affects all following
        !          2342: screen positions until the next marker.  These markers are traditionally
        !          2343: called @dfn{magic cookies}.
        !          2344: 
        !          2345: The same capabilities (@samp{so}, @samp{se}, @samp{mb} and so on) for
        !          2346: turning appearance modes on and off are used for both magic-cookie
        !          2347: terminals and per-character terminals.  On magic cookie terminals, these
        !          2348: give the commands to write the magic cookies.  On per-character terminals,
        !          2349: they change the current modes that affect future output and erasure.  Some
        !          2350: simple applications can use these commands without knowing whether or not
        !          2351: they work by means of cookies.
        !          2352: 
        !          2353: However, a program that maintains and updates a display needs to know
        !          2354: whether the terminal uses magic cookies, and exactly what their effect is.
        !          2355: This information comes from the @samp{sg} capability.
        !          2356: 
        !          2357: The @samp{sg} capability is a numeric capability whose presence indicates
        !          2358: that the terminal uses magic cookies for appearance modes.  Its value is
        !          2359: the number of character positions that a magic cookie occupies.  Usually
        !          2360: the cookie occupies one or more character positions on the screen, and these
        !          2361: character positions are displayed as blank, but in some terminals the
        !          2362: cookie has zero width.
        !          2363: 
        !          2364: The @samp{sg} capability describes both the magic cookie to turn standout
        !          2365: on and the cookie to turn it off.  This makes the assumption that both
        !          2366: kinds of cookie have the same width on the screen.  If that is not true,
        !          2367: the narrower cookie must be ``widened'' with spaces until it has the same
        !          2368: width as the other.
        !          2369: 
        !          2370: On some magic cookie terminals, each line always starts with normal
        !          2371: display; in other words, the scope of a magic cookie never extends over
        !          2372: more than one line.  But on other terminals, one magic cookie affects all
        !          2373: the lines below it unless explicitly canceled.  Termcap does not define any
        !          2374: way to distinguish these two ways magic cookies can work.  To be safe, it
        !          2375: is best to put a cookie at the beginning of each line.
        !          2376: 
        !          2377: On some per-character terminals, standout mode or other appearance modes
        !          2378: may be canceled by moving the cursor.  On others, moving the cursor has no
        !          2379: effect on the state of the appearance modes.  The latter class of terminals
        !          2380: are given the flag capability @samp{ms} (``can move in standout'').  All
        !          2381: programs that might have occasion to move the cursor while appearance modes
        !          2382: are turned on must check for this flag; if it is not present, they should
        !          2383: reset appearance modes to normal before doing cursor motion.
        !          2384: 
        !          2385: A program that has turned on only standout mode should use @samp{se} to
        !          2386: reset the standout mode to normal.  A program that has turned on only
        !          2387: alternate character set mode should use @samp{ae} to return it to normal.
        !          2388: If it is possible that any other appearance modes are turned on, use the
        !          2389: @samp{me} capability to return them to normal.
        !          2390: 
        !          2391: Note that the commands to turn on one appearance mode, including @samp{so}
        !          2392: and @samp{mb} @dots{} @samp{mr}, if used while some other appearance modes
        !          2393: are turned on, may combine the two modes on some terminals but may turn off
        !          2394: the mode previously enabled on other terminals.  This is because some
        !          2395: terminals do not have a command to set or clear one appearance mode without
        !          2396: changing the others.  Programs should not attempt to use appearance modes
        !          2397: in combination except with @samp{sa}, and when switching from one single
        !          2398: mode to another should always turn off the previously enabled mode and then
        !          2399: turn on the new desired mode.
        !          2400: 
        !          2401: On some old terminals, the @samp{so} and @samp{se} commands may be the same
        !          2402: command, which has the effect of turning standout on if it is off, or off
        !          2403: it is on.  It is therefore risky for a program to output extra @samp{se}
        !          2404: commands for good measure.  Fortunately, all these terminals are obsolete.
        !          2405: 
        !          2406: Programs that update displays in which standout-text may be replaced with
        !          2407: non-standout text must check for the @samp{xs} flag.  In a per-character
        !          2408: terminal, this flag says that the only way to remove standout once written is
        !          2409: to clear that portion of the line with the @samp{ce} string or something
        !          2410: even more powerful (@pxref{Clearing}); just writing new characters at those
        !          2411: screen positions will not change the modes in effect there.  In a magic
        !          2412: cookie terminal, @samp{xs} says that the only way to remove a cookie is to
        !          2413: clear a portion of the line that includes the cookie; writing a different
        !          2414: cookie at the same position does not work.
        !          2415: 
        !          2416: Such programs must also check for the @samp{xt} flag, which means that the
        !          2417: terminal is a Teleray 1061.  On this terminal it is impossible to position
        !          2418: the cursor at the front of a magic cookie, so the only two ways to remove a
        !          2419: cookie are (1) to delete the line it is on or (2) to position the cursor at
        !          2420: least one character before it (possibly on a previous line) and output the
        !          2421: @samp{se} string, which on these terminals finds and removes the next
        !          2422: @samp{so} magic cookie on the screen.  (It may also be possible to remove a
        !          2423: cookie which is not at the beginning of a line by clearing that line.)  The
        !          2424: @samp{xt} capability also has implications for the use of tab characters,
        !          2425: but in that regard it is obsolete (@xref{Cursor Motion}).
        !          2426: 
        !          2427: @table @samp
        !          2428: @item so
        !          2429: @kindex so
        !          2430: String of commands to enter standout mode.
        !          2431: 
        !          2432: @item se
        !          2433: @kindex se
        !          2434: String of commands to leave standout mode.
        !          2435: 
        !          2436: @item sg
        !          2437: @kindex sg
        !          2438: Numeric capability, the width on the screen of the magic cookie.  This
        !          2439: capability is absent in terminals that record appearance modes
        !          2440: character by character.
        !          2441: 
        !          2442: @item ms
        !          2443: @kindex ms
        !          2444: Flag whose presence means that it is safe to move the cursor while the
        !          2445: appearance modes are not in the normal state.  If this flag is absent,
        !          2446: programs should always reset the appearance modes to normal before
        !          2447: moving the cursor.
        !          2448: 
        !          2449: @item xs
        !          2450: @kindex xs
        !          2451: Flag whose presence means that the only way to reset appearance modes
        !          2452: already on the screen is to clear to end of line.  On a per-character
        !          2453: terminal, you must clear the area where the modes are set.  On a magic
        !          2454: cookie terminal, you must clear an area containing the cookie.
        !          2455: See the discussion above.
        !          2456: 
        !          2457: @item xt
        !          2458: @kindex xt
        !          2459: Flag whose presence means that the cursor cannot be positioned right
        !          2460: in front of a magic cookie, and that @samp{se} is a command to delete
        !          2461: the next magic cookie following the cursor.  See discussion above.
        !          2462: 
        !          2463: @item mb
        !          2464: @kindex mb
        !          2465: String of commands to enter blinking mode.
        !          2466: 
        !          2467: @item md
        !          2468: @kindex md
        !          2469: String of commands to enter double-bright mode.
        !          2470: 
        !          2471: @item mh
        !          2472: @kindex mh
        !          2473: String of commands to enter half-bright mode.
        !          2474: 
        !          2475: @item mk
        !          2476: @kindex mk
        !          2477: String of commands to enter invisible mode.
        !          2478: 
        !          2479: @item mp
        !          2480: @kindex mp
        !          2481: String of commands to enter protected mode.
        !          2482: 
        !          2483: @item mr
        !          2484: @kindex mr
        !          2485: String of commands to enter reverse-video mode.
        !          2486: 
        !          2487: @item me
        !          2488: @kindex me
        !          2489: String of commands to turn off all appearance modes, including
        !          2490: standout mode and underline mode.  On some terminals it also turns off
        !          2491: alternate character set mode; on others, it may not.  This capability
        !          2492: must be present if any of @samp{mb} @dots{} @samp{mr} is present.
        !          2493: 
        !          2494: @item as
        !          2495: @kindex as
        !          2496: String of commands to turn on alternate character set mode.  This mode
        !          2497: assigns some or all graphic characters an alternate picture on the
        !          2498: screen.  There is no standard as to what the alternate pictures look
        !          2499: like.
        !          2500: 
        !          2501: @item ae
        !          2502: @kindex ae
        !          2503: String of commands to turn off alternate character set mode.
        !          2504: 
        !          2505: @item sa
        !          2506: @kindex sa
        !          2507: String of commands to turn on an arbitrary combination of appearance
        !          2508: modes.  It accepts 9 parameters, each of which controls a particular
        !          2509: kind of appearance mode.  A parameter should be 1 to turn its appearance
        !          2510: mode on, or zero to turn that mode off.  Most terminals do not support
        !          2511: the @samp{sa} capability, even among those that do have various
        !          2512: appearance modes.
        !          2513: 
        !          2514: The nine parameters are, in order, @var{standout}, @var{underline},
        !          2515: @var{reverse}, @var{blink}, @var{half-bright}, @var{double-bright},
        !          2516: @var{blank}, @var{protect}, @var{alt char set}.
        !          2517: @end table
        !          2518: 
        !          2519: @node Underlining, Cursor Visibility, Standout, Capabilities
        !          2520: @section Underlining
        !          2521: @cindex underlining
        !          2522: 
        !          2523: Underlining on most terminals is a kind of appearance mode, much like
        !          2524: standout mode.  Therefore, it may be implemented using magic cookies or as
        !          2525: a flag in the terminal whose current state affects each character that is
        !          2526: output.  @xref{Standout}, for a full explanation.
        !          2527: 
        !          2528: The @samp{ug} capability is a numeric capability whose presence indicates
        !          2529: that the terminal uses magic cookies for underlining.  Its value is the
        !          2530: number of character positions that a magic cookie for underlining occupies;
        !          2531: it is used for underlining just as @samp{sg} is used for standout.  Aside
        !          2532: from the simplest applications, it is impossible to use underlining
        !          2533: correctly without paying attention to the value of @samp{ug}.
        !          2534: 
        !          2535: @table @samp
        !          2536: @item us
        !          2537: @kindex us
        !          2538: String of commands to turn on underline mode or to output a magic cookie
        !          2539: to start underlining.
        !          2540: 
        !          2541: @item ue
        !          2542: @kindex ue
        !          2543: String of commands to turn off underline mode or to output a magic
        !          2544: cookie to stop underlining.
        !          2545: 
        !          2546: @item ug
        !          2547: @kindex ug
        !          2548: Width of magic cookie that represents a change of underline mode;
        !          2549: or missing, if the terminal does not use a magic cookie for this.
        !          2550: 
        !          2551: @item ms
        !          2552: @kindex ms
        !          2553: Flag whose presence means that it is safe to move the cursor while the
        !          2554: appearance modes are not in the normal state.  Underlining is an
        !          2555: appearance mode.  If this flag is absent, programs should always turn
        !          2556: off underlining before moving the cursor.
        !          2557: @end table
        !          2558: 
        !          2559: There are two other, older ways of doing underlining: there can be a
        !          2560: command to underline a single character, or the output of @samp{_}, the
        !          2561: ASCII underscore character, as an overstrike could cause a character to be
        !          2562: underlined.  New programs need not bother to handle these capabilities
        !          2563: unless the author cares strongly about the obscure terminals which support
        !          2564: them.  However, terminal descriptions should provide these capabilities
        !          2565: when appropriate.
        !          2566: 
        !          2567: @table @samp
        !          2568: @item uc
        !          2569: @kindex uc
        !          2570: String of commands to underline the character under the cursor, and
        !          2571: move the cursor right.
        !          2572: 
        !          2573: @item ul
        !          2574: @kindex ul
        !          2575: Flag whose presence means that the terminal can underline by
        !          2576: overstriking an underscore character (@samp{_}); some terminals can do
        !          2577: this even though they do not support overstriking in general.  An
        !          2578: implication of this flag is that when outputting new text to overwrite
        !          2579: old text, underscore characters must be treated specially lest they
        !          2580: underline the old text instead.
        !          2581: @end table
        !          2582: 
        !          2583: @node Cursor Visibility, Bell, Underlining, Capabilities
        !          2584: @section Cursor Visibility
        !          2585: @cindex visibility
        !          2586: 
        !          2587: Some terminals have the ability to make the cursor invisible, or to enhance
        !          2588: it.  Enhancing the cursor is often done by programs that plan to use the
        !          2589: cursor to indicate to the user a position of interest that may be anywhere
        !          2590: on the screen---for example, the Emacs editor enhances the cursor on entry.
        !          2591: Such programs should always restore the cursor to normal on exit.
        !          2592: 
        !          2593: @table @samp
        !          2594: @item vs
        !          2595: @kindex vs
        !          2596: String of commands to enhance the cursor.
        !          2597: 
        !          2598: @item vi
        !          2599: @kindex vi
        !          2600: String of commands to make the cursor invisible.
        !          2601: 
        !          2602: @item ve
        !          2603: @kindex ve
        !          2604: String of commands to return the cursor to normal.
        !          2605: @end table
        !          2606: 
        !          2607: If you define either @samp{vs} or @samp{vi}, you must also define @samp{ve}.
        !          2608: 
        !          2609: @node Bell, Keypad, Cursor Visibility, Capabilities
        !          2610: @section Bell
        !          2611: @cindex bell
        !          2612: @cindex visible bell
        !          2613: 
        !          2614: Here we describe commands to make the terminal ask for the user to pay
        !          2615: attention to it.
        !          2616: 
        !          2617: @table @samp
        !          2618: @item bl
        !          2619: @kindex bl
        !          2620: String of commands to cause the terminal to make an audible sound.  If
        !          2621: this capability is absent, the terminal has no way to make a suitable
        !          2622: sound.
        !          2623: 
        !          2624: @item vb
        !          2625: @kindex vb
        !          2626: String of commands to cause the screen to flash to attract attention
        !          2627: (``visible bell'').  If this capability is absent, the terminal has no
        !          2628: way to do such a thing.
        !          2629: @end table
        !          2630: 
        !          2631: @node Keypad, Meta Key, Bell, Capabilities
        !          2632: @section Keypad and Function Keys
        !          2633: 
        !          2634: Many terminals have arrow and function keys that transmit specific
        !          2635: character sequences to the computer.  Since the precise sequences used
        !          2636: depend on the terminal, termcap defines capabilities used to say what the
        !          2637: sequences are.  Unlike most termcap string-valued capabilities, these are
        !          2638: not strings of commands to be sent to the terminal, rather strings that
        !          2639: are received from the terminal.
        !          2640: 
        !          2641: Programs that expect to use keypad keys should check, initially, for a
        !          2642: @samp{ks} capability and send it, to make the keypad actually transmit.
        !          2643: Such programs should also send the @samp{ke} string when exiting.
        !          2644: 
        !          2645: @table @asis
        !          2646: @item @samp{ks}
        !          2647: @kindex ka@dots{}ku
        !          2648: String of commands to make the function keys transmit.  If this
        !          2649: capability is not provided, but the others in this section are,
        !          2650: programs may assume that the function keys always transmit.
        !          2651: 
        !          2652: @item @samp{ke}
        !          2653: String of commands to make the function keys work locally.  This
        !          2654: capability is provided only if @samp{ks} is.
        !          2655: 
        !          2656: @item @samp{kl}
        !          2657: String of input characters sent by typing the left-arrow key.  If this
        !          2658: capability is missing, you cannot expect the terminal to have a
        !          2659: left-arrow key that transmits anything to the computer.
        !          2660: 
        !          2661: @item @samp{kr}
        !          2662: String of input characters sent by typing the right-arrow key.
        !          2663: 
        !          2664: @item @samp{ku}
        !          2665: String of input characters sent by typing the up-arrow key.
        !          2666: 
        !          2667: @item @samp{kd}
        !          2668: String of input characters sent by typing the down-arrow key.
        !          2669: 
        !          2670: @item @samp{kh}
        !          2671: String of input characters sent by typing the ``home-position'' key.
        !          2672: 
        !          2673: @item @samp{K1} @dots{} @samp{K5}
        !          2674: @kindex K1@dots{}K5
        !          2675: Strings of input characters sent by the five other keys in a 3-by-3
        !          2676: array that includes the arrow keys, if the keyboard has such a 3-by-3
        !          2677: array.  Note that one of these keys may be the ``home-position'' key,
        !          2678: in which case one of these capabilities will have the same value as
        !          2679: the @samp{kh} key.
        !          2680: 
        !          2681: @item @samp{k0}
        !          2682: String of input characters sent by function key 10 (or 0, if the terminal
        !          2683: has one labeled 0).
        !          2684: 
        !          2685: @item @samp{k1} @dots{} @samp{k9}
        !          2686: @kindex k1@dots{}k9
        !          2687: Strings of input characters sent by function keys 1 through 9,
        !          2688: provided for those function keys that exist.
        !          2689: 
        !          2690: @item @samp{kn}
        !          2691: Number: the number of numbered function keys, if there are more than
        !          2692: 10.
        !          2693: 
        !          2694: @item @samp{l0} @dots{} @samp{l9}
        !          2695: @kindex l0@dots{}l9
        !          2696: Strings which are the labels appearing on the keyboard on the keys
        !          2697: described by the capabilities @samp{k0} @dots{} @samp{l9}.  These
        !          2698: capabilities should be left undefined if the labels are @samp{f0} or
        !          2699: @samp{f10} and @samp{f1} @dots{} @samp{f9}.@refill
        !          2700: 
        !          2701: @item @samp{kH}
        !          2702: @kindex kA@dots{}kT
        !          2703: String of input characters sent by the ``home down'' key, if there is
        !          2704: one.
        !          2705: 
        !          2706: @item @samp{kb}
        !          2707: String of input characters sent by the ``backspace'' key, if there is
        !          2708: one.
        !          2709: 
        !          2710: @item @samp{ka}
        !          2711: String of input characters sent by the ``clear all tabs'' key, if there
        !          2712: is one.
        !          2713: 
        !          2714: @item @samp{kt}
        !          2715: String of input characters sent by the ``clear tab stop this column''
        !          2716: key, if there is one.
        !          2717: 
        !          2718: @item @samp{kC}
        !          2719: String of input characters sent by the ``clear screen'' key, if there is
        !          2720: one.
        !          2721: 
        !          2722: @item @samp{kD}
        !          2723: String of input characters sent by the ``delete character'' key, if
        !          2724: there is one.
        !          2725: 
        !          2726: @item @samp{kL}
        !          2727: String of input characters sent by the ``delete line'' key, if there is
        !          2728: one.
        !          2729: 
        !          2730: @item @samp{kM}
        !          2731: String of input characters sent by the ``exit insert mode'' key, if
        !          2732: there is one.
        !          2733: 
        !          2734: @item @samp{kE}
        !          2735: String of input characters sent by the ``clear to end of line'' key, if
        !          2736: there is one.
        !          2737: 
        !          2738: @item @samp{kS}
        !          2739: String of input characters sent by the ``clear to end of screen'' key,
        !          2740: if there is one.
        !          2741: 
        !          2742: @item @samp{kI}
        !          2743: String of input characters sent by the ``insert character'' or ``enter
        !          2744: insert mode'' key, if there is one.
        !          2745: 
        !          2746: @item @samp{kA}
        !          2747: String of input characters sent by the ``insert line'' key, if there is
        !          2748: one.
        !          2749: 
        !          2750: @item @samp{kN}
        !          2751: String of input characters sent by the ``next page'' key, if there is
        !          2752: one.
        !          2753: 
        !          2754: @item @samp{kP}
        !          2755: String of input characters sent by the ``previous page'' key, if there is
        !          2756: one.
        !          2757: 
        !          2758: @item @samp{kF}
        !          2759: String of input characters sent by the ``scroll forward'' key, if there
        !          2760: is one.
        !          2761: 
        !          2762: @item @samp{kR}
        !          2763: String of input characters sent by the ``scroll reverse'' key, if there
        !          2764: is one.
        !          2765: 
        !          2766: @item @samp{kT}
        !          2767: String of input characters sent by the ``set tab stop in this column''
        !          2768: key, if there is one.
        !          2769: 
        !          2770: @item @samp{ko}
        !          2771: String listing the other function keys the terminal has.  This is a
        !          2772: very obsolete way of describing the same information found in the
        !          2773: @samp{kH} @dots{} @samp{kT} keys.  The string contains a list of
        !          2774: two-character termcap capability names, separated by commas.  The
        !          2775: meaning is that for each capability name listed, the terminal has a
        !          2776: key which sends the string which is the value of that capability.  For
        !          2777: example, the value @samp{:ko=cl,ll,sf,sr:} says that the terminal has
        !          2778: four function keys which mean ``clear screen'', ``home down'',
        !          2779: ``scroll forward'' and ``scroll reverse''.@refill
        !          2780: @end table
        !          2781: 
        !          2782: @node Meta Key, Initialization, Keypad, Capabilities
        !          2783: @section Meta Key
        !          2784: 
        !          2785: @cindex meta key
        !          2786: A Meta key is a key on the keyboard that modifies each character you type
        !          2787: by controlling the 0200 bit.  This bit is on if and only if the Meta key is
        !          2788: held down when the character is typed.  Characters typed using the Meta key
        !          2789: are called Meta characters.  Emacs uses Meta characters as editing
        !          2790: commands.
        !          2791: 
        !          2792: @table @samp
        !          2793: @item km
        !          2794: @kindex km
        !          2795: Flag whose presence means that the terminal has a Meta key.
        !          2796: 
        !          2797: @item mm
        !          2798: @kindex mm
        !          2799: String of commands to enable the functioning of the Meta key.
        !          2800: 
        !          2801: @item mo
        !          2802: @kindex mo
        !          2803: String of commands to disable the functioning of the Meta key.
        !          2804: @end table
        !          2805: 
        !          2806: If the terminal has @samp{km} but does not have @samp{mm} and @samp{mo}, it
        !          2807: means that the Meta key always functions.  If it has @samp{mm} and
        !          2808: @samp{mo}, it means that the Meta key can be turned on or off.  Send the
        !          2809: @samp{mm} string to turn it on, and the @samp{mo} string to turn it off.
        !          2810: I do not know why one would ever not want it to be on.
        !          2811: 
        !          2812: @node Initialization, Pad Specs, Meta Key, Capabilities
        !          2813: @section Initialization
        !          2814: @cindex reset
        !          2815: @cindex initialization
        !          2816: @cindex tab stops
        !          2817: 
        !          2818: @table @samp
        !          2819: @item ti
        !          2820: @kindex ti
        !          2821: String of commands to put the terminal into whatever special modes are
        !          2822: needed or appropriate for programs that move the cursor
        !          2823: nonsequentially around the screen.  Programs that use termcap to do
        !          2824: full-screen display should output this string when they start up.
        !          2825: 
        !          2826: @item te
        !          2827: @kindex te
        !          2828: String of commands to undo what is done by the @samp{ti} string.
        !          2829: Programs that output the @samp{ti} string on entry should output this
        !          2830: string when they exit.
        !          2831: 
        !          2832: @item is
        !          2833: @kindex is
        !          2834: String of commands to initialize the terminal for each login session.
        !          2835: 
        !          2836: @item if
        !          2837: @kindex if
        !          2838: String which is the name of a file containing the string of commands
        !          2839: to initialize the terminal for each session of use.  Normally @samp{is}
        !          2840: and @samp{if} are not both used.
        !          2841: 
        !          2842: @item i1
        !          2843: @itemx i3
        !          2844: @kindex i1
        !          2845: @kindex i3
        !          2846: Two more strings of commands to initialize the terminal for each login
        !          2847: session.  The @samp{i1} string (if defined) is output before @samp{is}
        !          2848: or @samp{if}, and the @samp{i3} string (if defined) is output after.
        !          2849: 
        !          2850: The reason for having three separate initialization strings is to make
        !          2851: it easier to define a group of related terminal types with slightly
        !          2852: different initializations.  Define two or three of the strings in the
        !          2853: basic type; then the other types can override one or two of the
        !          2854: strings.
        !          2855: 
        !          2856: @item rs
        !          2857: @kindex rs
        !          2858: String of commands to reset the terminal from any strange mode it may
        !          2859: be in.  Normally this includes the @samp{is} string (or other commands
        !          2860: with the same effects) and more.  What would go in the @samp{rs}
        !          2861: string but not in the @samp{is} string are annoying or slow commands
        !          2862: to bring the terminal back from strange modes that nobody would
        !          2863: normally use.
        !          2864: 
        !          2865: @item it
        !          2866: @kindex it
        !          2867: Numeric value, the initial spacing between hardware tab stop columns
        !          2868: when the terminal is powered up.  Programs to initialize the terminal
        !          2869: can use this to decide whether there is a need to set the tab stops.
        !          2870: If the initial width is 8, well and good; if it is not 8, then the
        !          2871: tab stops should be set; if they cannot be set, the kernel is told
        !          2872: to convert tabs to spaces, and other programs will observe this and do
        !          2873: likewise.
        !          2874: 
        !          2875: @item ct
        !          2876: @kindex ct
        !          2877: String of commands to clear all tab stops.
        !          2878: 
        !          2879: @item st
        !          2880: @kindex st
        !          2881: String of commands to set tab stop at current cursor column on all
        !          2882: lines.
        !          2883: @end table
        !          2884: 
        !          2885: @node Pad Specs, Status Line, Initialization, Capabilities
        !          2886: @section Padding Capabilities
        !          2887: @cindex padding
        !          2888: 
        !          2889: There are two terminal capabilities that exist just to explain the proper
        !          2890: way to obey the padding specifications in all the command string
        !          2891: capabilities.  One, @samp{pc}, must be obeyed by all termcap-using
        !          2892: programs.
        !          2893: 
        !          2894: @table @samp
        !          2895: @item pb
        !          2896: @kindex pb
        !          2897: Numeric value, the lowest baud rate at which padding is actually
        !          2898: needed.  Programs may check this and refrain from doing any padding at
        !          2899: lower speeds.
        !          2900: 
        !          2901: @item pc
        !          2902: @kindex pc
        !          2903: String of commands for padding.  The first character of this string is
        !          2904: to be used as the pad character, instead of using null characters for
        !          2905: padding.  If @samp{pc} is not provided, use null characters.  Every
        !          2906: program that uses termcap must look up this capability and use it to
        !          2907: set the variable @code{PC} that is used by @code{tputs}.
        !          2908: @xref{Padding}.
        !          2909: @end table
        !          2910: 
        !          2911: Some termcap capabilities exist just to specify the amount of padding that
        !          2912: the kernel should give to cursor motion commands used in ordinary
        !          2913: sequential output.
        !          2914: 
        !          2915: @table @samp
        !          2916: @item dC
        !          2917: @kindex dC
        !          2918: Numeric value, the number of msec of padding needed for the
        !          2919: carriage-return character.
        !          2920: 
        !          2921: @item dN
        !          2922: @kindex dN
        !          2923: Numeric value, the number of msec of padding needed for the newline
        !          2924: (linefeed) character.
        !          2925: 
        !          2926: @item dB
        !          2927: @kindex dB
        !          2928: Numeric value, the number of msec of padding needed for the backspace
        !          2929: character.
        !          2930: 
        !          2931: @item dF
        !          2932: @kindex dF
        !          2933: Numeric value, the number of msec of padding needed for the formfeed
        !          2934: character.
        !          2935: 
        !          2936: @item dT
        !          2937: @kindex dT
        !          2938: Numeric value, the number of msec of padding needed for the tab
        !          2939: character.
        !          2940: @end table
        !          2941: 
        !          2942: In some systems, the kernel uses the above capabilities; in other systems,
        !          2943: the kernel uses the paddings specified in the string capabilities
        !          2944: @samp{cr}, @samp{sf}, @samp{le}, @samp{ff} and @samp{ta}.  Descriptions of
        !          2945: terminals which require such padding should contain the @samp{dC} @dots{}
        !          2946: @samp{dT} capabilities and also specify the appropriate padding in the
        !          2947: corresponding string capabilities.  Since no modern terminals require
        !          2948: padding for ordinary sequential output, you probably won't need to do
        !          2949: either of these things.
        !          2950: 
        !          2951: @node Status Line, Half-Line, Pad Specs, Capabilities
        !          2952: @section Status Line
        !          2953: 
        !          2954: @cindex status line
        !          2955: A @dfn{status line} is a line on the terminal that is not used for ordinary
        !          2956: display output but instead used for a special message.  The intended use is
        !          2957: for a continuously updated description of what the user's program is doing,
        !          2958: and that is where the name ``status line'' comes from, but in fact it could
        !          2959: be used for anything.  The distinguishing characteristic of a status line
        !          2960: is that ordinary output to the terminal does not affect it; it changes only
        !          2961: if the special status line commands of this section are used.
        !          2962: 
        !          2963: @table @samp
        !          2964: @item hs
        !          2965: @kindex hs
        !          2966: Flag whose presence means that the terminal has a status line.  If a
        !          2967: terminal description specifies that there is a status line, it must
        !          2968: provide the @samp{ts} and @samp{fs} capabilities.
        !          2969: 
        !          2970: @item ts
        !          2971: @kindex ts
        !          2972: String of commands to move the terminal cursor into the status line.
        !          2973: Usually these commands must specifically record the old cursor
        !          2974: position for the sake of the @samp{fs} string.
        !          2975: 
        !          2976: @item fs
        !          2977: @kindex fs
        !          2978: String of commands to move the cursor back from the status line to its
        !          2979: previous position (outside the status line).
        !          2980: 
        !          2981: @item es
        !          2982: @kindex es
        !          2983: Flag whose presence means that other display commands work while
        !          2984: writing the status line.  In other words, one can clear parts of it,
        !          2985: insert or delete characters, move the cursor within it using @samp{ch}
        !          2986: if there is a @samp{ch} capability, enter and leave standout mode, and
        !          2987: so on.
        !          2988: 
        !          2989: @item ds
        !          2990: @kindex ds
        !          2991: String of commands to disable the display of the status line.  This
        !          2992: may be absent, if there is no way to disable the status line display.
        !          2993: 
        !          2994: @item ws
        !          2995: @kindex ws
        !          2996: Numeric value, the width of the status line.  If this capability is
        !          2997: absent in a terminal that has a status line, it means the status line
        !          2998: is the same width as the other lines.
        !          2999: 
        !          3000: Note that the value of @samp{ws} is sometimes as small as 8.
        !          3001: @end table
        !          3002: 
        !          3003: @node Half-Line, Printer, Status Line, Capabilities
        !          3004: @section Half-Line Motion
        !          3005: 
        !          3006: Some terminals have commands for moving the cursor vertically by half-lines,
        !          3007: useful for outputting subscripts and superscripts.  Mostly it is hardcopy
        !          3008: terminals that have such features.
        !          3009: 
        !          3010: @table @samp
        !          3011: @item hu
        !          3012: @kindex hu
        !          3013: String of commands to move the cursor up half a line.  If the terminal
        !          3014: is a display, it is your responsibility to avoid moving up past the
        !          3015: top line; however, most likely the terminal that supports this is a
        !          3016: hardcopy terminal and there is nothing to be concerned about.
        !          3017: 
        !          3018: @item hd
        !          3019: @kindex hd
        !          3020: String of commands to move the cursor down half a line.  If the
        !          3021: terminal is a display, it is your responsibility to avoid moving down
        !          3022: past the bottom line, etc.
        !          3023: @end table
        !          3024: 
        !          3025: @node Printer,, Half-Line, Capabilities
        !          3026: @section Controlling Printers Attached to Terminals
        !          3027: @cindex printer
        !          3028: 
        !          3029: Some terminals have attached hardcopy printer ports.  They may be able to
        !          3030: copy the screen contents to the printer; they may also be able to redirect
        !          3031: output to the printer.  Termcap does not have anything to tell the program
        !          3032: whether the redirected output appears also on the screen; it does on some
        !          3033: terminals but not all.
        !          3034: 
        !          3035: @table @samp
        !          3036: @item ps
        !          3037: @kindex ps
        !          3038: String of commands to cause the contents of the screen to be printed.
        !          3039: If it is absent, the screen contents cannot be printed.
        !          3040: 
        !          3041: @item po
        !          3042: @kindex po
        !          3043: String of commands to redirect further output to the printer.
        !          3044: 
        !          3045: @item pf
        !          3046: @kindex pf
        !          3047: String of commands to terminate redirection of output to the printer.
        !          3048: This capability must be present in the description if @samp{po} is.
        !          3049: 
        !          3050: @item pO
        !          3051: @kindex pO
        !          3052: String of commands to redirect output to the printer for next @var{n}
        !          3053: characters of output, regardless of what they are.  Redirection will
        !          3054: end automatically after @var{n} characters of further output.  Until
        !          3055: then, nothing that is output can end redirection, not even the
        !          3056: @samp{pf} string if there is one.  The number @var{n} should not be
        !          3057: more than 255.
        !          3058: 
        !          3059: One use of this capability is to send non-text byte sequences (such as
        !          3060: bit-maps) to the printer.
        !          3061: @end table
        !          3062: 
        !          3063: Most terminals with printers do not support all of @samp{ps}, @samp{po} and
        !          3064: @samp{pO}; any one or two of them may be supported.  To make a program that
        !          3065: can send output to all kinds of printers, it is necessary to check for all
        !          3066: three of these capabilities, choose the most convenient of the ones that
        !          3067: are provided, and use it in its own appropriate fashion.
        !          3068: 
        !          3069: @node Summary, Var Index, Capabilities, Top
        !          3070: @chapter Summary of Capability Names
        !          3071: 
        !          3072: Here are all the terminal capability names in alphabetical order
        !          3073: with a brief description of each.  For cross references to their definitions,
        !          3074: see the index of capability names (@pxref{Cap Index}).
        !          3075: 
        !          3076: @table @samp
        !          3077: @item ae
        !          3078: String to turn off alternate character set mode.
        !          3079: @item al
        !          3080: String to insert a blank line before the cursor.
        !          3081: @item AL
        !          3082: String to insert @var{n} blank lines before the cursor.
        !          3083: @item am
        !          3084: Flag: output to last column wraps cursor to next line.
        !          3085: @item as
        !          3086: String to turn on alternate character set mode.like.
        !          3087: @item bc
        !          3088: Very obsolete alternative name for the @samp{le} capability.
        !          3089: @item bl
        !          3090: String to sound the bell.
        !          3091: @item bs
        !          3092: Obsolete flag: ASCII backspace may be used for leftward motion.
        !          3093: @item bt
        !          3094: String to move the cursor left to the previous hardware tab stop column.
        !          3095: @item bw
        !          3096: Flag: @samp{le} at left margin wraps to end of previous line.
        !          3097: @item CC
        !          3098: String to change terminal's command character.
        !          3099: @item cd
        !          3100: String to clear the line the cursor is on, and following lines.
        !          3101: @item ce
        !          3102: String to clear from the cursor to the end of the line.
        !          3103: @item ch
        !          3104: String to position the cursor at column @var{c} in the same line.
        !          3105: @item cl
        !          3106: String to clear the entire screen and put cursor at upper left corner.
        !          3107: @item cm
        !          3108: String to position the cursor at line @var{l}, column @var{c}.
        !          3109: @item CM
        !          3110: String to position the cursor at line @var{l}, column
        !          3111: @var{c}, relative to display memory.
        !          3112: @item co
        !          3113: Number: width of the screen.
        !          3114: @item cr
        !          3115: String to move cursor sideways to left margin.
        !          3116: @item cs
        !          3117: String to set the scroll region.
        !          3118: @item cS
        !          3119: Alternate form of string to set the scroll region.
        !          3120: @item ct
        !          3121: String to clear all tab stops.
        !          3122: @item cv
        !          3123: String to position the cursor at line @var{l} in the same column.
        !          3124: @item da
        !          3125: Flag: data scrolled off top of screen may be scrolled back.
        !          3126: @item db
        !          3127: Flag: data scrolled off bottom of screen may be scrolled back.
        !          3128: @item dB
        !          3129: Obsolete number: msec of padding needed for the backspace character.
        !          3130: @item dc
        !          3131: String to delete one character position at the cursor.
        !          3132: @item dC
        !          3133: Obsolete number: msec of padding needed for the carriage-return character.
        !          3134: @item DC
        !          3135: String to delete @var{n} characters starting at the cursor.
        !          3136: @item dF
        !          3137: Obsolete number: msec of padding needed for the formfeed character.
        !          3138: @item dl
        !          3139: String to delete the line the cursor is on.
        !          3140: @item DL
        !          3141: String to delete @var{n} lines starting with the cursor's line.
        !          3142: @item dm
        !          3143: String to enter delete mode.
        !          3144: @item dN
        !          3145: Obsolete number: msec of padding needed for the newline character.
        !          3146: @item do
        !          3147: String to move the cursor vertically down one line.
        !          3148: @item DO
        !          3149: String to move cursor vertically down @var{n} lines.
        !          3150: @item ds
        !          3151: String to disable the display of the status line.
        !          3152: @item dT
        !          3153: Obsolete number: msec of padding needed for the tab character.
        !          3154: @item ec
        !          3155: String of commands to clear @var{n} characters at cursor.
        !          3156: @item ed
        !          3157: String to exit delete mode.
        !          3158: @item ei
        !          3159: String to leave insert mode.
        !          3160: @item eo
        !          3161: Flag: output of a space can erase an overstrike.
        !          3162: @item es
        !          3163: Flag: other display commands work while writing the status line.
        !          3164: @item ff
        !          3165: String to advance to the next page, for a hardcopy terminal.
        !          3166: @item fs
        !          3167: String to move the cursor back from the status line to its
        !          3168: previous position (outside the status line).
        !          3169: @item gn
        !          3170: Flag: this terminal type is generic, not real.
        !          3171: @item hc
        !          3172: Flag: hardcopy terminal.
        !          3173: @item hd
        !          3174: String to move the cursor down half a line.
        !          3175: @item ho
        !          3176: String to position cursor at upper left corner.
        !          3177: @item hs
        !          3178: Flag: the terminal has a status line.
        !          3179: @item hu
        !          3180: String to move the cursor up half a line.
        !          3181: @item hz
        !          3182: Flag: terminal cannot accept @samp{~} as output.
        !          3183: @item i1
        !          3184: String to initialize the terminal for each login session.
        !          3185: @item i3
        !          3186: String to initialize the terminal for each login session.
        !          3187: @item ic
        !          3188: String to insert one character position at the cursor.
        !          3189: @item IC
        !          3190: String to insert @var{n} character positions at the cursor.
        !          3191: @item if
        !          3192: String naming a file of commands to initialize the terminal.
        !          3193: @item im
        !          3194: String to enter insert mode.
        !          3195: @item in
        !          3196: Flag: outputting a space is different from moving over empty positions.
        !          3197: @item ip
        !          3198: String to output following an inserted character in insert mode.
        !          3199: @item is
        !          3200: String to initialize the terminal for each login session.
        !          3201: @item it
        !          3202: Number: initial spacing between hardware tab stop columns.
        !          3203: @item k0
        !          3204: String of input sent by function key 0 or 10.
        !          3205: @item k1 @dots{} k9
        !          3206: Strings of input sent by function keys 1 through 9.
        !          3207: @item K1 @dots{} K5
        !          3208: Strings sent by the five other keys in 3-by-3 array with arrows.
        !          3209: @item ka
        !          3210: String of input sent by the ``clear all tabs'' key.
        !          3211: @item kA
        !          3212: String of input sent by the ``insert line'' key.
        !          3213: @item kb
        !          3214: String of input sent by the ``backspace'' key.
        !          3215: @item kC
        !          3216: String of input sent by the ``clear screen'' key.
        !          3217: @item kd
        !          3218: String of input sent by typing the down-arrow key.
        !          3219: @item kD
        !          3220: String of input sent by the ``delete character'' key.
        !          3221: @item ke
        !          3222: String to make the function keys work locally.
        !          3223: @item kE
        !          3224: String of input sent by the ``clear to end of line'' key.
        !          3225: @item kF
        !          3226: String of input sent by the ``scroll forward'' key.
        !          3227: @item kh
        !          3228: String of input sent by typing the ``home-position'' key.
        !          3229: @item kH
        !          3230: String of input sent by the ``home down'' key.
        !          3231: @item kI
        !          3232: String of input sent by the ``insert character'' or ``enter
        !          3233: insert mode'' key.
        !          3234: @item kl
        !          3235: String of input sent by typing the left-arrow key.
        !          3236: @item kL
        !          3237: String of input sent by the ``delete line'' key.
        !          3238: @item km
        !          3239: Flag: the terminal has a Meta key.
        !          3240: @item kM
        !          3241: String of input sent by the ``exit insert mode'' key.
        !          3242: @item kn
        !          3243: Numeric value, the number of numbered function keys.
        !          3244: @item kN
        !          3245: String of input sent by the ``next page'' key.
        !          3246: @item ko
        !          3247: Very obsolete string listing the terminal's named function keys.
        !          3248: @item kP
        !          3249: String of input sent by the ``previous page'' key.
        !          3250: @item kr
        !          3251: String of input sent by typing the right-arrow key.
        !          3252: @item kR
        !          3253: String of input sent by the ``scroll reverse'' key.
        !          3254: @item ks
        !          3255: String to make the function keys transmit.
        !          3256: @item kS
        !          3257: String of input sent by the ``clear to end of screen'' key.
        !          3258: @item kt
        !          3259: String of input sent by the ``clear tab stop this column'' key.
        !          3260: @item kT
        !          3261: String of input sent by the ``set tab stop in this column'' key.
        !          3262: @item ku
        !          3263: String of input sent by typing the up-arrow key.
        !          3264: @item l0
        !          3265: String on keyboard labelling function key 0 or 10.
        !          3266: @item l1 @dots{} l9
        !          3267: Strings on keyboard labelling function keys 1 through 9.
        !          3268: @item le
        !          3269: String to move the cursor left one column.
        !          3270: @item LE
        !          3271: String to move cursor left @var{n} columns.
        !          3272: @item li
        !          3273: Number: height of the screen.
        !          3274: @item ll
        !          3275: String to position cursor at lower left corner.
        !          3276: @item lm
        !          3277: Number: lines of display memory.
        !          3278: @item mb
        !          3279: String to enter blinking mode.
        !          3280: @item md
        !          3281: String to enter double-bright mode.
        !          3282: @item me
        !          3283: String to turn off all appearance modes
        !          3284: @item mh
        !          3285: String to enter half-bright mode.
        !          3286: @item mi
        !          3287: Flag: cursor motion in insert mode is safe.
        !          3288: @item mk
        !          3289: String to enter invisible mode.
        !          3290: @item mm
        !          3291: String to enable the functioning of the Meta key.
        !          3292: @item mo
        !          3293: String to disable the functioning of the Meta key.
        !          3294: @item mp
        !          3295: String to enter protected mode.
        !          3296: @item mr
        !          3297: String to enter reverse-video mode.
        !          3298: @item ms
        !          3299: Flag: cursor motion in standout mode is safe.
        !          3300: @item nc
        !          3301: Obsolete flag: do not use ASCII carriage-return on this terminal.
        !          3302: @item nd
        !          3303: String to move the cursor right one column.
        !          3304: @item nl
        !          3305: Obsolete alternative name for the @samp{do} and @samp{sf} capabilities.
        !          3306: @item ns
        !          3307: Flag: the terminal does not normally scroll for sequential output.
        !          3308: @item nw
        !          3309: String to move to start of next line, possibly clearing rest of old line.
        !          3310: @item os
        !          3311: Flag: terminal can overstrike.
        !          3312: @item pb
        !          3313: Number: the lowest baud rate at which padding is actually needed.
        !          3314: @item pc
        !          3315: String containing character for padding.
        !          3316: @item pf
        !          3317: String to terminate redirection of output to the printer.
        !          3318: @item po
        !          3319: String to redirect further output to the printer.
        !          3320: @item pO
        !          3321: String to redirect @var{n} characters ofoutput to the printer.
        !          3322: @item ps
        !          3323: String to print the screen on the attached printer.
        !          3324: @item rc
        !          3325: String to move to last saved cursor position.
        !          3326: @item RI
        !          3327: String to move cursor right @var{n} columns.
        !          3328: @item rp
        !          3329: String to output character @var{c} repeated @var{n} times.
        !          3330: @item rs
        !          3331: String to reset the terminal from any strange modes.
        !          3332: @item sa
        !          3333: String to turn on an arbitrary combination of appearance modes.
        !          3334: @item sc
        !          3335: String to save the current cursor position.
        !          3336: @item se
        !          3337: String to leave standout mode.
        !          3338: @item sf
        !          3339: String to scroll the screen one line up.
        !          3340: @item SF
        !          3341: String to scroll the screen @var{n} lines up.
        !          3342: @item sg
        !          3343: Number: width of magic standout cookie.  Absent if magic cookies are
        !          3344: not used.
        !          3345: @item so
        !          3346: String to enter standout mode.
        !          3347: @item sr
        !          3348: String to scroll the screen one line down.
        !          3349: @item SR
        !          3350: String to scroll the screen @var{n} line down.
        !          3351: @item st
        !          3352: String to set tab stop at current cursor column on all lines.
        !          3353: programs.
        !          3354: @item ta
        !          3355: String to move the cursor right to the next hardware tab stop column.
        !          3356: @item te
        !          3357: String to return terminal to settings for sequential output.
        !          3358: @item ti
        !          3359: String to initialize terminal for random cursor motion.
        !          3360: @item ts
        !          3361: String to move the terminal cursor into the status line.
        !          3362: @item uc
        !          3363: String to underline one character and move cursor right.
        !          3364: @item ue
        !          3365: String to turn off underline mode
        !          3366: @item ug
        !          3367: Number: width of underlining magic cookie.  Absent if underlining
        !          3368: doesn't use magic cookies.
        !          3369: @item ul
        !          3370: Flag: underline by overstriking with an underscore.
        !          3371: @item up
        !          3372: String to move the cursor vertically up one line.
        !          3373: @item UP
        !          3374: String to move cursor vertically up @var{n} lines.
        !          3375: @item us
        !          3376: String to turn on underline mode
        !          3377: @item vb
        !          3378: String to make the screen flash.
        !          3379: @item ve
        !          3380: String to return the cursor to normal.
        !          3381: @item vi
        !          3382: String to make the cursor invisible.
        !          3383: @item vs
        !          3384: String to enhance the cursor.
        !          3385: @item wi
        !          3386: String to set the terminal output screen window.
        !          3387: @item ws
        !          3388: Number: the width of the status line.
        !          3389: @item xb
        !          3390: Flag: superbee terminal.
        !          3391: @item xn
        !          3392: Flag: cursor wraps in a strange way.
        !          3393: @item xs
        !          3394: Flag: clearing a line is the only way to clear the appearance modes of
        !          3395: positions in that line (or, only way to remove magic cookies on that
        !          3396: line).
        !          3397: @item xt
        !          3398: Flag: Teleray 1061; several strange characteristics.
        !          3399: @end table
        !          3400: 
        !          3401: @node Var Index, Cap Index, Summary, Top
        !          3402: @unnumbered Variable and Function Index
        !          3403: 
        !          3404: @printindex fn
        !          3405: 
        !          3406: @node Cap Index, Index, Var Index, Top
        !          3407: @unnumbered Capability Index
        !          3408: 
        !          3409: @printindex ky
        !          3410: 
        !          3411: @node Index,, Cap Index, Top
        !          3412: @unnumbered Concept Index
        !          3413: 
        !          3414: @printindex cp
        !          3415: 
        !          3416: @contents
        !          3417: @bye

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.